Neptune 1.0 Beta 3 Documentation: Custom Tags

Neptune Information

Download from RIA Forge

Custom Tags

ColdFusion Versions

If you are using ColdFusion 8 or better, then feel free to ignore this page as Neptune will handle Application-specific custom tag mappings for you. If you are using an earlier version then read on...

The documentation examples all use "cf_" syntax to reference custom tags, but that is not a requirement to use Neptune. In fact, you have several options for custom tag usage which we will cover in order of our preference (which you should feel free to ignore in favor of your own).

Custom Tags in CustomTags folder

Ideally, all of the custom tags and the com.sebtools package should be stored in your server's CustomTags directory and custom tags should be referenced with "cf_" syntax. This allows you to have multiple sites using the same custom tags and keeps them outside the web root.

THIS.customTagPaths

If you do not have access to the server's CustomTags folder or do not wish to use it then you can use the "THIS.customTagPaths" property of Application.cfc (in ColdFusion 8 or better) to allow you to use "cf_" syntax to reference custom tags that are stored within your site.

Remember, however, that CFC should be stored in the path referenced ("[root]/com/sebtools", for example) or should have Application-specific mappings created for them as well.

See Simon Whately's excellent Application-Based Paths in ColdFusion blog entry for more details.

As of 1.0 Beta 1.5, Neptune does not include Application.cfc, but that should be remedied in an upcoming version.

CFIMPORT

If you do not have access to the server's CustomTags folder and you are not running ColdFusion 8 or better (or you do not wish to set up a CustomTagsPath on your site), then you can use CFIMPORT to reference your custom tags.

This, however, does require a code change from the examples. It also requires a CFIMPORT statement on every page.

So, this code:

<cf_PageController>

<cf_layout>
<cf_layout showTitle="true">

<cf_sebForm />

<cf_layout>

Would become this with CFIMPORT:

<cfimport taglib="/CustomTags/" prefix="tag">
<tag:PageController>

<tag:layout>
<tag:layout showTitle="true">

<tag:sebForm />

<tag:layout>

In good news, any code downloaded from the generator can be downloaded as "cf_" syntax or as CFIMPORT syntax. Moreover, you can upload a zip of any Neptune code to the generator's transformations page and have it change it from "cf_" syntax to CFIMPORT syntax or vice versa. The page has a number of other transformations that should mostly be of interest for the few of us that have been using Neptune for a long time and wish to update to the newest syntax available.

CFMODULE

If you don't like any of the previous options, you can also use CFMODULE syntax.

This, however, does require a code change from the examples.

So, this code:

<cf_PageController>

<cf_layout>
<cf_layout showTitle="true">

<cf_sebForm />

<cf_layout>

Would become this with CFMODULE:

<cf_Module template="/CustomTags/PageController.cfm">

<cf_Module template="/CustomTags/layout.cfm">
<cf_Module template="/CustomTags/layout.cfm" showTitle="true">

<cf_Module template="/CustomTags/sebForm.cfm" />

<cf_Module template="/CustomTags/layout.cfm">

While this code will work, Neptune doesn't have any built tools to translate to or from this syntax.