The type components in Farcry provide a way to extend the data that is managed by Farcry and stored in the Farcry database. Farcry provides not just add, edit, and delete functionality, but also automagically creates the database table based on the component, creates and deletes columns (with basic column typing) based on new or removed properties, and incorporates the required and default attributes of those properties.

This means that any data your web application requires can potentially be managed within Farcry.

Designing the Component

Custom FarCry types are components kept in the farcry_yourproject/packages/types/ directory. Your custom type component should have a bCustomType="1" attribute in the component tag. The naming convention for type component filenames is abTypeName, where ab are your initials.

The Types Base Component

The component that you are creating needs to extend the types component in the FarCry core packages directory (or another core type like dmHTML). Use the package path "farcry.farcry_core.packages.types.types". This base class provides standard functions for managing the database, plugging into the administration console, and being displayed on the website. Most of these will be covered in other sections.

Types has a number of standard properties:

• objectid (uuid)
• label (nstring)
• datetimecreated (date)
• createdby (nstring)
• ownedby (nstring)
• datetimelastupdated (date)
• lastupdatedby (nstring)
• lockedBy (nstring)
• locked (boolean)

Component Type Properties

Component properties (<cfproperty ...>) are detected by FarCry and will be used to create table columns in the database.

FarCry supports several property types:

• boolean
• date
• numeric (any number)
• string (255 8bit characters)
• nstring (255 16bit characters)
• uuid
• variablename ????
• color (20 characters)
• email (up to 255 characters)
• longchar (long text)
• array (one dimensional, up to 255 characters per element)

You can also use the default and required attributes.

Deploying the Type

Implementing the new FarCry type, and changes to the name or properties is done by "Deploying" them. Go to the Admin tab of the administration console, select COAPI Management from the drop down list, and click on the Type Classes option.

At this point you will get a ColdFusion error if any of the components in the custom types directory have invalid syntax or don't meet FarCry's expectation that they will be types. A common error is to use extends="types" instead of the full package path.

If the component is sound but hasn't been deployed by FarCry, you will see a message asking whether you wish to deploy your new type. Similar messages and options are provided when FarCry detects that a deployed type has been changed (new, changed or removed properties).

NOTE: array properties are not detected properly - deploying them does implement the necessary database changes, but FarCry will not recognise them and will continue to display the deploy message.

Managing Types

In order to manage your custom type in the FarCry administration console you will have to implement further functions and files.

Listing Type Data in the Admin Console

The standard management interface for basic types provides a list of selectable records, options for manipulating them, and some search options. This is a generic interface that can be used for any type.

In the farcry_yourproject/customadmin directory, create another directory with the name of your custom type. This directory will be used to store all the management modules for the new type. In this directory create an empty cfm file for the type management list, for example listabMyType.cfm. NOTE: this file will be accessed as a module.
The first thing to do with this file is to add the standard administration console menus and styles. These are contained in the admin tag library.

To create the header, use the header tag. This tag has a title attribute, which you can set to whatever title you're using for the page.

<admin:header title="My admin page" />

The footer tag finishes the default administration display.

<admin:footer />

The list, buttons, and search are inserted with another set of tags, called widgets.

<widgets:typeAdmin typename="abYourType"
  permissionset="news"
  title="Manage YourType">
</widgets:typeAdmin>

Changing the Columns

The default set of columns is created in farcry_core/packages/farcry/typeadmin.cfc getDefaultColumns function. But if you wish, you can replace these default columns with your own.

To do this, use the typeAdminColumn tag from the widgets library inside the typeAdmin tag.

<widgets:typeAdmin typename="abYourType"
                   permissionset="news"
                   title="Manage YourType">
  <widgets:typeAdminColumn title="Colour"
                              columntype="variable"
                              value="colourprop" />
</widgets:typeAdmin>

Changing the Buttons

The default set of buttons is created in farcry_core/packages/farcry/typeadmin.cfc getDefaultButtons function. But if you wish, you can replace these default buttons with your own.

To do this, use the typeAdminButton tag from the widgets library inside the typeAdmin tag.

<widgets:typeAdmin typename="abYourType"
                   permissionset="news"
                   title="Manage YourType">
<widgets:typeAdminButton buttontype="custom"
                              name="dosomethingunique"
                              value="Do This"
                              url=http://yoursite/abc.cfm />
</widgets:typeAdmin>

Adding to the Administration Console

To add your administration page to those available on the administration console, you need to edit farcry_yourproject/customadmin/customadmin.xml.

With newer versions of FarCry you can insert your functionality into the core menu structure by making the id's of the common parents the same as those in farcry_core/config/webtop.xml.

The xml structure is:

<webtop>
  <section>
    <subsection>
      <menu>
        <menuitem />
      </menu>
    </subsection>
  </section>
</webtop>

Label, labeltype and permission can only be left out if the item is being merged.

XML Element section, subsection, menu, menuitem

XML Element menuitem

Editing a Record

When a user clicks on the edit icon of a record, the administration console loads /farcry/conjuror/invocation.cfm?objectid=#objectid#&typename=abMyType&ref=typeadmin. This template imports the console header and footer, and calls on the abMyType.edit function to create the form and handle form postback.

The base Types class does provide a default edit function, however it uses only the most basic form elements and data validation, and will not allow the user to associate the type instance with categories.

By providing your own edit function you can provide this extra functionality, and make use of a number of slick and function rich tags provided in the FarCry core for just this purpose. The standard handling of edit is:

1. Create a subdirectory in farcry_yourproject/packages/types called _abMyType. This directory will store includes for your type, allowing you to keep your code organized.
2. Create edit.cfm in this directory.
3. Create an edit function in abMyType.cfc. This function will take a required argument of type "uuid" called objectid.
4. Retrieve the type data and store it in stObj (the standard FarCry variable for instance property values) using getData.
   function types.getData()

   Argument	Description
   objectid	The objectid of the item data to retrieve.
   returnvalue	A struct. The keys are the property names, and the values are the values of the item.

5. Include _abMyType/edit.cfm
6. Put the form, and submission handling in edit.cfm. stObj will contain the current values, and you can use setData to update the values.
   function types.setData()

   Argument	Description
   stProperties	A struct with identical structure to stObj: the keys are the names of the type properties, and the values are their current values.
   user	The name of the user making the change
   auditnote	The audit note for the change
   bAudit	Defaults as 1. Set to 0 to not add this change to the audit trail
   dsn	Defaults to the applications default database

PLP (Process Logic Path)

Displaying a Record

Accesssing and Using Types

Accessing the Data

... With the Type Component

... With the Type Table

Webskins

Creating a Display Method

Adding a Selectable List of Display Methods to an Edit Form

Using a Display Method

Custom Functions

Type Metadata