4.1. Skin / Template System

The PHOCOA skin system provides a simple yet flexible way to control the template being used to render each page. Instead of having to include header and footer templates on each page, you actually design the layout in the skin system, and the skin where the "page body" (the result of the module rendering) goes in the skin. This separation of concerns makes it simpler to manage complex layouts and keeps your attention focused on the relevant part of your page design.

The skin system has three layers:

• Skin Type At the top level is the Skin Type. Each skin type can have its own distinct infrastructure of common components, which are managed by its delegate, implementing WFSkinDelegate. The skin type is not a layout in and of itself; rather it is just an implementation of the layout from a semantic perspective. The Skin Delegate provides an interface for the skins (explained below) to access the data common to the layout. Many applications have only one skin type. However, you might have different portions of your site that have different sets of data to present, and this is a reason that you might create a new skin type. For instance, you might create an additional skin type for the "Admin" interface of your web site since it has a different set of "components" that need to be displayed on each page.

• Skin A skin is an actual layout implementation of the elements defined by a skin type. Each skin type can have any number of skin implementations.

• Skin Theme Each skin can optionally be partitioned into themes. Themes provide an easy way to use the same basic layout (the Skin) while changing colorschemes, graphics packages, etc. This is done effectively by swapping out a css file and the "path" to the skin's assets (images, etc).

• Template Type Each skin by default has just one template file, template_normal.tpl. If you want minor variations of the same look and feel, such as for a popup or mobile version, this is the way to do it. Different template types of the same skin will still be "themed".

By default, a new PHOCOA application has a single Skin Type (simple) and two Skins (topnav, sidenav). topnav has only one theme, while sidenav has two themes set up.

The bundled "SkinInfo" module provides an interactive browser for the installed skins on any PHOCOA application to make it easy to understand and browse the skin infrastructure. This is also available at http://phococa.com/examples/skinInfo.

Determining When To Use The Various Aspects of the Skin System

How do you know when you should create a new skin type, or just a new skin, or just a new skin theme? Here are a few pointers:

• If you just want a slight variation on an existing look and feel (i.e., different header graphics, different colors), then you should use just one skin type with one skin and make a skin theme for each variation.

• If you are keeping the same look and feel, but want a slightly different layout (maybe for a pop-up window or a mobile version), then you should make a new template type for your skin.

• If you want a different look and feel, but need to display all of the same elements on the page, you should create a new skin.

• If you need to represent an entirely different set of elements on the web page, such as for an admin interface vs. the public interface, then you should create a new skin type.

Most applications will have a single skin type, and a single skin, with one or more themes, and maybe a few extra template types. Don't get too overwhelmed with the options. The flexibility in the skin system is primarily intended for CMS applications or large web applications with multiple "sections".

Authoring Skins

When authoring skins, you will need to know how the skin systems stores its files and also how to create URL's pointing to the themed CSS files and other assets (images, js, etc) of your skin.

For convenience, all files related to a skin are stored along with the skin delegate code. PHOCOA takes care of mapping incoming URL requests to the proper folders. All skins are stored under the skins directory at the top level of your PHOCOA project.

skins/ - Contains only directories; each directory represents a Skin Type.

skins/<skinType>/ - For each skin type, pick a unique name and create a directory.

skins/<skinType>/<skinType>_SkinDelegate.php - A php file containing exactly one class, named <skinType>_SkinDelegate, that is the WFSkinDelegate for the Skin Type.

skins/<skinType>/<skinName>/ - Also in the skin type directory are other directories, one for each skin that can be used for the Skin Type.

skins/<skinType>/<skinName>/<skinName>_SkinManifestDelegate.php - The WFSkinManifestDelegate for the skin <skinName>.

skins/<skinType>/<skinName>/ - Other files in here are the various tpl and css files used for this skin.

skins/<skinType>/<skinName>/www/ - Web root of the skin. Nothing actually goes in this folder but other folders.

skins/<skinType>/<skinName>/www/shared/ - Files that need to be accesible to the WWW and are shared by multiple themes of this skin go here.

skins/<skinType>/<skinName>/www/<themeName>/ - Files that need to be accessible to the WWW and are specific to a theme go here. Each theme has its own folder to contain "themed" versions of resources. Typically every theme has the same set of resources, but of course customized for that theme.

PHOCOA automatically adds some template variables to make it easy to access skin assets.

• skinDir Absolute URL path to the skins/<skinType>/<skinName>/www/<themeName>/ directory.

• skinDirShared Absoulte URL path to the skins/<skinType>/<skinName>/www/shared/ directory.

• skinBody The raw output of the current PHOCOA request. This is where the "page content" goes.

• skinHead The raw output PHOCOA generates to go in the <head> section of the web page. You can "override" default head elements in your own skin by placing references to css, js, etc. after skinHead.

• skinThemeVars The data returned by your skin's loadTheme($theme) function.

In addition to these variables, PHOCOA also includes a Smarty plugin to generate the correct CSS reference to include themed CSS files. The syntax is:

{WFSkinCSS file="myFile.css" media="screen"}

The media attribute is optional.

You don't have to use this method to include CSS files. You can simply put them in your theme's www directory, or in the shared directory. The difference, however, is that if you use the themed css syntax, your CSS file will be processed as a template and thus have access to the skinThemeVars variable. This is particularly useful if the only difference between your different theme css files is just a different colorscheme, for instance. Instead of having to maintain multiple copies of nearly identical CSS files, you can just have one that is run through the themed CSS system, and simply subsitute the colorscheme info via template variables.

Previewing Skins

PHOCOA includes a useful utility for browsing and previewing installed skin types, skins, themes, and template types. See http://phocoa.com/webapp/examples/skininfo/skinTypes for a demo.

Including Module/Page Content in a Skin

At this time, skin template files cannot make use of PHOCOA widgets or other PHOCOA technologies for building web pages. However, a special Smarty plugin is provided to allow you to include the output of a module/page in a skin. This is useful for cases such as building menu navigation systems, including a login form on every page, etc.

PHOCOA ships with a module/page called "menu" which makes it easy to include a YUI-based menu system on your site. You simply include the menu module with the WFSkinModuleView plugin, passing the name of the "namedContent" you want to use from your skin, and optionally a 1 to indicate that your menu is a horizontal menu bar.

For example, this creates a horizontal menu bar with drop-down menus, using the content supplied by the skin's "mainMenu" content:

{WFModuleView invocationPath="menu/menu/mainMenu/1"}