This is my implementation of a themeable view class for CakePHP. This class will allow your site to use themes or skins. Themes or skins are a great feature because they allow for division of labor between the developer and the designer (although the designer in this case has to know a bit of PHP). They also allow the website owner to quickly change the look and feel of the website.

The ThemeableView class here is part of the CMS that I am currently working on.

Updated to Version 1.0.6

See this usage notes for CakePHP 1.2.x.x users.

Download the package here:

ThemeableView-1.0.6.zip

What's new in 1.0.6?

Yes, I am aware of another themeable view class for CakePHP which can be found here. However there are two problems that I have with that implementation which forced me to write my own class:

1. The class file is licensed under the OPPL. As far as I can tell, the OPPL seems to prohibit commercial use (see OPPL Section 3b and Section 4a).

   It is also unclear whether or not the OPPL is viral when OPPL licensed code is used to create a “Combined Work”. It is also unclear how the OPPL interacts with the GPL, LGPL and other licenses.

   I have written to Larry E. Masters about this but I have not gotten any response from him so far.

2. Theme elements are spread out in separate directories under app/views. This makes it less than ideal for large sites with a lot of controllers and actions.

For instance, if you have a theme named ‘MyTheme’ you will have to create the following directory structure in app/views:

app/views/elements/MyTheme
app/views/errors/MyTheme
app/views/layouts/MyTheme
app/views/controller_name/MyTheme

The first three directories present very little problems. However, with several controllers it will be taxing to have to create a MyTheme folder for each controller. Things get even messier when you use plugins:

app/plugins/MyPlugin/views/elements/MyTheme
app/plugins/MyPlugin/views/errors/MyTheme
app/plugins/MyPlugin/views/layouts/MyTheme
app/plugins/MyPlugin/views/controller_name/MyTheme

This can be a nightmare for theme maintainers since there can be a lot of themeable elements to keep track of and they are all over the place.

My implementation solves problem #1 by licensing ThemeableView under the MIT License. This is the same license used by CakePHP itself. Which means you can do pretty much anything with this code: use it in commercial apps, sublicense it (change the license terms), use it to bring world peace…

The only thing the MIT License disallows you to do is to remove the copyright notice from the code.

If you look at the code for the class itself, you will notice that it sort of resembles phpnut’s code. Before you go off and yell profanities at me, you should know that I contributed to phpnut’s ThemeView as well. Another thing is that my code is based on the View class itself, being that ThemeView and View are written by the same person, then there is bound to be similarities. This is aside from the fact that with the way CakePHP is structured, it is very hard to produce truly unique code.

For problem #2, all themes are placed in a themes directory under the app/ directory. Each theme is in its own directory. So using the MyTheme example above:

app/themes/MyTheme/views/elements
app/themes/MyTheme/views/errors
app/themes/MyTheme/views/layouts
app/themes/MyTheme/views/controller_name

Even with plugins:

app/themes/MyTheme/plugins/MyPlugin/views/elements
app/themes/MyTheme/plugins/MyPlugin/views/errors
app/themes/MyTheme/plugins/MyPlugin/views/layouts
app/themes/MyTheme/plugins/MyPlugin/views/controller_name

Everything that the theme requires to render all the views in your app is placed inside the MyTheme directory. In addition, you can also include other resources with the theme such as images, icons, Javascript, and CSS stylesheets. These need to be placed in a location that is accessible on your webserver. This means you should place theme resources under the themes/MyTheme directory in your webroot directory. For example, if your webroot is under your app (as in the default setup):

app/webroot/themes/MyTheme/css
app/webroot/themes/MyTheme/js
app/webroot/themes/MyTheme/images
app/webroot/themes/MyTheme/icons

Then from your templates, simply do:

<link href="<? $this->getThemeablePath('css', 'mystyle.css') ?>" type="text/css" rel="stylesheet" />
<script language="Javascript" type="text/javascript" src="<? $this->getThemeablePath('js', 'myscripts.js') ?>" />
<img src="<? $this-/>getThemeablePath('images', 'myimage.gif') ?>" />
<img src="<? $this-/>getThemeablePath('icons', 'myicon.gif') ?>" />

New in 1.0.4

