Class WFSkin

Description

Main skin class for managing skin wrappers around the content.

The Web Application's WFRequestController object always uses exactly one skin instance to render the page. However, your application may choose to create other skin instances to use the infrastructure for things like HTML email, etc.

The Skin mechanism is broken down into three layers. Each layer provides the ability to swap behaviors/looks at runtime. For each request, one of each layer must be specified.

  1. Skin Type -- i.e., which SkinDelegate is used. The Skin Delegate provides the skin with its catalog of behaviors, i.e., menus, footers, etc. Each skin type is unique, and skins must be written specifically for each Skin Type. Most web sites have just one skin type, that handles the elements appropriate for the skins of that application. However, sometimes there is a need for a single site to have multiple skins. For instance, the public site may have different navigational needs than the back-end admin interface. A WFSkinDelegate is implemented for each skin type an tells the system what data is available for the skin type. Skin Types, however, do NOT provide any layout or style. By default, each Skin Type implements only the "normal" template type. Your Skin Type may need additional layouts. For instance, printer-friendly or minimal layouts used for popups. Your skin can support additiona template types via templateTypes(). Every Skin for a Skin Type must have a template file for all template types to ensure proper operation.
  2. Skin -- A skin provides basic layout for a given Skin Type. Skins are specific for Skin Types, since they necessarily know about the data types offered by a particular skin type, via its Skin Delegate. Each Skin resides in its own directory inside the Skin Type directory that it belongs to. Each Skin thus provides a template file that implements a layout. Skins may also have multiple Skin Themes. Each Skin has a SkinManifestDelegate which tells the system which themes are available, and which theme to use by default.
  3. Skin Themes -- It may be desirable for a skin to have multiple colorschemes or other minor "thematic" differences. Each skin must have at least one theme. Infrastructure is provided so that the SkinManifestDelegate can easily supply different data to the skin based on the theme. This allows easy creation of colorschemes or other thematic differences.
 Skin Directory Structure:

 The skins have a specified, hierarchical directory structure, based in the "skins" directory.
 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 skinType 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.

 To use WWW visible items in your pages, simply use {$skinDir}/myImage.jpg and {$skinDirShared}/mySharedImage.jpg in your templates. The skin system automatically assigns these vars.
 skinDir maps to skins/<skinType>/<skinName>/www/<themeName>/
 skinDirShared maps to skins/<skinType>/<skinName>/www/shared/

Located in /framework/WFSkin.php (line 176)

WFObject
   |
   --WFSkin
Class Constant Summary
Variable Summary
string $body
object The $delegate
string $delegateName
array $headStrings
string $headTemplate
string $skinName
integer $templateType
string $title
Method Summary
static array installedSkinTypes ()
WFSkin __construct ()
void addHeadString (string $string)
void addMetaKeywords (array $keywords)
string delegateName ()
void getSkinDir ()
array installedSkins ()
void loadDefaults ()
void loadSkin ()
mixed namedContent (string $name, [assoc_array $options = NULL])
array namedContentList ()
string render ([boolean $display = true])
void setBody (string $html)
void setDelegate (object The $skinDelegate)
void setDelegateName (string $skinDelegateName)
void setHeadTemplate (string $path)
void setMetaDescription (string $description)
void setSkin (string $skinName)
void setTemplateType (string $templateType)
void setTheme (string $skinThemeName)
void setTitle (string $title)
string skinName ()
array templateTypes ()
void willRender ()
Variables
string $body (line 210)
  • var: The body content for the skin. This is the only "predefined" content element of the skin infrastructure.
  • access: protected
object The $delegate (line 202)
string $delegateName (line 190)
  • var: The skin delegate name to use for this instance.
  • access: protected
array $headStrings (line 234)
  • var: An array of strings of things that needed to be added to the <head> section.
  • access: protected
string $headTemplate (line 230)
  • var: The absolute filesystem path to a tpl file that is automatically added to the "head" element of all skins of this skin type.
  • access: protected
string $metaDescription (line 222)
  • var: The META DESCRIPTION for HTML skins.
  • access: protected
array $metaKeywords (line 218)
  • var: A list of META KEYWORDS for HTML skins.
  • access: protected
object The $skinManifestDelegate (line 206)
  • var: SkinManifestDelegate for the current skin.
  • access: protected
string $skinName (line 194)
  • var: The skin to use for this instance.
  • access: protected
string $skinThemeName (line 198)
  • var: The theme of the skin to use.
  • access: protected
integer $templateType (line 226)
string $title (line 214)
  • var: The TITLE of the skin. This will be used automatically as the HTML title.
  • access: protected
Methods
static method installedSkinTypes (line 554)

Get a list of all installed skin types.

  • return: Skin Types are installed.
static array installedSkinTypes ()
Constructor __construct (line 236)
WFSkin __construct ()

Redefinition of:
WFObject::__construct()
addHeadString (line 420)

Add a string that needs to go in the page's head section.

void addHeadString (string $string)
  • string $string: The string to go in the head section.
addMetaKeywords (line 462)

Add meta keywords to the skin.

void addMetaKeywords (array $keywords)
  • array $keywords: A list of keywords to add.
delegate (line 339)

Get the delegate instance.

  • return: A WFSkinDelegate instance.
object WFSkinDelegate delegate ()
delegateName (line 329)

Get the name of the Skin Type for the current instance.

  • return: The name of the current skin type.
string delegateName ()
getSkinDir (line 480)

return a path to the skin image dir

  • todo: Convert this to use the www root in the skins/ dir rather than the wwwroot/skins/ dir to consolidate skins into a single subdirectory
void getSkinDir ()
getSkinDirShared (line 489)

return a path to the skin shared image dir

  • todo: Convert this to use the www root in the skins/ dir rather than the wwwroot/skins/ dir to consolidate skins into a single subdirectory
