Warning | ||
---|---|---|
| ||
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:
|
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. |
...
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 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 | ||
---|---|---|
| ||
--->
<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 | ||
---|---|---|
| ||
If you are feeling really adventurous you could add |
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 | ||
---|---|---|
| ||
<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="aObjectIDs" type="array" hint="Holds objects to be displayed at this particular node. Can be of mixed types. ftTemplateSnippetWebskinPrefix="insertSnippet" /> <cfproperty name="aMedia" type="array" hint="" 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://docs.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
...