Advanced ColdFusion Custom Tags With Ben Nadel

Viewing slide 0 of 0
  1. Ben Nadel

    • Chief Software Engineer, Epicenter Consulting
    • Author of Kinky Solutions blog (
    • Adobe Community Expert
    • Adobe Certified ColdFusion Developer
    • Co-Manager New York ColdFusion User Group
    • ColdFusion, XHTML, CSS, Javascript Developer
  2. What Are ColdFusion Custom Tags?

    • ColdFusion custom tags are user-created tags that extend the ColdFusion tag set
    • Written in ColdFusion
    • Executed on the server as part of the ColdFusion page request
    • Used along side standard ColdFusion tags
    • Locally available or shared across applications
  3. Why Use ColdFusion Custom Tags?

    • Code Reuse
    • Encapsulation
    • Abstraction
    • Simplification
    • Customized Control Flow
    • Packaging
  4. What About ColdFusion Components?

    I use CFCs for that stuff. Why would I use Custom Tags?

    Everything you can do with Custom Tags, you can also do with Components ... But,

    • Custom Tags can sometimes offer a more natural feeling integration
    • I'm not here to sell you on custom tags as being better than CFCs!
  5. ColdFusion Custom Tags - The Basics

    • Storing custom tags
    • Invoking custom tags: CF_, CFModule, CFImport
    • Execution: Open / Close / Self-Close
    • Scopes: Attributes, ThisTag, Caller, Variables
    • Passing data to / from custom tags

    Skip to the Advanced »

  6. Storing Custom Tags

    • In an application folder / sub-folder
    • In ColdFusion custom tags directory (or sub-directory)
    • In a folder defined in the ColdFusion administrator

  7. ColdFusion 8 Application-Specific Mappings

    • THIS.CustomTagPaths (Application.cfc)
    • Comma-separated list of paths
    • Has higher precedence than ColdFusion Admin settings
    • Create application-specific custom tag mappings (does not affect global mappings as defined in CF Admin)

    Run Demo (Demo 2)

  8. Calling Custom Tags (CF_)

    • <cf_TagName>
    • Looks for "TagName.cfm" ColdFusion template in the following directories:
      • Same directory as the calling CFM template
      • Application-specific tags directory (or sub-directory recursively)
      • ColdFusion custom tags directory (or sub-directory recursively)
      • Directory defined in the ColdFusion Admin (or sub-directory recursively)

    Run Demo (Demo 3)

  9. Calling Custom Tags (CFMODULE / Name)

    • <cfmodule name="TagName">
    • Looks for "TagName.cfm" ColdFusion template in the following directories:
      • Application-specific tags directory (or sub-directory recursively)
      • ColdFusion custom tags directory (or sub-directory recursively)
      • Directory defined in the ColdFusion Admin (or sub-directory recursively)
    • You can provide location-specific tag:
      • <cfmodule name="SubDirectory.TagName">
      • Note: Name-spacing your tag name prevents recursive search
    • Name attribute can be dynamic!

    Run Demo (Demo 4)

  10. Calling Custom Tags (CFMODULE / Template)

    • <cfmodule template="TagPath">
    • Executes the template, "TagPath," as a custom tag
    • Template can use path relative (ex. ./template.cfm)
    • Template can use mapped path (ex. /tags/template.cfm)
    • Template attribute can be dynamic!
    • Cannot be used with Name attribute

    Run Demo (Demo 5)

  11. Calling Custom Tags (CFIMPORT)

    • <cfimport prefix="utility" taglib="./tags/" />
    • <utility:TagName>
    • CFImport allows you to import an entire directory of custom tags
    • Custom tags are executed using defined prefix
    • Looks for "TagName.cfm" ColdFusion template in the directory defined by "tablib" attribute
    • CFImport tag must be in every template that uses imported tags
    • Tags imported at compile time! (cannot use app-specific mappings)

    Run Demo (Demo 6)

  12. Executing Custom Tags

    • Open: <cf_TagName>
    • Open/Close: <cf_TagName>...</cf_TagName>
    • Self-Close: <cf_TagName />
    • Applies to all calling methods (CF_, CFModule, CFImport)
    • "Open" executes "Start" mode of a custom tag
    • "Close" executes "End" mode of a custom tag

    Run Demo (Demo 7)

  13. Anatomy Of A Custom Tag

    • Each custom tag is executed in its own page context and has the following structures:
      • ExecutionMode - Start, End, or Inactive
      • HasEndTag - True / False
      • GeneratedContent - The generated content produced in the body of the tag
      • Note: Will contain data cache if using CFAssociate
    • CALLER
      • Reference to calling page's context
      • Has some special reference behavior
      • The custom tag has its own variables scope
      • Unscoped variables get stored here
      • Collection of attributes defined in tag execution

    Run Demo (Demo 8)

  14. Passing Data To A Custom Tag

    • Custom tags have access to the usual scopes: APPLICATION, SESSION, REQUEST, URL, FORM, CGI, etc.
    • Best to pass data in as name/value attributes:
    • <cf_TagName name="Ben" group="admin" />
    • <cf_TagName attributecollection="#attribs#" />
    • Note: With CFModule, cannot define name/template in attributeCollection

    Run Demo (Demo 9)

  15. Returning Data From A Custom Tag

    • There's no explicit "return" statement, nor does any data need to be returned
    • Use the CALLER scope to store data into calling page
    • <cfset CALLER[ strReturnVariable ] = objReturnData />
    • CALLER scope has special "key" behavior - like ColdFusion dynamic naming
    • CALLER[ "REQUEST.Data" ] - stores "Data" key in REQUEST scope
    • URL[ "REQUEST.Data" ] - stores "REQUEST.Data" key in URL scope

    Run Demo (Demo 10)

  16. Generating And Leveraging Output

    • THISTAG.GeneratedContent contains any output generated by the body of the custom tag
    • Includes content between:
      • Open/Close tags of calling page
      • Output inside custom tag
      • Output of nested tags
    • THISTAG.GeneratedContent can be treated like a variable (manually set)
    • When custom tag finished executing, THISTAG.GeneratedContent is rendered
    • You cannot use CFFlush inside custom tags
    • <cfsetting enablecfoutputonly="true" /> is a stack, not a setting

    Run Demo (Demo 11)

  17. Exiting A Custom Tag

    • Custom tag will exit naturally when done executing
    • Use CFExit tag for greater control
    • <cfexit method="exittag" />
    • CFExit has following method attribute values:
      • ExitTag - Exits custom tag execution
      • ExitTemplate - Exits current "mode" of execution
      • Loop - Exits "End" mode and re-executes Body / End mode

    Run Demo (Demo 12)

  18. Nesting Custom Tags

    • Nesting tags in ColdFusion is something we do all the time (ex. CFHttp / CFHttpParam)
    • Custom tags can be nested in the same manner
    • Nested tags are not required to communicate
    • Parent tags do not know about their children until "body" has executed
    • Child tags know about their parent tags immediately
  19. Passing Data To A Child Tag

    • Child tag generally collects data in the calling context (not from parent tag)
      • Tag Attributes
      • Tag Body
    • Parent tag cannot actively communicate with child tag
    • Child tag must read from / write to parent tag
  20. Reading Parent Data From A Child Tag

    • Child tag can get a handle on parent tag context
    • Child tag can read values directly out of parent context
    • GetBaseTagList() - Gets list of parent tags (custom and other)
    • GetBaseTagData() - Gets the context of the given parent tag

    Run Demo (Demo 13)

  21. Passing Data Up To A Parent Tag

    • Child tag can write values directly into parent context
    • GetBaseTagData() - Gets the context of the given parent tag
    • Child attributes can be automatically stored in parent ThisTag scope
    • <CFAssociate basetag="" datacollection="" />

    Run Demo (Demo 14)

  22. Defining And Using Functions Inside Custom Tags

    • You can define User Defined Functions (UDFs) inside custom tags
    • UDFs can be invoked in same tag
    • UDFs can be invoked from child tags
    • UDF execution is bound to calling context (not defining context)

    Run Demo (Demo 15)

  23. Hacking UDFs To Work With Defining Context

    • You cannot implicitly bind UDF to defining context
    • You can access defining context at run time
      • Caution - Not always possible!

    Run Demo (Demo 16)

  24. Technically Speaking, That's All There Is

    • Custom Tags are not too complicated
    • Not much more than encapsulated page execution
    • Real magic is in how you apply them
  25. Real-World Examples

    • Explore some code!
  26. Regular Expression Loop

    • Like standard CFLoop tag
    • Loop over regular expression pattern matches
    • Uses more powerful Java Regular Expression engine

    Run Demo (Demo 17)

  27. Regular Expression Loop With A ColdFusion Component

    • I already have a CFC for regular expression iteration!

    Run Demo (Demo 18)

  28. Custom Tags As Functional Facades (RELoop)

    • Best of both worlds
    • Leverage existing ColdFusion components
    • Create clean, simple interfaces via Custom Tags

    Run Demo (Demo 19)

  29. Gathering And Consuming Data In One Step

    • Using Custom Tags as functional facades
    • Implicit execution
    • Tag interfaces meant purely for gathering data

    Run Demo (Demo 20)

  30. Abstracting User Interface Modules

    • Define interface data, not implementation
    • Centralized rendering

    Run Demo (Demo 21)

  31. Leverage Relative Addressing Of Templates

    • Use custom tag as a proxy for CFC creation
    • CFC names are relative to tag proxy location

    Run Demo (Demo 22)

  32. Creating Custom Work Flows: SwitchLoop.cfm

    • Like CFSwitch, but will allow "resetting" of expression

    Run Demo (Demo 23)

  33. Creating Custom Work Flows: RandomSwitch.cfm

    • Like CFSwitch, but single case will randomly execute
    • Requires multi-pass work flow

    Run Demo (Demo 24)

  34. Recursive Custom Tags

    • Custom tags can be called recursively

    Run Demo (Demo 25)

  35. Executing Components As Custom Tags

    • Railo can execute a CFC as if it were a custom tag
    • We can do that ... sort of

    Run Demo (Demo 26)

  36. ColdFusion Custom Tag Resources

    • ColdFusion Live Docs
  37. Thank You For Listening

    • Ben Nadel
    • Blog:
    • Email:
    • Ask Ben:
    • Consulting: