UNIT 04 - Webskins I

Objectives

In this unit we learn about webskins: the "view" for FarCry Framework. Webskins form the presentation tier of any FarCry application. By the end of this unit you should have a basic understanding of how webskins are managed, their relationship to content types and how to create your own.

The Webskin

The webskin is a templating layer that effectively translates your data into a view. Typically this is an HTML page or fragment of HTML representing a content teaser or some other element used in assembling a page. But a webskin could just as easily be outputting a form, RSS, XML or other format.

In its basic form we can run a webskin on an object by using the following URL Syntax:

URL Syntax

http://superheroes.local?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard

The url above is running the webskin "displayPageStandard" on the object with the objectid of "E689D66F-96FD-E9F6-B1AF64B8DAE78A69"

Where to Find Webskins

Webskins are all located in a single folder under your project root called "webskin" funnily enough. Inside that directory branch you should find a single folder for each content type you want a webskin for.

Example Directory Structure

c:\farcry
    \projects
      \myproject
        \webskin
          \dmHTML
          \dmNews
          \dmEvent
          \myContentType

Webskin Inheritence

Webskins can be stored in the core framework, and any plugin as well as your current project. However, any webskin placed in your project with the same name as an existing webskin will always be overridden by your project's webskin.

Walkthrough: Call a Webskin on a HTML Object

In this walkthrough we're going to call the standard dmHTML webskins on the Home Page HTML object.

Login to the Webtop and click on the Home Page dmHTML object in the site tree (the white page icon... not the blue dmNavigation object)
Copy the objectid of this object to the ClipBoard (located at the bottom of the summary for the object)
Now, locate the ./webskin/dmHTML folder in your project
Take note of the current webskins in that folder.

Now enter a url to call the various webskins in that folder using the following format

http://superheroes.local/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard
http://superheroes.local/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPage3Col
http://superheroes.local/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayTeaserStandard

Discuss how this forms the basis of almost ALL web applications

Creating Webskins

Webskins are literally just ColdFusion templates. Any file with a .cfm extension in a directory under ./myproject/webskin will be registered as a webskin by the FarCry Framework. Consequently only files that you intend to be webskins should ever be stored here. To create a webskin simply create the template in the correct directory and RELOAD the application.

Reloading The Application To Recognise Webskin Changes

When a FarCry application starts it works out all the available webskins for every content type and stores them in memory. Every time you add a new webskin you need to reload the application in order for the system to recognise it. If you are logged in you can reload the application from the "Tray Menu" or by simply running a page with &updateapp=1 at the end of the URL (if you are logged in). Alternatively, if you only want to reload part of the application, go into the [ webtop / admin / developer utilities / reload application ] and simply select the options you wish to reload. This is a handy tab to have open at all times while your developing and constantly adding/updating webskins and metadata.

Although you can give your webskin template any file name, in practise it makes sense to follow the naming standards used by the rest of the community. The following table outlines common naming prefixes for templates and explains their uses within the FarCry framework. An asterisk denotes a wildcard, where you would use your own unique name to differentiate templates of similar purpose.

Template Name	Purpose	Examples
display*	General prefix for all display templates. By default FarCry allows anonymous users to view anything prefixed with display*
displayPage*	A full page template display, typically incorporating header and footer HTML, and designating the entire page layout. These templates are available by default in the content editing wizards for contributors in community plugins, such as FarCry CMS.	./dmHTML/displayPageHome.cfm
displayPageStandard.cfm	In the absence of any additional criteria, FarCry will attempt to display a content object with this template, assuming it is available. It is in effect the "standard" full page template view.
displayTeaser*	A teaser view such as a title and short copy with a link to the full page view. Often used for listing other content objects on a page. Automatically recognised by many publishing rules.	./dmHTML/displayTeaserFeature.cfm
displayTeaserStandard.cfm	Similar to displayPageStandard, in that if no other criteria is given the framework will attempt to render a given content object with this template, assuming it is available and a teaser view is required.
displaySearchResult.cfm	Used in the farcryverity plugin to provide a universal search result teaser. As individual content types might be better suited to different teasers you can provide your own.
edit*	General prefix for editing a content type.	./dmProfile/editOwnProfile.cfm
edit.cfm	Default edit handler. Typically this is not present, at least in simple content types, as the framework will automatically build edit handlers from the formtool metadata. However, like most things in FarCry you can override this as needed.

These are just a few of the regularly used webskin names within the FarCry framework.

Hooking Up The Webskin To Data

Every time a webskin is invoked it is done so in the context of a specific content object. For example, viewing a particular news article in with a displayPageStandard, or a product item with displayPageProduct.cfm, or whatever. FarCry always provides the entire content object record to the webskin (or view) as a structure called stobj. stobj contains the typename, and all the property keys and values for the object in question, including array properties.

Array Properties

