Included Objects

Owned by Rachel Maxim
Last updated: Apr 13, 2006Version comment

Overview of included objects

Included objects are an easy way to quickly add custom functionality to Farcry without having to create Custom Types or display rules. Essentially included objects are self-contained CFM pages that, once added in Farcry, will be included within the standard site skin. Of course, building an include does required enough knowledge of ColdFusion to build whatever functionality you need from scratch.

Creating included objects

When you develop an included object, you can develop it exactly as you would any other ColdFusion page, using either the Farcry datasource or another datasource as needed.

Some tips to keep in mind when designing includes

  • make the include itself a self-contained page - if you need a self-posting form or multiple displays of the same object/data, the include can be a ColdFusion switch statement that includes the various views
  • you can call a CFC as you normally would using the include
  • I personally prefer to keep all files related to Included Objects under a folder named for the object so that it's neat and clean and not intermingled with other Farcry code.

Example included object structure

Let's say you are creating a Contact Form for an included object. This is a self-posting form with a "form" view, and a "confirmation" view. It is inserted into a database by a CFC, and the information from it is emailed to your email address.

Here are the files you would need:

  • The main include: _contact.cfm (consisting primarily of a switch statement to toggle between the various views)
  • the CFC that processes the form: contact.cfc (can be stored wherever you prefer to keep CFCs)
  • a folder for related files:
    -contact (folder)
    --contactForm.cfm (the form display)
    --confirmMessage.cfm (the confirmation message display page/html)

Making included objects available to Farcry

To be available in Farcry, the include needs to be placed in the farcry_<application name>/includedObj directory. The include must be directly within this folder so that Farcry can find it.

Using included objects in Farcry

  1. Once the file is in the proper place, simply log in to Farcry admin and go to the Site tab.
  2. Within your site tree, select the navigation node where you want the include to appear, and create a new include object (right-click and choose Create > Include from the context menu).
  3. In the Create Include form you will see a select menu that shows all the files in the includedObj folder. Select your include file from the list.
  4. Give the include object a title, teaser and select a Display Method for it. Send it live or preview as desired.

note: at this point it often helps to turn on debugging in CF Admin or append "debug=1" to the URL of the page to work out any errors!

If this is your first include you will also notice that it may not match the rest of your webskin. Under the /webskin/ folder, there is a folder for Included Object display methods. This folder by default is called dmInclude. These skins are what will determine the display of your include, customize as needed.
The most important line in the skin is where the include itself is called:

<cfinclude template="/farcry/#application.applicationname#/includedObj/#stObj.include#">

As long as this line is in your display method, your include should show up.

Include tips and ideas

  • Insert a container or two above and below your include so that your users can customize areas outside the include.
  • Includes can be used to quickly integrate already-built functionality or downloaded apps into Farcry