Friendly URL Controller

Owned by Geoff Bowers
Last updated: Nov 20, 2009Version comment

Overview

The FarCry Core framework takes cues from the URL to determine what content instance or content type and what view should be rendered in the browser. These variables are closely integrated with the Friendly URL engine to provide good looking URLs that can drive the frameworks output. Understanding how the URL is interpreted by the framework is an important part of FarCry development.

Documentation for the 5.2+ Core Release

The behaviour of the URL interpreter varies slightly between subsequent releases of FarCry – gradually improving functionality. This documentation reflects the 5.2+ release.

  

Predefined VS Constructed Friendly URLs

Predefined FUs are those URLs that are created for a new object and stored in the database.

Typical examples are:

  • /about-us/location
  • /news/no-news-is-good-news

This system can be used by users to control how people link to specific content objects in FarCry.

Constructed URLs were added recently. They allow a developer to override the page or body webskin in the URL, and add extra URL parameters.

Examples of these may be:

  • /news/archive/year/2008
  • /blogger/E6EB2B10-D311-11DE-9F5C001FD08AA651/rss

It is also possible to combine these, e.g. /news/no-news-is-good-news/comment-rss.

FarCry will attempt to match a portion of the URL to a predefined FU. The remainder is parsed as:

type

The name or alias of a content type

objectid

The UUID corresponding to a content object

view

The name or alias of a page webskin

webskin

The name or alias of a body webskin

name/value

The remainder of the FU is parsed as name=value pairs

Some of important points:

  • This order is strict. Once a variable is matched, it and previous possibilities are not considered again.
  • This includes name/value - once a "directory" defaults to the name/value option, only name/value will be checked again.
  • Type and/or objectid MUST be provided, either with a predefined FU prefix, or by including them in the constructed portion.

If you are explicit about the view to be called FarCry will follow your instructions – the more you leave out the more FarCry tries to "work out' what's needed.

Aliases

To avoid using the actual names of types and webskins in the URL we have added support for an fuAlias property. This property can be added to the content type as an attribute and to a webskin with a comment variable. This value can be used in the URL instead of the file name.

View Binding

Type webskins are a recent addition to FarCry. They allow a developer to write a view runs in the context of a type instead of a specific object. But it's possible to try to bind a type webskin to an object and vice-versa, and the resulting errors can be very confusing. So the FU controller now makes an explicit check that the views being accessed are being bound at the right level.

If the controller finds an objectid, but view or bodyview is prefixed with displayType, it will throw an error. If the controller does not find an objectid, view and bodyview must be prefixed with displayType. By default the only exceptions are displayPage webskins, which can be bound to a type or an object.

By default ... but it is possible to override a webskin's binding with this comment variable:

<!--- @@viewBinding: type --->

Options for @@viewBinding are type, object, and any.

View Stack

The view stack refers to the convention of having page webskins and embedded body webskins. These in turn often use various "fragment" webskins. Each of these is treated differently by the FU controller.

If a page webskin is included in the URL (e.g. /news/no-news-is-good-news/displayPagePrint), FarCry knows that this view should override the default page webskin. If only a body webskin is added (e.g. /news/no-news-is-good-news/displayBodyComments) only the embedded body webskin is changed. The following table shows how a webskin's prefix changes how the controller handles it:

displayPage

page

displayBody

body

displayTypeBody

body

anything else

error - the controller doesn't know what to do

This behaviour can be modified with a comment variable in the webskin:

<!--- @@viewStack: page --->

Options for @@viewBinding are page, ajax, body, and any. Page and ajax are equivalent, but ajax may be clearer in some cases.

Note that ajaxmode=1 short circuits the view stack. This means a developer can access ANY fragment webskin with view=xyz&ajaxmode=1.

These allow a developer to use a FU without doing a database lookup themselves. As of this FarCry version they also handle constructed URLs automatically. Type, view and bodyView arguments are automatically converted to aliases where possible, urlParameters and stParameters are added as /name/value pairs.

Gotchas

These are possibilities that a developer should keep an eye out for. Feel free to add to the list.

Constructed URLs being the same as predefined URLs

A classic example of this is /news. On many sites this will will match a navigation node. Predefined URLs (even partially matched ones) ALWAYS take precedence.

Parsing