Page Comparison

...

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.

Changes should include:

updated validation options to reflect shift to jquery/jqueryui
- http://docs.jquery.com/Plugins/validation
- http://bassistance.de/jquery-plugins/jquery-plugin-validation/

Objectives

Excerpt
This unit covers the fundamental building blocks of any FarCry application: the Content Type. By the end of this unit you should be able to create and deploy your own content types.

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.

...

Excerpt
This unit covers the fundamental building blocks of any FarCry application: the Content Type. By the end of this unit you should be able to create and deploy your own content types.

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.

Mockup

	SuperHero
	SuperHero
Version	1
Name	SuperHero

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.

Mockup

	SuperPower
	SuperPower
Version	1
Name	SuperPower

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.

Mockup

	SuperGroup
	SuperGroup
Version	1
Name	1SuperGroup

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.

...

Tip
types is an abstract class that contains a number of system attributes/properties that are inherited by any custom content type.
Warning

Walkthrough: Creating Super Hero

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

Create a new file called superHero.cfc and save this into your project's ./packages/types directory.
Copy the following code into this file, save and review with the instructor
Code Block

...

title ./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>

Go to the FarCry Webtop and deploy the content type: ADMIN > Developer Utilities > COAPI Tools > Types
Locate your new content type, "superHero" and select DEPLOY.
Click on the [Scaffold] button now to create an Administration scaffold

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

put in a title for your administration list

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

Info

title	Basic Scaffolding

The Scaffold option for deployed content types generates some sample code you can use to get started right away.
"Create type admin interface" creates a small XML file that generates a menu item for you in the FarCry webtop.
The framework provides a default edit handler and display view so no need to add anything else here just yet.

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

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

Info

title	Editing Content Types

When you created your first superHero object you may have noticed a rudimentary edit handler allowing you to key in details, save and update. That's not actually part of the scaffold code that was generated at all. The edit handler is dynamically generated at run time based on the metadata associated with the superHero component's cfproperty tags. Ok. So its pretty minimalist now but wait.. it's only the beginning.

Warning

title	Wait Up!

Make sure you understand the concept of extends, displayname and property type before the instructor starts babbling on about something else.

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".

<!--- .

Code Block

title	./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."
		ftSeq="1" ftFieldset="General Details" ftLabel="Title" />
	<cfproperty
		name="secretHideout" type="string" hint="The secret hideout location of the super hero"
		ftSeq="2" ftFieldset="General Details" ftLabel="Secret Hideout" />
	<cfproperty
		name="teaser" type="longchar" default="" hint="Mini intro for super hero biography."
		ftSeq="3" ftFieldset="General Details" ftLabel="Teaser" />
	<cfproperty
		name="biography" type="longchar" default="" hint="Super hero biography."
		ftSeq="4" ftFieldset="General Details" ftLabel="Biography"
		ftType="richtext" />
	<cfproperty
		name="imgHero" type="string" hint="The source image to upload"
		ftSeq="10" ftFieldset="Imagery" ftLabel="Hero Image"
		ftType="image" ftDestination="/images/superHero/imgHero" ftImageWidth="120" ftImageHeight="120" ftAutoGenerateType="fitInside" />
</cfcomponent>

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.

Tip

title	ftHelpTitle and ftHelpSection

If you are feeling really adventurous you could add ftHelpTitle and ftHelpSection to the very first cfproperty of each fieldset and you'll get a nicely formatted inline help message allowing you to describe what the fieldset is all about.

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.

...

Code Block

title	Example ftType="richtext" Formtool Control

<cfproperty
	name="Body" type="longchar" hint="Main body of content." required="no" default=""
	ftSeq="12" ftFieldset="Body" ftWizardStep="Body" ftLabel="Body"
	ftType="richtext"
	ftImageArrayField="aObjectIDsaMedia" ftImageTypename="dmImage" ftImageField="StandardImage"
	ftTemplateTypeList="dmImage,dmFile,dmNavigation,dmHTML" ftTemplateWebskinPrefixList="insertHTML"
	ftTemplateSnippetWebskinPrefix="insertSnippet" />
<cfproperty
	name="aObjectIDsaMedia" type="array" 	hint="Holds objects to be displayed at this particular node.  Can be of mixed types." required="no" default=""
	ftSeq="13" ftFieldset="Relationships" ftWizardStep="Body" ftLabel="Associated Media"
	ftJoin="dmImage,dmFile,dmFlash" bSyncStatus="true" />

It won't surprise you to learn that the ftType attribute options begin to describe a whole library form controls that you can leverage to do your bidding including:

...

A complete compendium of formtool controls can be found on the FarCry Developer WIKI at:

