Tube Site Script
Design

Creating a child template: inherit a parent, override views and add your own CSS

Build a child template that inherits from a parent: folder layout, template.json settings, stacked CSS, overriding a view and keeping JavaScript hooks.

Updated 4 minute read The Tube Site Script team

A child template is a template that names another template as its parent and only contains the files you want to change. Anything it does not have, such as views, scripts or images, is taken from the parent, so you can restyle a site or rewrite one page without copying the whole template. In Tube Site Script the smallest working child template is a template.json file and one stylesheet.

Why use a child template

Editing a bundled template directly is a common mistake. The next update replaces those files and your changes are gone. A child template keeps your work separate:

  • Updates to the parent reach your sites automatically, including fixes.
  • You only maintain the handful of files you changed.
  • You can build several children from the same parent for different sites in a network.

If you are still deciding on a look, read choosing and customising a tube site design first.

The folder structure

A template is a folder inside templates/:

  • template.json with the name, description, parent and settings
  • views/*.php for the page files you change
  • assets/css/style.css, plus any JavaScript or images in assets/
  • screenshot.jpg at 960 by 600 pixels, shown in the admin

The easiest way to start is Admin › Templates › Create a template, based on any existing template, and then add files in the browser editor.

How inheritance works

Set "parent" to stream, classic, mosaic or another template. When a page is rendered, each view or asset is looked up in your template first, then its parent, then the parent's parent, ending at Stream. Stylesheets stack rather than replace each other: css/style.css is loaded from every template in the chain, parent first, followed by the site's settings as CSS variables, then the site's custom CSS. Your CSS only needs to contain the differences.

Writing template.json

Here is a small example for a child of Classic that adds two settings (shown on one line; normal indentation works too):

{"name": "Classic Blue", "version": "1.0", "author": "You", "description": "Classic with a blue accent and adjustable grid gap", "parent": "classic", "settings": [{"key": "accent", "label": "Accent colour", "type": "color", "default": "#1f6feb", "css_var": "--accent", "group": "Colours"}, {"key": "gap", "label": "Grid gap", "type": "number", "default": 12, "min": 0, "max": 40, "unit": "px", "css_var": "--gap", "group": "Layout"}]}

This names Classic as the parent, changes the default accent colour, and adds a grid gap setting that sites can adjust from 0 to 40 pixels.

Points to know about settings:

  • Types are color, toggle, select, number, text and textarea.
  • Settings appear automatically under Sites › Appearance for every site using the template, grouped by group. Each site keeps its own values.
  • A child inherits all its parent's settings. List a key again to change its default or label.
  • css_var publishes the value as a CSS custom property, with unit appended for numbers.
  • In a view, read a value with tpl('key'). It always returns a string, and toggles return '1' or '0'.

Adding your CSS

Create assets/css/style.css and write only the overrides. Using the variables published by settings keeps the stylesheet short and lets each site adjust values without touching code. For example:

  • .grid { gap: var(--gap); }
  • .card .title { font-weight: 600; }
  • a, .btn-primary { color: var(--accent); }

For one-off changes on a single site, the per-site custom CSS box is often enough and needs no template at all.

Overriding a view

To change the markup of one part of a page, add a file with the same name to your views/ folder. Common choices are _card (one video card), video (the video page) and layout (the page frame). When you open a view your template does not have yet, the browser editor shows the inherited version, so you can copy it and edit from there. The editor checks PHP syntax before saving.

A few rules keep things working:

  • Escape everything you print with e().
  • Use helpers such as video_url($v), App\Media::thumb($v) and App\Ads::zone('header') instead of building URLs by hand.
  • Keep the hooks the built-in JavaScript relies on, for example .card[data-id] with .thumb[data-preview] on cards, #player on the video page, and #ageGate with #ageYes for the age gate. If you override layout, keep the app.js script tag and the window.TUBE line from Stream.

Testing and sharing

Preview the template on a site with a private preview link before switching the site over, and check the home page, a category page, a video page and the member pages on a phone. When you are happy, Export .zip gives you one folder you can back up or install elsewhere with Install from .zip. Templates contain PHP, so only install templates from people you trust.

How Tube Site Script helps

Tube Site Script supports child templates throughout: inheritance from Stream, Classic, Mosaic or your own templates, stacked stylesheets, settings that show up per site under Appearance, an in-browser editor with PHP syntax checking, duplication, and zip export and import. Bundled templates are read-only so updates never overwrite your work, and admins can switch the browser editor off in Network settings if they prefer to deploy files another way.

Because every site in a network chooses its own template and settings, one child template can give several sites a shared base while each keeps its own colours and logo. See the Tube Site Script features or go straight to pricing.

Frequently asked questions

What is the smallest possible child template?

A template.json that names a parent and an assets/css/style.css file. Every view and asset you leave out is taken from the parent.

Will updates overwrite my child template?

No. Updates replace the bundled templates, not yours, so keep your own template folders when you upload new files.

How do I read a template setting in a view?

Call tpl('key') with the setting's key. The value is always returned as a string, with toggles giving '1' or '0'.

Get three guides like this every month, plus software update notices.Subscribe →