...
Objectives
...
title | Work in Progress |
---|
...
Updating the course for FarCry 6.x. If you can help let us know! Put your notes in the comments for the page.
Additional topics to be considered for this unit:
- introduce the difference between views on the content type (ie type or listing views) and views on individual content items/instances
- introduce friendly URLs; these will be covered in more detail in Webskin II
- explain the use of the webskin tracer; developers need to learn this immediately
- introduce view inheritance ie. views coming from core and plugins as well as the project
- explain how headers and footers work
- explain in detail the way skin:view works
- give examples of relevant @@viewdecorators where possible
- explain grid tags; especially with respect to mollio skeleton
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.
...
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 | ||
---|---|---|
| ||
http://superheroes.local?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard
|
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 | ||
---|---|---|
| ||
[install-root]
\farcry-express-install
\webroot
\farcry
\projects
\myproject
\webskin
\dmHTML
\dmNews
\dmEvent
\myContentType
|
Tip | ||
---|---|---|
| ||
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.
...
title | Example URLs Only |
---|
...
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 | ||||||||
---|---|---|---|---|---|---|---|---|
|
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 | ||
---|---|---|
| ||
http://superheroes.local?objectid=E689D66F-96FD-E9F6-B1AF64B8DAE78A69&view=displayPageStandard
|
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 | ||
---|---|---|
| ||
[install-root]
\farcry-express-install
\webroot
\farcry
\projects
\myproject
\webskin
\dmHTML
\dmNews
\dmEvent
\myContentType
|
Tip | ||
---|---|---|
| ||
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 or in version 6-0-16, under the Miscellaneous tab in the ObjectID section)
- 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 Block title Example 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
- Discuss how this forms the basis of almost ALL web applications
...
Note | ||
---|---|---|
| ||
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 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. Alternatively, if you only want to (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. |
...
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
...
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.
...
Code Block | ||
---|---|---|
| ||
c:\farcry \projects \myproject \webskin \www (standard project webroot) \wsimages \css\images |
Tip | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
<!--- @@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 />
|
Tip | ||
---|---|---|
| ||
We recommend creating your own custom tag libraries under the project folder and importing them in the same way: ./myproject/tags/mytaglibrary |
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 | ||||||||
---|---|---|---|---|---|---|---|---|
|
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 | ||
---|---|---|
| ||
<div id="main"> <div class="container_12"> <div \wsimages \css\images |
Tip | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
<!--- @@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 />
|
Tip | ||
---|---|---|
| ||
We recommend creating your own custom tag libraries under the project folder and importing them in the same way: ./myproject/tags/mytaglibraryclass="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.
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.
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.
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
- turn on the webskin tracer
- review various pages with your instructor
- Add Header & Footer views to
./dmHTML/displayPageSuper.cfm
Walkthrough: Putting It All Together
...