Versions Compared

Old Version 14

changes.mady.by.user Geoff Bowers

Saved on

compared with

New Version Current

changes.mady.by.user Justin Carter

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

Objectives

Excerpt

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 COAPI

The FarCry framework is based on a variation of the classic Model-View-Controller pattern. The COAPI (or Content Object API) is a high level name for the MVC engine inside FarCry. Without getting bogged down in the details of the framework, its good to have a high level or "helicopter" view of how things work under the hood. We'll expand on these themes gradually as you go through the course.

Mockup
mvc-diagram
mvc-diagram
Version2
Namemvc-diagram

Requests from users are processed by FarCry's built-in "smart controller" which automatically determines wiring based on the URL convention or the friendly URL sub-system. The COAPI always ends up calling a principal content type (a special type of class) that manages how we interact with the model and view. When thinking of views (or webskins) its important to realise that they are always executed in the context of a specific content type.

It's not at all important for developers to understand how the COAPI works, but hey, for those that want the details we've added some advanced info boxes where relevant.

The Webskin

The webskin is a templating layer that effectively translates your data into a view. Typically this is a complete 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:

Code Block
titleURL Syntax
http://superheroes.local?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard
{code}

The

...

url

...

above

...

is

...

running

...

the

...

webskin

...

"displayPageStandard"

...

on

...

the

...

content

...

item

...

with

...

the

...

objectid

...

of

...

E689D66F-96FD-E9F6-B1AF64B8DAE78A69

...

Pretty

...

ugly,

...

eh.

...

But

...

not

...

to

...

worry.

...

In

...

practice

...

the

...

Friendly

...

URL

...

(FU)

...

engine

...

dynamically

...

changes

...

these

...

links

...

to

...

beautiful

...

looking

...

URLs.

...

For

...

example,

...

/hero/batman

...

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.

Code Block
titleWebskin Directory Structure
[install-root]
\farcry-express-install
  \webroot
   \farcry
     \projects
       \myproject
         \webskin
           \dmHTML
           \dmNews
           \dmEvent
           \myContentType
{code}

{tip:title=Webskin Inheritance}
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.
{tip}

h2. 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 each of the webskins in that folder using the following format
{code:title=Example URLs Only}
Tip
titleWebskin Inheritance

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.

  1. 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)
  2. Copy the objectid of this object to the ClipBoard (located at the bottom of the summary for the object or in version 6-0-16, under the Miscellaneous tab in the ObjectID section)  
  3. Now, locate the ./webskin/dmHTML folder in your project
  4. Take note of the current webskins in that folder.
  5. Now enter a url to call each of the webskins in that folder using the following format
    Code Block
    titleExample URLs Only
    
http://localhost:8888/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard

http://localhost:8888/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPage3Col

http://localhost:8888/index.cfm?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayTeaserStandard

...

  2. Discuss how this forms the basis of almost ALL web applications
Creating Webskins
The "smart controller" wires up the content type, the content item and webskin (view) by convention based on the parameters in the URL.
Webskins are literally just ColdFusion templates. Any file with a .cfm extension in a directory under ./myproject/webskin will be automatically 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/RESTART the application.
 Note
titleReloading/Restarting 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 create a new webskin file 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. (Note: Your updateapp key may be set to a value other than 1. Check inside your farcryConstructor.cfm in your webroot to confirm).
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.
 Tip
Changing webskins does NOT require an application restart. You only need to restart if you are adding, removing or renaming webskin files.
Naming Webskin Templates
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 item 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 search plugins to provide a universal search result teaser. As individual content types might be better suited to different teasers you can provide your own as needed. 
 edit* 
 General prefix for editing a content type. By default, these views are secured to content publishers only and are not accessible by anonymous users. 
 ./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. For a complete list of reserved webskin template names review: https://farcry.jira.com/wiki/display/FCDEV50/Webskin+Templates
...
Hooking 
...
 Up 
...
 The 
...
 Webskin 
...
 To 
...
 Data
...
Every 
...
 time 
...
 a 
...
 webskin 
...
 is 
...
 invoked 
...
 it 
...
 is 
...
 done 
...
 so 
...
 in 
...
 the 
...
 context 
...
 of 
...
 a 
...
 specific 
...
 content 
...
 type.
