Themes and templates: Changing the look and feel of your site (v2)
9 April 2022 522 views | Documentation v2
The theme system
The layout and appearance of your site is defined through the use of "themes” (Bootstrap templates) each of which resides in a separate folder in the /themes directory. Themes can be applied on a per-page basis, so you can have a completely different layout, look and feel in different areas of your site. On every page, actually.
Tuskfish ships with a couple of Bootstrap example themes as starting points to create your own designs. These are quite plain, but there are many third-party sites that offer free themes with more visual ‘bling’, or that you can buy (a word of warning, in my experience the official getbootstrap.com site does not respond to support requests).
What is this Bootstrap of which you speak?
Bootstrap is a mainstream front-end presentation framework of HTML, CSS and Javascript. It excels at building responsive, mobile-first websites that work across different sized devices, and can turn basic HTML into a beautiful site with the application of a few classes.
Bootstrap is very well documented. If you plan to tinker with the look and feel of your site then it is worthwhile to take a look at the documentation and familiarise yourself with the layout grid concept and the core classes that are available.
As Bootstrap is a mainstream presentation framework there are literally hundreds of third-party themes available (both free and paid), and it only takes a few minutes to convert one for use with Tuskfish. Basically it’s just a case of inserting your PHP output (variables) into the appropriate places in the template.
Adding a new theme to your site
Simply upload your new theme to the /themes directory to make it available for use. You will need to assign it to the pages you where you want to use it (see below).
Customising the default theme
The default theme comes with a few link placeholders in the navigation menu, to give you the idea that you can change things. To rename a link and point it to a page - or to add more links - open /themes/default/layout.html and change it to suit your needs. If you would like instruction, please see the Bootstrap documentation or their example templates, which illustrate most of the available Bootstrap components, you can cut and paste what you need. To modify the look and feel edit /themes/default/style.css. See also the section on Anatomy of the Default Theme.
Changing the default theme
Tuskfish ships with a 'default' theme, which will be used for every page (except for the admin pages, which use the 'admin' theme) unless you specify otherwise. If you would prefer to use something else as the sitewide default, simply:
- Rename the 'default' theme directory to something else (eg. default_bak), and then change the name of the theme you want to use in its place to 'default'.
- Look inside the new 'default' directory and edit layout.html. Change the path of the link to style.css in the header to match the new directory name, which is now 'default'.
The new default theme will now be applied to your entire site, except for pages where you have manually specified something else. In the near future a preference will be added that allows you to change the default theme through the admin panel.
Overriding the default theme for a particular page
Alternatively, you can just specify the theme you want to use on any given page. The theme is usually set in the viewModel for a particular page, but you can also override it there or in the controller using the setTheme() function, passing in the directory name for your new theme:
// viewModels are found in trust_path/libraries/tuskfish/class/Tfish/Content/ViewModel and .../Tfish/ViewModel
// In a controller, make this call to override the theme:
$this->viewModel->setTheme('myNewTheme');
// Controllers are found in trust_path/libraries/tuskfish/class/Tfish/Content/Controller and .../Tfish/Controller
// In a viewModel, alter the call below to change the theme:
$tfTemplate->setTheme('myNewTheme');
You can use a different theme on every page, if you want to. You can even use different themes on the one page, varying them according to programmatic conditions using either the controller or viewModel.
Creating (cloning) a new theme
To create a new theme from an existing one, simply:
- Copy one of the existing theme directories (eg. ‘default’) and give it a new name (eg. 'vanilla').
- Edit layout.html and point the link to style.css to point to the new directory name, eg, change:
<!-- Custom styles for this template -->
<link href="<?php echo TFISH_THEMES_URL . 'default/style.css'; ?>" rel="stylesheet">
To something like:
<!-- Custom styles for this template -->
<link href="<?php echo TFISH_THEMES_URL . 'vanilla/style.css'; ?>" rel="stylesheet">
That's it! You now have a new theme that you can modify to your heart's content without affecting the old one. To use the new theme simply declare it in the page(s) you wish to use it on, as described above.
Copyright, all rights reserved.