Advanced ColdFusion Custom Tags With Ben Nadel Advanced ColdFusion Custom Tags With Ben Nadel

1. Ben Nadel

   

   • Chief Software Engineer, Epicenter Consulting
   • Author of Kinky Solutions blog (www.bennadel.com)
   • 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:
    • THISTAG
      • 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
    • VARIABLES
      • The custom tag has its own variables scope
      • Unscoped variables get stored here
    • ATTRIBUTES
      • 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: http://www.bennadel.com
    • Email: ben@bennadel.com
    • Ask Ben: http://www.bennadel.com/ask-ben
    • Consulting: http://www.epicenterconsulting.com