...
For 
...
 example, 
...
 viewing 
...
 a 
...
 particular 
...
 news 
...
 article 
...
 with 
...
 a 
...
 displayPageStandard, 
...
 or 
...
 a 
...
 product 
...
 item 
...
 with 
...
 displayPageProduct.cfm, 
...
 or 
...
 whatever. 
...
 FarCry 
...
 always 
...
 provides 
...
 the 
...
 entire 
...
 content 
...
 item 
...
 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.
...
Image Added
 Tip
titleArray Properties
Array properties are automatically provided as a CF 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 as a simple ColdFusion variable, 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.
 Code Block
titleSimple Example of a News Template
<cfsetting enablecfoutputonly="true">
<!--- // Dead Simple Example Webskin Template --->
<cfoutput>
  <h1>#stobj.title#</h1>
  #stobj.body#
</cfoutput>
<cfsetting enablecfoutputonly="false">
{code}

{tip:title=Whitespace Management}
FarCry best practice sets <cfsetting 
 Tip
titleWhitespace 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 
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.

{tip}

h2. Webskin Decorators

Every template can be supplemented with additional metadata, called a 
Webskin Decorators
Every template can be supplemented with additional metadata, called a "decorator". 
...
 You 
...
 should 
...
 make 
...
 a 
...
 habit 
...
 of 
...
 adding 
...
 relevant 
...
 decorators 
...
 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. 
For a complete list of decorators and their uses, see:https://farcry.jira.com/wiki/display/FCDEV60/Summary+of+View+Decorators
...
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.
...
:=    }
 Code Block
title
Sample 
 Metadata 
 Attached 
 With 
 Decorators
<!--- @@displayname: Core Home Page --->
<!--- @@description: Home page for the FarCry Core developer portal. --->
<!--- @@Cachestatus: 1 --->
<!--- @@Cachetimeout: 60 --->
<!--- @@Fualias: home --->
{code}

h2. 
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.
...
  1. Locate 
...
  1.  the 
...
  1.  ./webskin/dmHTML 
...
  1.  folder 
...
  1.  in 
...
  1.  your 
...
  1.  project
...
  2. Create 
...
  1.  a 
...
  1.  file 
...
  1.  called 
...
  1.  displayPageSuper.cfm
...
  2. Write 
...
  1.  up 
...
  1.  some 
...
  1.  basic 
...
  1.  HTML 
...
  1.  in 
...
  1.  a 
...
  1.  <cfoutput> 
...
  1.  Code Block
...
  1. title
...
  1. ./webroot/farcry/projects/myproject/webskin/dmHTML/displayPageSuper.cfm
...
  1. 
<!--- @@displayname: Demo Template --->
<cfoutput>
<h1>Hello Cruel World</h1>
</cfoutput>

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

...
  2. 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.
 Code Block
titleSample Project Directory Structure
c:\farcry
    \projects
      \myproject
        \webskin
        \www (standard project webroot)
          \wsimages
          \css\images
{code}
{tip:title=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.
{tip}

h2. 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: *
 Tip
titleVersion 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.
...
For 
...
 a 
...
 complete 
...
 list 
...
 of 
...
 webskin 
...
 tags 
...
 see:
...
http://docs.farcrycore.org/p600/
...
:=   }
 Code Block
title
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" />

<!--- breadcrumb; detects position in the site tree and builds a breadcrumb --->
<skin:breadcrumb />
{code}

{tip:title=Project Tag Libraries}
We recommend creating your own custom tag libraries under the project folder and importing them in the same way: 
 Tip
titleProject Tag Libraries
We recommend creating your own custom tag libraries under the project folder and importing them in the same way: ./myproject/tags/mytaglibrary

{tip}

h2. Composite Views

In practice, web pages in FarCry are assembled from multiple webskins.  While you can do a lot with custom tags, the best way to build web pages is by compositing multiple webskins together.

Consider the following real world examples of composite views from the Fandango theme.

{mockups}

{note}
FarCry doesn't prescribe a specific templating architecture - you can get pretty sophisticated in your approach or keep it dead simple. Fandango is a good best practice starting point.
{note}

h3. Building a Composite View

A typical starting point for any composite view is working with headers and footers. Its very common to have a similar header across all web pages, albeit with slight variations such as page title, highlighted navigation and so on. Likewise the footer structure.

