Chapter 4. Advanced Topics

This chapter contains a conceptual overview of additional PHOCOA programming topics.

(more to come)

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:

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:

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.

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"}