Array properties are automatically generated as an actually array in the structure value field. The array contains all the related object references as UUID values. More on this later.

The data contained in the stobj structure can be referenced in the normal way, and then combined with mark-up to produce the desired output. The similarity between this and any normal procedural ColdFusion template is deliberate - the framework authors have tried hard to make the creation of webskins or views very similar to building a simple ColdFusion template.

Simple Example of a News Template

<!--- Example Webskin Template -- Dead Simple --->
<cfoutput>
<h1>#stobj.title#</h1>
#stobj.body#
</cfoutput>

Whitespace Management

FarCry best practice sets <cfsetting enablecfoutputonly="true" /> at the top of your webskin and <cfsetting enablecfoutputonly="false" /> at the bottom. This means simply that any content you want displayed must appear between <cfoutput></cfoutput> tags. Try to avoid putting custom tags within <cfoutput> - without special treatment (eg. using cfsilent internally) the custom tag will output all its contents as whitespace.

Webskin Metadata

Every template can be supplemented with metadata. You should make a habit of this as it makes the whole system read much better, helping to provide human readable template names, inline documentation and so on. Metadata is incorporated by including a series of specific comments at the top of each template.

Attribute	Description
@@displayname:	Human readable display name for the template. Otherwise the framework will display the filename instead.
@@description:	Longer description about the template's purpose. This can run to any length but is typically a paragraph only.
@@author:	Name and contact email for the responsible developer.

Template metadata is always stored in a ColdFusion comment. On initialisation, FarCry scans the registered webskins for their additional metadata and stores it in memory. If you make a change to the metadata you may need to re-start the application in order to see the change come into effect.

Sample Metadata

<!--- @@displayname: Core Home Page --->
<!--- @@description: Home page for the FarCry Core developer portal. --->
<!--- @@author: Matthew Bryant (mbryant@daemon.com.au)--->

Walkthrough: Create displayPageSuper.cfm

In this walkthrough we're going to create a simple dmHTML webskin template to play with some of the ideas we've just considered.

Locate the ./webskin/dmHTML folder in your project
Create a file called displayPageSuper.cfm

Write up some basic HTML in a <cfoutput>

<!--- @@displayname: Demo Template --->
<cfoutput>
<h1>Hello Cruel World</h1>
</cfoutput>

Reload the application to pick up the template change. Use the [Reload Application] tool in the webtop.
Select the Site Overview Tab. Edit the FarCry Support HTML page and change its template to the one you just created.
Save and Preview the page. Check the HTML source and discuss with your instructor.
Edit your template and add a cfdump to the page for stobj
```
<cfdump var="#stobj#" label="Content Object" />
```
Save and preview the page.

Static Media Assets

In a FarCry project we normally make a distinction between media assets (such as files, images, video, etc) that are managed by the application (ie. Content Managed) and assets which are hard-coded and fixed in the code base (ie. Application Chrome).

When you are dealing with the application's chrome, the fixed static images and so on that make up the graphic theme of the site, in most instances you do not want to have these mixed with assets that are content managed by users. The standard for managing media assets of this nature is to store them under the webroot (for obvious reasons) in a directory called ./wsimages/ or under the ./css/images directory if they are relative to the style sheet.

Sample Project Directory Structure

c:\farcry
    \projects
      \myproject
        \webskin
        \www (standard project webroot)
          \wsimages
          \css\images

Version Control

If you version control your code base you want to make sure that content managed images are not included in your repository but be absolutely sure that images, etc pertaining to the design of the application are in the repository. Hence the clear split in where to store them.

Webskin Tag Libraries

Remember a webskin is just like a ColdFusion template - you can do all sorts of things. The webskin is strictly speaking a VIEW and following good programming practise you should refrain from doing business logic in this area. However, you can reference ColdFusion tags, FarCry service components and custom tag libraries as needed.

FarCry has a special custom tag library dedicated to making life easier when building webskins. In includes all sorts of goodies from building navigation, to breadcrumbs, to rendering other views and more. You can find this library in the core framework at: ./core/tags/webskin To make use of these tags you will need to import them first.

Importing Custom Tag Libraries

<!--- @@displayname: Home Page --->
<!--- @@author: Matthew Bryant (mbryant@daemon.com.au)--->

<!--- import tag libraries --->
<cfimport taglib="/farcry/core/tags/webskin" prefix="skin" />

<skin:breadcrumb />

Project Tag Libraries

We recommend creating your own custom tag libraries under the project folder and importing them in the same way: ./myproject/tags/mytaglibrary

Walkthrough: Putting It All Together

Get comfortable with how webskins are assembled in the real world. You should be able to dissect the sample application webskins and understand how they have been put together.

Review the other templates in the ./webskin/dmHTML directory with your instructor
Consider the use of custom tags, headers, footers and other layout mechanisms