You can call another view directly using the {{skin:view}} tag. {{skin:view}} is a real workhorse - we use it *all the time*.

{code}
skin:view example
{code}

h3. View Inheritance

FarCry is an object oriented framework. All content types extend the core {{types}} component (an abstract class). Any views associated with {{types}} are automatically inherited by other content types, such as our dmHTML content type.

More on content types later. Long story short, you can assume that *any* view located in {{./webskins/types}} is available to *all* content types.

Looking at our dmHTML content type in Fandango, we have at least the following views available:
- displayPageStandard
- displayTeaserStandard
- displayHeaderStandard
- displayFooterStandard
- displayBody
- displaySimpleSearchResult


h2. Webskin Tracer

The *tray* that appears at the bottom of the website when you are logged in, contains a marvellous developer utility called the "Webskin Tracer". You can activate it for any page by simply selecting the webskin tracer option.

!tracer01.png|border=1!

The entire pages composite of views is laid bare; highlighting each webskin executed for the page. Select a specific view and the HTML fragment is highlighted, with a tooltip detailing exactly where the webskin template can be found.


!tracer02.png|border=1!
 

{tip}You can turn on the webskin tracer and profile tools without being logged in by using your projects "secret key" on the URL.{tip}

h2. Walkthrough: Creating a Composite View

# turn on the webskin tracer
# review various pages with your instructor
# Add Header & Footer views to {{./dmHTML/displayPageSuper.cfm}}



h2. 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 
Composite Views
In practice, web pages in FarCry are assembled from multiple webskins. While you can do a lot with custom tags, the best way to build web pages is by compositing multiple webskins together.
Consider the following real world examples of composite views from the Fandango theme.
 Mockup
webskin-composite
webskin-composite
Version1
Namewebskin-composite
 Note
FarCry doesn't prescribe a specific templating architecture - you can get pretty sophisticated in your approach or keep it dead simple. Fandango is a good best practice starting point.
Building a Composite View
A typical starting point for any composite view is working with headers and footers. Its very common to have a similar header across all web pages, albeit with slight variations such as page title, highlighted navigation and so on. Likewise the footer structure.
You can call another view directly using the skin:view tag. skin:view is a real workhorse - we use it all the time.
 Code Block
titleExample from ./dmHTML/displayPageHome.cfm

<div id="main">
	<div class="container_12">
		<div class="grid_12 content">
		<skin:view typename="#stobj.typename#" objectid="#stobj.objectid#" webskin="#url.bodyView#" />
		</div>
	</div>
</div>

View Inheritance
FarCry is an object oriented framework. All content types extend the core types component (an abstract class). Any views associated with types are automatically inherited by other content types, such as our dmHTML content type.
More on content types later. Long story short, you can assume that any view located in ./webskins/types is available to all content types.
Looking at our dmHTML content type in Fandango, we have at least the following views available:
  • displayPageStandard
  • displayTeaserStandard
  • displayHeaderStandard
  • displayFooterStandard
  • displayBody
  • displaySimpleSearchResult
Webskin Tracer
The tray that appears at the bottom of the website when you are logged in, contains a marvellous developer utility called the "Webskin Tracer". You can activate it for any page by simply selecting the webskin tracer option.
Image Added
The entire pages composite of views is laid bare; highlighting each webskin executed for the page. Select a specific view and the HTML fragment is highlighted, with a tooltip detailing exactly where the webskin template can be found.
Image Added
FarCry Profiler
The FarCry profiler details how long each part of your request is taking to execute on the server. This is a great tool for identifying slow running pages and candidates for caching.
Image Added
 Tip
You can turn on the webskin tracer and profile tools without being logged in by using your projects "secret key" on the URL:http://localhost:8888/index.cfm?objectid=E689D721-B6C9-605B-DE1D813E4CDA3339&tracewebskins=farcry
Walkthrough: Creating a Composite View
  1. turn on the webskin tracer
  2. review various pages with your instructor
  3. Add Header & Footer views to ./dmHTML/displayPageSuper.cfm
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.
  1. Review the other templates in the ./webskin/dmHTML directory with your instructor
  2. Consider the use of custom tags, headers, footers and other layout mechanisms