As of version 1.0.4, a new ThemeHelper class is available. This class contains theme-aware versions of the css() and image() methods found in the HtmlHelper class. You can use this instead of having to write the tags by hand as above. See the ThemeHelper PHPDocs for details.

To use this class, place the file named themeable.php inside app/views.

Then, from your controller set view to "Themeable". Then set the current theme as a property themeName:

var $view = 'Themeable';
var $themeName = 'MyTheme';

Or you can create your own app_controller class and define the view and themeName properties so that all controllers in your application will be using them.

There are two constants that point to the location of your themes and theme resources.

• THEMES - point to the absolute path on your webserver's filesystem where your theme templates are stored.

  Default: APP . 'themes' . DS

• THEME_RESOURCES - point to the relative path on your website's URL where your theme resources are stored.

  Default: DS . 'themes' . DS

You can define these to point elsewhere depending on your setup.

I hope someone finds this useful. If you have any questions or comments please leave them on this post. My apologies for the slight inconvenience of required registration. There has been a string of spambot activity on my site recently.

If you have patches to this code, they are very much welcome. Send them to:

nimrod.abing+blog@gmail.com

Please use the subject line:

PATCH: ThemeableView class

Notes For CakePHP 1.2.x.x

This one comes from PJ Hile. Some API changes have taken place in CakePHP 1.2.x.x and naturally this equates to some changes in the themable view class as well. However, at the time of this update (13 Jun 2007) CakePHP 1.2.x.x is still in Alpha stage. That pretty much means that the API is still subject to change so this may or may not work for you depending on your current 1.2.x.x snapshot. Here's the full text of the email I got from PJ:

On 6/13/07, PJ Hile wrote:

Just some updates for those using CakePHP 1.2.x.x

1. $this->_viewVars has been changed to $this->viewVars (lines 242 and 260)
2. strip_plugin() has been moved to Router::stripPlugin() (line 183)

Hopefully that will save some people some time.

Regards, PJ

Internal ChangeLog

21 April 2007 - Version 1.0.6

Download: ThemeableView-1.0.6.zip

• Match themeable view locations between website pages and phpdoc. (Peppe Bergqvist)

• Fix filename mangling when falling back to 'system' theme in Themeable::themeElement(). (Peppe Bergqvist)

• Change behavior of Themeable::themeElement() to match new behavior in View::element(). Client code that relied on the old behavior should now use Themeable::_getThemeableElement() instead.

19 April 2007 - Version 1.0.5

Download: ThemeableView-1.0.5.zip

• Fixed recursive method invocation for View::element() whose behavior was changed in revision 4050. Special thanks to Peppe Bergqvist for discovering, reporting and investigating this bug.

07 October 2006 - Version 1.0.4

Download: ThemeableView-1.0.4.zip

• Use / instead of DS in getThemeablePath() and THEME_RESOURCES. (thanks to Ryan Clark)

• Fix viewPath resolution logic in _getViewFileName to include 'system' theme.

• Provide documentation in the PHPDoc comments.

• Added new ThemeHelper class to provide theme-aware analogs to css() and image() methods in HtmlHelper.

06 October 2006 - Version 1.0.3

Download: ThemeableView-1.0.3.zip

• Fix _getLayoutFilename() logic when the view attempts to search for a usable view layout file. (thanks to Ryan Clark)

• Added absoluteURL() method and use it for getThemeablePath() so that it returns the correct path to a themeable resource regardless of where CakePHP is currently installed.

25 September 2006 - Version 1.0.2

Download: ThemeableView-1.0.2.zip

• Move theme resources to webroot to allow for setups where the app dir is in a location that is not accessible through the webserver.

• Conditionally define THEMES constant to allow user to define an alternate location.

• Add a new conditionally defined constant THEME_RESOURCES to point to the relative URL of resources provided by the current theme.

15 September 2006 - Version 1.0.1

Download: ThemeableView-1.0.1.zip

• Fix theme fallback mechanisms. If a theme resource is not found in the current theme, it will try to search in themes/system.

• Fix bugs in plugin and element theme resource searching.

11 September 2006 - Version 1.0.0

• Initial release.

This entry was posted on Monday, September 11th, 2006 at 3:02 pm and is filed under CakePHP, Code and Consequences, PHP. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.