UNIT 05 - Content Types

Objectives

Super Hero Handbook

In a bid to test the theory that FarCry is indeed a framework, we're building the Super Hero Handbook application. It's a somewhat frivolous application that has the benefit of not tying us down to a specific set of functionality. Plus it should be a lot of fun.

We can invent things as we need them to showcase aspects of the technology without being constrained by the more traditional, user focused goals of a typical application. It also has the potential of being a lot more complex than your average "build a blog in 10 minutes" exercise which appears to be the benchmark for determining the viability of many frameworks.

FarCry is accused of being an extensible, cutting edge, content management system (CMS). Ok so that's true. But the CMS functionality is actually built on the FarCry Framework. It's a framework that just happens to be suitable for building many other sorts of web based applications. In fact, we're firm believers that content management is really a commodity service that just about every application needs, so its great to be able to build an application that has immediate access to such rich CMS tools.

Content Types

The central building block of the farcry framework is the content type. Think of a content type as the definition of a table in a relational database as this is exactly what they are.

A content type is defined by a ColdFusion component (CFC), and depending on its complexity a variety of auxiliary files. A content type can be just about any sort of persistent data; for example, a news item, product, log table, transaction record, user profile and so on. For example, the pages currently on your site are stored in the content type called dmHTML.

More about the mechanics of content types later - for now we need to think about the basic content types that constitute the Super Hero Handbook, what "content objects" will model the data we have in our application and how they fit together. Lets start relatively simple, and evolve from there.

The Super Hero

We need a central profile to capture our catalogue of super powered beings, their properties and relationships.

The Super Power

Super powers are generally not unique (with some exceptions). It would be nice to have a library of super powers we can assign to super heroes as we add them to the system.

The Super Group

We're not talking ABBA here. The super group is a league or association of super heroes; for example, the Sovereign 7, Fantastic Four, and the League of Justice. A super hero could potentially belong to several groups over their lifetime.

Building a Content Type

The FarCry content type is a central building block for the FarCry Framework. Developers can extend and change the behaviour of existing content types, create their own content types and group related content types into libraries.

We start by creating a content type component and defining the properties that exist for the content objects it manages. Content types are saved in your projects ./packages/types sub-directory.

Hooking Into the Framework

The component must extend FarCry's core abstract class "types" in order to engage with the FarCry Framework. This abstract class provides both additional system properties and methods necessary for the content type to work within the framework.

Content Object API (COAPI)

The cfproperty tag doesn't really do a great deal other than define meta data for the component in ColdFusion. FarCry leverages this fact to allow developers to define the default behaviour of the component within the framework.
In the superHero.cfc example we're using the cfproperty tags to define the name and FarCry data type for each property of our Super Hero content type.

Next we use the FarCry type deployment interface to build a data persistence model for the content items or records associated with the component.

FarCry detects that a component exists but hasn't got a corresponding persistence model in the database - the "deploy" options creates all the tables required for this content type. The columns are mapped to their relevant data types, depending on the FarCry data type nominated and the specific relational database you are using.

FarCry relies on the component to define the required data model definition and has tools to keep the database model in sync with changes to the component property set. Not only will the framework deploy tables it will also alter columns and data-types to match changes in the underlying component as required. The COAPI is even clever enough to set precision on table columns and build indices for better performance.

All properties in the component map to a specific column in the content type table, with the exception of array properties (discussed later on).

Walkthrough: Creating Super Hero

We'll kick off our sample application by creating a content type for the Super Hero.

1. Create a new file called superHero.cfc and save this into your project's ./packages/types directory.

2. Copy the following code into this file, save and review with the instructor

   ./myproject/packages/types/superHero.cfc

   <cfcomponent name="superHero" extends="farcry.core.packages.types.types" output="false" displayname="Super Hero"> <cfproperty name="title" type="string" default="" hint="Super hero title." /> <cfproperty name="secretHideout" type="string" hint="The secret hideout location of the super hero" /> <cfproperty name="teaser" type="longchar" default="" hint="Mini intro for super hero biography." /> <cfproperty name="biography" type="longchar" default="" hint="Super hero biography." /> <cfproperty name="imgHero" type="string" hint="The image of the hero" /> </cfcomponent>

3. Go to the FarCry Webtop and deploy the content type: ADMIN > Developer Utilities > COAPI Tools > Types

4. Locate your new content type, "superHero" and select DEPLOY.

5. Click on the [Scaffold] button now to create an Administration scaffold

6. Select the checkbox next to "Create type admin interface",

   1. put in a title for your administration list

   2. select label and imgHero as the fields to appear in your list

7. Reload your Application. This time you will need to update the [Webtop] option

8. Go to the Custom Content Tab. Locate your Super Hero admin and create some Heroes (or Villains!)

Formtools

Formtools is essentially a library of clever UI controls that react dynamically to the metadata encapsulated in your content type definition.

There's an extensive number of configuration options for every UI control. You can bypass FarCry's automated layout engine and hand code your forms using the controls if required. You can also override the behaviour of the default controls or create your own controls entirely.

So without going into the detail behind how formtools works - what's in it for the FarCry developer? Well most of the time you will never have to build an administration interface for your content types. Seriously.

Next we will extend our simple superHero content type to leverage these "formtool" features. We're focusing on a selection of the individual property tags in superHero.cfc for the sake of brevity so be sure to fill in the gaps.

Check out the code sample on this page, and pay particular attention to the attributes starting with "ft".

./myproject/packages/types/superHero.cfc

Form Layout

By modifying the ftSeq and ftFieldset attributes we can order form fields and group them into specific field sets. Every field sharing the same fieldset value will appear in a correctly formatted field grouping in the edit handler.

Form UI Controls

There are several ft attributes that are common across all formtools, such as ftLabel which provides a text label for the form field.

General Formtool Property Options