Welcome to The Cookbook

You can take advantage of themes, making it easy to switch the look and feel of your page quickly and easily.

To use themes, you need to tell your controller to use the ThemeView class instead of the default View class.

class ExampleController extends AppController {
    var $view = 'Theme';
}

1. class ExampleController extends AppController {
2. var $view = 'Theme';
3. }

To declare which theme to use by default, specify the theme name in your controller.

class ExampleController extends AppController {
    var $view = 'Theme';
    var $theme = 'example';
}

1. class ExampleController extends AppController {
2. var $view = 'Theme';
3. var $theme = 'example';
4. }

You can also set or change the theme name within an action or within the beforeFilter or beforeRender callback functions.

$this->theme = 'another_example';

1. $this->theme = 'another_example';

Theme view files need to be within the /app/views/themed/ folder. Within the themed folder, create a folder using the same name as your theme name. Beyond that, the folder structure within the /app/views/themed/example/ folder is exactly the same as /app/views/.

For example, the view file for an edit action of a Posts controller would reside at /app/views/themed/example/posts/edit.ctp. Layout files would reside in /app/views/themed/example/layouts/.

If a view file can't be found in the theme, CakePHP will try to locate the view file in the /app/views/ folder. This way, you can create master view files and simply override them on a case-by-case basis within your theme folder.

Theme assets

In previous versions themes needed to be split into their view and asset parts. New for 1.3 is a webroot directory as part of a theme. This webroot directory can contain any static assets that are included as part of your theme. Allowing the theme webroot to exist inside the views directory allows themes to be packaged far easier than before.

Linking to static assets is slightly different from 1.2. You can still use the existing app/webroot/themed and directly link to those static files. It should be noted that you will need to use the full path to link to assets in app/webroot/themed. If you want to keep your theme assets inside app/webroot it is recommended that you rename app/webroot/themed to app/webroot/theme. This will allow you to leverage the core helper path finding. As well as keep the performance benefits of not serving assets through PHP.

To use the new theme webroot create directories like theme/<theme_name>/webroot<path_to_file> in your theme. The Dispatcher will handle finding the correct theme assets in your view paths.

All of CakePHP's built-in helpers are aware of themes and will create the correct paths automatically. Like view files, if a file isn't in the theme folder, it'll default to the main webroot folder.

//When in a theme with the name of 'purple_cupcake'
$this->Html->css('main.css');
 
//creates a path like
/theme/purple_cupcake/css/main.css
 
//and links to
app/views/themed/purple_cupcake/webroot/css/main.css 

1. //When in a theme with the name of 'purple_cupcake'
2. $this->Html->css('main.css');
4. //creates a path like
5. /theme/purple_cupcake/css/main.css
7. //and links to
8. app/views/themed/purple_cupcake/webroot/css/main.css