http://farcrydocs.jira.farcrycore.org/p600/ – select Formtools
http://farcry.jira.com/wiki/display/FCDEV40/Form+Tool+Property+MetadataFCDEV50/Formtools
http://farcry.jira.com/wiki/display/FCDEV50/FormtoolsFCDEV40/Form+Tool+Property+Metadata

Anatomy of a Formtool

Each ftType corresponds to a specific formtool component that comprises of at least an edit, display and validation method.
The edit method defines the relevant form element, any additional semantic markup that might be relevant (such as a label) and any associated JavaScript or UI cleverness needed to render the control.

Standard formtool methods:

Edit builds the form control with associated smarts.
Display describes the semantic markup required to render a display for the property. For example, an ftType="url" will activate the URL as a link by default.
Validation provides some server side validation, and in the case of complex controls mangles the data into the format the underlying database model expects.

Best of all if you don't like the core library of widgets then you can always make your own. The core formtools can be overridden, and/or supplemented with brand new controls by deploying them through both plugins and your own project. But lets just stick to the basics for now .

Walkthrough: Using Formtools Metadata

...

Open the ./packages/superHero.cfc

Add Wizard Steps using the ftWizardStep formtool metadata

Code Block

<!--- ./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."
		ftSeq="1" ftFieldset="General Details" ftWizardStep="Teaser Information" ftLabel="Title" ftValidation="required" />
	<cfproperty
		name="secretHideout" type="string" hint="The secret hideout location of the super hero"
		ftSeq="2" ftFieldset="General Details" ftWizardStep="Teaser Information" ftLabel="Secret Hideout" />
	<cfproperty
		name="teaser" type="longchar" default="" hint="Mini intro for super hero biography."
		ftSeq="3" ftFieldset="General Details" ftWizardStep="Teaser Information" ftLabel="Teaser" />
	<cfproperty
		name="biography" type="longchar" default="" hint="Super hero biography."
		ftSeq="4" ftFieldset="General Details" ftWizardStep="Biography Details" ftLabel="Biography"
		ftType="richtext" />
	<cfproperty
		name="imgHero" type="string" hint="The source image to upload"
		ftSeq="10" ftFieldset="Imagery" ftWizardStep="Imagery" ftLabel="Hero Image"
		ftType="image" ftDestination="/images/superHero/imgHero" ftImageWidth="120" ftImageHeight="120" ftAutoGenerateType="fitInsidecenter" />

</cfcomponent>

Make sure that each <cfproperty> has a relevant ftWizardStep entry
Reload the formtool metadata and test that your wizard works.

...

Create a new ColdFusion component called ./packages/types/SuperPower.cfc
Create the following properties
- title (string; required... think ftValidation="required")
- description (longchar; try limiting the total characters to 512)
- imgPower (image; 100x100 dimensions, destination: /images/superPower/imgPower)
Deploy the content type into the database
Use the Scaffold tool in the COAPI area to create an administration page
Add a bunch of super powers to your application (ColdFusion, Flex, Flash, Photoshop, etc. ) You will find some content for powers in your media folder

Bonus Lab: Image Sourced from Library

You can easily source images from the global image library. If you have some time on your hands, try implementing the an image sourced from the library with custom crops for your local content item.

Code Block

title	Sample Code from ./myproject/packages/dmCarouselItem.cfc


<cfproperty name="imageSourceID" type="string"
	ftSeq="2" ftFieldset="General Details" ftLabel="Source Image"
	ftType="uuid" ftJoin="dmImage"
	ftHint="Select an image from the image library or create a new image.">

<cfproperty name="imageCarousel" type="string"
	ftSeq="3" ftFieldset="General Details" ftLabel="Carousel Image"
	ftType="image" ftDestination="/images/dmCarouselItem/imageCarousel"
	ftAllowUpload="false" ftSourceField="imageSourceID:SourceImage"
	ftAutoGenerateType="center" ftImageWidth="620" ftImageHeight="200"
	ftQuality="0.8" ftInterpolation="blackman">

<cfproperty name="imageThumbnail" type="string"
	ftSeq="4" ftFieldset="General Details" ftLabel="Thumbnail Image"
	ftType="image" ftDestination="/images/dmCarouselItem/imageThumbnail"
	ftAllowUpload="false" ftSourceField="imageSourceID:SourceImage"
	ftAutoGenerateType="center" ftImageWidth="95" ftImageHeight="30"
	ftQuality="0.8" ftInterpolation="blackman"
	ftHint="">

Versions Compared

Old Version 10

New Version Current

Key

Objectives

Objectives

Super Hero Handbook

Content Types

The Super Hero

The Super Power

Super Hero Handbook

Content Types

The Super Hero

The Super Power

The Super Group

Building a Content Type

Walkthrough: Creating Super Hero

Formtools

Form Layout

Form UI Controls

Anatomy of a Formtool

Walkthrough: Using Formtools Metadata

Bonus Lab: Image Sourced from Library