Summary of View or Webskin Decorators

Overview

A view decorator is a little bit of metadata that you can stick at the top of your view in FarCry to change its behaviour and the way its documented. FarCry Core framework is pretty clever and can work out a default in most cases depending on the file naming convention you have used. However, its good practice to be explicit about your decorators so be sure to put them in.

Adding them to your view couldn't be easier. Just add each decorator on its own line, in a ColdFusion comment, at the top of your view.

<!--- @@Displayname: Full Page Display --->
<!--- @@Description: Complete view of the case study. --->
<!--- @@Viewstack: page --->
<!--- @@Viewbinding: object --->
<!--- @@Cachestatus: 1 --->
<!--- @@Cachetimeout: 60 --->
<!--- @@Fualias: page --->
<!--- @@postprocess: youtube(width=720,height=405);gist --->

View Decorators

What follows is a little cheat sheet of the most common decorators and how they work.

@@cachestatus: 0, 1, -1
Cache status determines whether or not a view should participate in the dynamic caching layer of FarCry. 0 is the default and simply means, "no directive given". 1 says "turn on caching". -1 prohibits the view from being cached under any circumstances, even if a parent view has been instructed to be cached.

@@Cachetimeout: minutes (default 24hrs)
Cache time out is the number of minutes the view should remain in the cache. This defaults to an entire day. It's not unusual to have long time outs for FarCry caches. Unlike other CMSs, the FarCry caching service is clever and will automatically flush caches where content has been updated rather than waiting for the full time out.

@@Cachetypewatch: list of typenames
Cache type watch setting looks for changes in the nominated content types. If you add a new content item to the system, a view with a "type watch" will automatically get flushed. This is great for listing views that show stuff like the latest news items or whatever.

@@Cachebyvars: list of scoped variable names
Sometimes you want the view to have a different cache for different values of a variable. This is easily achieved by nominating the list of variables that make up that difference. For example, an archive page which uses a url parameter like &year=2010 would ideally have a different cache for each value for year.

The vars that might impact the caching are accessed and hashed BEFORE the webskin is executed in order to identify if that execution can be avoided. You can define a default cacheByVars value in the decorator like so:

<!--- @@cacheByVars: url.page:1 --->

In cases where the variable is not found by the caching layer, it is treated as being equal to the specified value instead. Variables with no defaults are still supported.

@@Viewstack: page, body, fragment, ajax, any
View stack is a little quirky. It's basically an instruction to the friendly url service to help it identify what type of view your output should be, ie. "where in the stack". Normally this is determined by convention. If you name your view with a prefix of displayPage, then it will be assigned a value of "page", displayBody and its "body", and just about everything else is "fragment", for example displayTeaserStandard.cfm

@@Viewbinding: type, object, any
View binding determines what part of the model should be bound to your view. Use "type" when its a type view, that is a view on a group of objects pertaining to a content type. And use "object" if you are rendering a specific content instance or record.

@@Fualias: friendly URL alias for the view
Friendly URL alias is great. You can rename your view, as it appears on the URL, to just about anything you like. So for a view with a file name of displayRSSFeed.cfm you get a default URL containing "displayRSSFeed". Using fualias you could change this to simply "rss".

@@postprocess: webskin post processing

Post processing can be used to modify the output of a webskin after it is generated. It can be used to remove white space, convert URLs into full embedded content, or support your own content macros. More details here.

@@Displayname: name of the template
@@Description: overview of template usage
Displayname and Description are used by the framework and documentation plugin to provide a friendly name and additional information about the view when its relevant. It's highly recommended you fill these in so your users get friendly and intuitive labels.