void getSkinDirShared ()
getskinThemeName (line 374)
void getskinThemeName ()
installedSkins (line 577)

Get a list of all installed skins for the current Skin Type.

  • return: Skins that are installed.
array installedSkins ()
loadDefaults (line 600)

Allow the skin delegate to load the default values for this skin.

  • see: WFSkinDelegate::loadDefaults
void loadDefaults ()
loadSkin (line 393)

Load the current skin.

void loadSkin ()
namedContent (line 629)

Get the named content from the delegate.

  • return: The content for the named content for this skin instance. Provided by the delegate.
  • see: WFSkinDelegate::namedContent
mixed namedContent (string $name, [assoc_array $options = NULL])
  • string $name: The name of the content to retrieve.
  • assoc_array $options: A list of additional parameters.
namedContentList (line 614)

Get the catalog (ie list) of named content for this skin from its delegate.

If the skin delegate supports additional content for the skin, the catalog of content is provided here. Mostly this is for documentation purposes.

  • return: Array of strings; each entry is a name of a content driver for this skin delegate.
  • see: WFSkinDelegate::namedContentList
array namedContentList ()
render (line 501)

Render the skin.

  • return: The rendered view. NULL if displaying.
  • todo: convert the DIR_SMARTY calls to use a new WFWebApplication::getResource($path) infrastructure that will allow for userland overloads of these templates
string render ([boolean $display = true])
  • boolean $display: TRUE to display the results to the output buffer, FALSE to return them in a variable. DEFAULT: TRUE.
setBody (line 430)

Set the content for the skin to wrap. Typically this is HTML but could be anything.

void setBody (string $html)
  • string $html: The content of the skin.
setDelegate (line 348)

Assign a skin delegate for this instance.

void setDelegate (object The $skinDelegate)
  • object The $skinDelegate: skin delegate.
setDelegateName (line 307)

Set the skin's delegate by passing the NAME of the skin delegate.

This function will look for the skin delegate in the appropriate place, instantiate it, and set it up for this skin instance.

NOTE: Calling this function may overwrite any existing skin settings, since the loadDefaults() function may overwrite title, meta tags, etc. For best results, always call setDelegateName() BEFORE making adjustments to the WFSkin object.

  • throws: object Exception if the skin delegate does not exist, or it does not contain the skin delegate class.
void setDelegateName (string $skinDelegateName)
  • string $skinDelegateName: The NAME of the Skin Type.
setHeadTemplate (line 453)

Set the template file to be added to the "head" element of every page. Defaults to the built-in template file that sets up various PHOCOA things.

If you want to include the default head content, use {$skinPhocoaHeadTpl} in your custom head template file.

Typically this function would be called from your SkinDelegate's loadDefaults() function.

void setHeadTemplate (string $path)
  • string $path: Absolute path to new head template file.
setMetaDescription (line 471)

Set the META DESCRIPTION of the page.

void setMetaDescription (string $description)
  • string $description: The description of the page.
setSkin (line 358)

Set the skin to the given name. Will automatically load the skin and its default theme.

void setSkin (string $skinName)
  • string $skinName: The name of the skin to use.
setTemplateType (line 272)

Set the which template file of the current skin will be used to render the skin.

Potential uses for this include:

  • Using WFSkin::SKIN_WRAPPER_TYPE_RAW to return HTML snippets that will be used in AJAX callback
  • Using a custom "minimal" file that is used for popup windows where there is not enough real estate for the full skin.
  • Using a custom "mobile" file that would be used for mobile devices.
Any custom templates must be manifested by the skin delegate WFSkinDelegate::tempateTypes() method.

  • throws: object WFException if the template of the given name does not exist for this skin
void setTemplateType (string $templateType)
setTheme (line 369)

Set the theme to use.

void setTheme (string $skinThemeName)
  • string $skinThemeName: The name of the theme of the skin to use.
setTitle (line 439)

Set the title of the page. This is the HTML title if you are building an HTML skin.

void setTitle (string $title)
  • string $title: The title of the page.
skinName (line 384)

Get the current skin name

  • return: The name of the current skin.
string skinName ()
templateTypes (line 286)

Get a list of all template types available for this skin.

This list will include WFSkin::SKIN_WRAPPER_TYPE_NORMAL, WFSkin::SKIN_WRAPPER_TYPE_RAW, and any custom template types manifested by the skin type delegate (skin manifest delegate).

  • return: An array of strings with the names of all valid template types.
array templateTypes ()
willRender (line 644)

Pre-render callback.

Calls the skin delegate's willRender() method if it exists. This method is called just before the template for the skin is rendered.

  • todo: Do I need to pass in the WFSmarty instance here so that you can actually change the TPL file from this callback? If so, also update the willRender() delegate docs/prototype
void willRender ()

Inherited Methods

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::setValuesForKeys()
WFObject::validatedSetValueForKey()
WFObject::validatedSetValueForKeyPath()
WFObject::validateObject()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForStaticKey()
WFObject::valueForStaticKeyPath()
WFObject::valueForTargetAndKeyPath()
WFObject::valueForUndefinedKey()
WFObject::valueForUndefinedStaticKey()
WFObject::valuesForKeyPaths()
WFObject::valuesForKeys()
WFObject::_valueForStaticKey()
WFObject::__toString()
Class Constants
SKIN_WRAPPER_TYPE_NORMAL = 'normal' (line 181)

The "normal" templateType: template_normal.tpl

SKIN_WRAPPER_TYPE_RAW = 'raw' (line 185)

The "raw" templateType: the exact page contents will be displayed; equivalent to using no skin.

Documentation generated on Thu, 14 May 2009 16:20:30 -0400 by phpDocumentor 1.4.2