Farcry and Extensibility
One of the most outstanding features of Farcry is it's extensibility. First, let me say that I am still learning the full extent of Farcry's power and extensibility. When I went to install my own tool into the webtop I must confess I was prepared for an afternoon of trial and error. I had my comfort food, soothing music and serenity prayer standing by just in case. As it turns out, I did not need any of those things.
...
Inside this packages/types folder you will see an individual cfc corresponding to each of the individual Farcry types. Let's use a specific example. A navigation node in Farcry is a of the type dmNavigation. If you look into the /packages/types/ folder you will see a dmNavigation.cfc file. When you create or view a "navigation node" in Farcry you are manipulating this "type".
Extending a "type"
Here's the neat thing. When Farcry first initializes it checks your project folder to see if there is a packages/types/typename.cfc file there. If there is one of these files, Farcry will automatically use it in lieu of the core type component. Sounds dangerous doesn't it? Actually, it's as easy as extending the core type.
...
| Code Block |
|---|
<cfproperty name="listStyle" type="string" hint="Add style to dmNavigation elements"> |
Refresh the app scope again and something magical happens. Not only is there now a new property added to dmNavigation, there is a new column added to the database. You'll need to deploy the new property to the database. You can do this by going to the webtop, ADMIN > COAPI Utilities > Types. Locate the content type and deploy the property.
That's right - the fourq system (a brokering system that allows for the support of various db platforms through a single interface) picks up the new property and alters your DB schema to include the new column. The type="string" attribute of the property dictates the data type. Farcry supports the following types through fourq.
...
In other words, if you enter a property with a type of "string" the system will create a column in your dmNavigation table named after your property with a character type and a length of 255 chars. So, if (using MSSQL) you examined the dmNavigation table after adding the property above you would see a new column called "listStyle" set to varchar(255).
Next Steps
So adding a property preps the database and ensures that the property will be present in all your calls to that object. But how do you get it populated? After all the form doesn't automatically contain a text box for the property - does it? For that you will need to use your extended component and override the edit function. Here are the steps.
...
| Code Block |
|---|
<cfset title = stObj.title> <cfset externalLink = stObj.externalLink> <cfset lNavIDAlias = stObj.lNavIDAlias> <cfset fu = stObj.fu> <cfset propertyname = stObj.propertyname> |
|
Add
...
a
...
new
...
form
...
element
...
into
...
the
...
form
...
to
...
handle
...
the
...
new
...
property.
...
Make
...
sure
...
and
...
populate
...
it
...
with
...
your
...
property
...
variable
...
like
...
so:
| Code Block |
|---|
<label for="propertyname"><b>property name label:</b> <textarea name="propertyname" cols="42">#propertyname#</textarea> </label> |
Now, when someone goes to edit a dmNavigation item from this project, your new edit form is called instead of the default edit form. The update and create functions automatically take care of themselves. NOTE: You may need to override other items in your type component. For example, we created new includes for renderOverview and renderObjectOverview, and overrode those 2 functions in our dmNavigation.cfc.
Wrap Up
You might be wondering why we would go through the trouble to do this. In our case we were using dmNavigation to support a non-typical navigation tree and behavior. We need to be able to specify the "width" of a particular LI tag. It seemed easiest to us to simply add that property to the dmNavigation item and use it inside of our navigation custom tag, then include how to adjust for width in our training.
...