Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Calling All Custom Tags Part 2

Calling All Custom Tags Part 2

In my Journeyman column last month (CFDJ Vol. 2, issue 4) we began looking at how - and why - to call custom tags in different ways.

So far, we've learned that the CF_ approach will look first locally, then in the shared \cfusion\customtags directory, while the CFMODULE NAME= approach will look only in the shared directory.

But what if you can't place files in the shared customtags directory? Perhaps you work in a tightly controlled corporate environment where you have to get all sorts of permissions to place files in the shared directory or, worse, you're in a hosted environment where you're extremely limited in what you can do and they absolutely refuse to place any tags you'd like to use in the shared directory?

Well, it's good to know that at least one solution exists. You can place the intended tag in the local directory and execute it from there using the CF_ approach. For many folks, this will be a revelation. If you have refrained until now from creating custom tags or exploring and enjoying the vast benefits of preexisting custom tags available in the Allaire Developer's Exchange (www.allaire.com), then let me welcome you to this world! You're not forced to use the shared directory. Go to town!

But there's a catch. You now know that you can place the intended custom tag in your local calling template directory and you're good to go. But what if you have code in several subdirectories? If you place the custom tag in all those directories, it will work; but you're exposing yourself to the risks and challenges of keeping all those versions updated and in sync. Of course, if you have access to the shared customtags directory, just place it there. But what if you don't? Are you forced to make those copies and suffer the indignities of multiple redundant and possibly out-of-sync versions?

A Template by Any Other Name...
Well, as always, Allaire has got you covered. If you need to execute a custom tag in someplace other than either the local directory or the shared directory, you want to use the CFMODULE TEMPLATE= approach, completing the triumvirate.

This approach allows you to name the specific location - anywhere on the CF server - in which the custom tag's file can be found. This could be used to name some alternative "global" directory that all can see or, more useful, it could name some "subglobal" directory that all the templates under the directories of a related group of applications could see. They could all point to this one directory, thus eliminating the redundancy problem.

And the coolest thing for those in a hosted or otherwise tightly controlled environment is that this "subglobal" directory, as I've termed it, could be placed anywhere in the directory structure that you do have control over, making it great for sharing a custom tag among all your (and only your) applications.

As with the CFMODULE NAME= approach, there are actually two different ways to use the TEMPLATE= approach. The first is for you to specify the physical path to the custom tag relative to the location of the caller. At the end of the last article, we introduced an example custom tag called format.cfm. If that were placed in the current directory with the template calling it, we'd be using it in what I have referred to as a "local" mode. It's intended to be used by templates in the same directory.

Using the CFMODULE TEMPLATE approach, we could call this local custom tag with the following syntax:

<CFMODULE TEMPLATE="format.cfm" TEXT="#fname#">

Note that the difference (besides use of the TEMPLATE attribute) is that the .cfm file extension is now used. Now it may appear that this is just a lot of extra work with little benefit, and in fact in this specific use you really haven't gained much over the CF_ approach. (Actually, there is one difference: it will now execute only the local version and not any shared one. But that's not usually a valuable benefit.)

But the key benefit comes when you specify some relative path information before the name of the custom tag template file name. For instance, consider a directory structure as depicted in Figure 1.

Assume we have several programs in a "mygroup" directory (under our Web root, where our Web files are located - we're not discussing here subdirectories under the shared customtags directory). If there were no further subdirectories under APP1 or APP2, then all the templates in those directories could call upon a shared customtags directory, depicted in the figure as "ourcustomtags."

Assuming our format.cfm file were placed in this directory, we could easily call it from any of our "mygroup" subdirectory templates using relative naming conventions that are common to folks familiar with using the operating system command prompt or even HTML tags like <IMG SRC> and <A HREF>. We specify a path above ours using ".." notation, which refers to our parent. And we can refer to a sibling (a directory at the same level as our own under our parent) as "..\sibling".

In our case, if our code is running in, say, the APP1 directory, we could call the format.cfm in the mygroup \ourcustomtags directory using the following syntax:

<CFMODULE TEMPLATE="..\ourcustomtags\format.cfm" TEXT="#fname#">

Notice the "..\" preceding "ourcustomtags\". These tell CF to go up to our parent and down to the ourcustomtags directory to find format.cfm. (In the last article, we learned that our fictitious format.cfm custom tag was designed to accept a parameter called "text," and we were passing it the value of a local variable called "fname.")

For those in hosted environments, this is A Good Thing, because you can use this approach to share a given custom tag among all the apps in your server directory.

The only drawback is that as soon as we start to put subdirectories under our APP1 or APP2 directories, for example, the relative paths for programs placed in those subdirectories become a little clumsy, since we now need to specify a grandparent reference, as in "..\..\ourcustomtags\format.cfm". This can become difficult to read and maintain.

My Kingdom for a Mapping
Like the cavalry coming to our rescue, Allaire foresaw this need and created an elegant - if often misunderstood, little used and rather poorly documented - solution called "directory mappings."

A directory mapping is a setting made in the ColdFusion Administrator that maps a virtual name to a physical directory path (see Figure 2).

That is, we could create a virtual name in the administrator to refer to our "mygroup\ourcustom-tags" directory with a single word. Let's say we called it "mygrouptags". (That is, let's say we had the administrator create a mapping of the word "mygrouptags" to the physical directory"c:\inetpub\wwwroot\my-group\ourcustomtags".)

Now we could refer to the tag in that location using this new mapping. The key to using mappings in the TEMPLATE= approach (as well as with CFINCLUDE, which can also use mappings) is to specify a "\" and the name of the mapping before the name of the custom tag file name. So our example would become:

<CFMODULE TEMPLATE="\mygrouptags\format.cfm" TEXT="#fname#">

Pretty nifty! And the beauty of this approach is that it doesn't matter where in our entire mygroups directory structure our calling template is located. We can even move code around within the directories and the call to the custom tag will always use this syntax to refer to the location of the custom tag. Not only that, another great benefit of directory mappings is that should anyone decide to move the "ourcustomtags" directory anywhere else in our tree structure - or really anywhere on the server - our code will again not have to change. Only the mapping in the administrator needs to change.

As with the CFMODULE NAME= approach, this call will not find a local version of the custom tag. It will find and use only that version in the named directory. And we can't really have different "versions" of the tag unless we create and use different mappings.

Furthermore, this approach opens up a bit of a security hole. You are making this mapping in the administrator; thus, technically, others on the server could become aware of and access the custom tag in your directory more easily. Of course, that's a thorny issue that deserves its own entire article. Mapping doesn't spawn the security problem in and of itself; it does, however, arguably increase exposure to the problem. There is a solution, if you're willing to make the commitment to using Advanced Security features. We'll address it briefly in a moment since it is indeed an important issue.

Getting to the "Root" of the Problem
As an aside, I said that the first TEMPLATE= approach allowed you to specify a relative path and that the second approach allows specification of a virtual path via a mapping. You may be wondering if there's a way simply to specify an absolute path. In fact, you may wonder why that "/" designation in front of the mapping name doesn't mean "look in the root." That's an interesting issue.

In fact, there is a predefined mapping called simply "/" defined in the administrator by default. And it does map to the Web root of the Web server on which CF is installed - such as c:\inetpub\wwwroot on an IIS server installed on the c: drive. So you can, in fact, use that to specify subdirectories off the root in a form that looks like an absolute path, such as "\myapp\customtags\format.cfm". This means, of course, that in some situations there is no real need to create a separate mapping for your particular directory.

Just be aware that things can get confusing in a hosted environment, where your "server" is actually just a "virtual server" under the directory tree of the entire Web server. In such a case, this "absolute" path defined in the administrator is relative to the root of the CF server, not relative to your own "virtual root."

One last note. I said that this TEMPLATE= approach allows access to a custom tag located anywhere on the CF server. If you can point to it with a relative or mapped path, you can run it. Actually, there's no limitation that says the path specified even needs to be to a file on the same server. Since we're specifying the physical path to the file, it can really be anywhere that the server can find it, whether on a mapped drive or a UNC path. As long as the server can see it, we can place and run our custom tags there.

Security Matters
When we describe the ability for custom tags to be placed and executed from shared directories, we open up the possibility that the tag can be used in an unauthorized or at least unexpected way.

If we're in a secure environment, perhaps we may have a tag that performs a function to return data that may be restricted. In a hosted environment, perhaps we have paid for a commercial custom tag and must restrict access for licensing issues.

Advanced Security to the Rescue
Again, Allaire has provided an answer, but the price to be paid is that you must enable what's called Advanced Security. This is a mode that became available in Release 4.0, but it's not the default mode of operation (which is called Basic Security).

Using Advanced Security requires considerable forethought and some rather lengthy setup procedures to create and administer users, resources and policies to map users to resources. Though the benefit is very likely well worth the price, it seems many have been slow to make the move. Maybe this is due to the rather sparse documentation or to the rather daunting user interface for administering it. Fortunately, both have been improved in 4.5. There's also coverage of the topic in Ben Forta's book Advanced ColdFusion Development, published by Que.

As for custom tags, they are just one of the many "resources" that can be protected in Advanced Security. Protectable resources actually include all manner of things such as files, directories and data sources, as well as applications, tags, functions and, indeed, custom tags.

You owe it to yourself and your organization to look into and take the time to implement Advanced Security. The benefits are manifold. And in a secured or hosted environment, it's imperative (though hosted environments are among the last to consider advanced security, paradoxically).

By the way, some presume that it's a feature available only in the Enterprise version of ColdFusion. But it's not. All that's missing from the Professional version is "Server Sandbox" security - which, while it may seem to encompass what we're describing here, in fact doesn't. Do check out Advanced Security.

Tales from the Crypt
Another matter that encompasses security is the matter of encrypting (or encrypted) custom tags. This is a process by which the CFML code within a template is manipulated in such a way (via an Allaire-provided utility) that the code is no longer human-readable. The CF Server can read and execute it, but no one looking at the file can see what the code is doing.

Encrypting tags is a valuable option for secured environments, and especially for commercially sold tags. The process is actually just an encoding, not an encryption, of the tag. In fact, as of Release 4.5, Allaire now calls it encoding, and the utility, formerly called CFCRYPT, is now called CFENCODE. For more information see the Allaire manual Developing Web Applications with ColdFusion.

You're No Custom Tag
Before concluding this discussion of custom tags, I'd be remiss not to mention a couple of related aspects of reusing code that technically don't involve custom tags but that may be of use to you as you consider whether and how to reuse code. I'll just mention these in passing for you to consider.

CFEXECUTE
The new CFEXECUTE tag in 4.5 allows you to execute any process on the server machine, including shell scripts, services, executables and batch files. See the Language Reference for more information and an example of executing the Windows NetStat network monitoring program. CFEXECUTE works in UNIX environments as well, and you can imagine that it would open the door to reusing existing user-written code also.

CFHTTP
If you want to execute some code that's not on your machine but is accessible via a Web site, whether it's a ColdFusion routine or even a CGI script, ASP page or simple HTML file, you can do that with the CFHTTP tag. This allows you to execute any page at any URL (Web site address) that can be reached from your server. You can even pass parameters to the page, such as to emulate formfields being passed to a form action page, or to pass expected cookie, cgi or URL variables to the page being executed. The result of the page execution is returned to your program in a variable called cfhttp.filecontent.

CFOBJECT
CFOBJECT allows you to call methods within COM, CORBA and Java objects. This opens the door to your calling programs written in languages other than CFML and even running on other servers than the CF server. This can be a tremendous opportunity for reusing legacy code within your organization or for simply choosing a more suitable environment for executing some process.

Java Processing
There are several other tags (and a function) for executing Java code. CFSERVLET executes a Java servlet on a JRun engine. (JRun is a technology for running JavaServer Pages and Servlets, which Allaire acquired last year.) CFSERVLET is designed to be consistent with the HTML <SERVLET> tag. Again, if you have an investment in such programs, you can reuse that code now within ColdFusion.

The createobject function allows you to create and use JAVA CFXs or objects, and by extension Enterprise JavaBean (EJB) objects. (As of 4.5, EJBs can be called via CFOBJECT as well.)

Other features you may come across for running Java objects include CF_ANYWHERE (an older form of executing servlets) and CFX_J (an older way to run Java objects now superseded by Java CFXs).

Final Thoughts
I've talked about all manner of possibilities and opportunities for using ColdFusion tags. There are a few closing notes to share that may be important.

First, I mentioned previously that you can find many (in fact, hundreds of) prebuilt custom tags at the Allaire Developer's Exchange (formerly known as the Tag Gallery). It is accessible from the Developer section of the Allaire site (www.allaire.com).

When you're working with custom tags, you may encounter an interesting problem that will arise if you move a custom tag from one directory to another (such as moving it from a local directory to the global one). If, before you move it, you execute a template that finds the custom tag in the first location, and then after you move the custom tag you execute that template again, you'll receive an error message indicating that the custom tag cannot be found. CF is still trying to find it in the original location, and even though it's been moved to a location where CF should be able to find it, it doesn't. It seems to be a template code-caching thing. The problem will be corrected if you restart the CF server process. I'm not aware of another way to resolve the problem, though I'm confident there may be one.

Also, as Ben Forta pointed out in his article "Preserve Precious Resources - Recycle" (CFDJ, Vol. 2, issue 2), the notion of paired custom tags and nested custom tags has also been enabled in Release 4. They're very useful in some situations, and they work just like the CF_ approach described above. Unfortunately, that means that they're not able to take advantage of some of the control offered by the CFMODULE approaches.

Finally, it's worth noting that with respect to all aspects of referring to file names when using custom tags, case sensitivity is significant in UNIX operating environments. The Developing Web Applications with ColdFusion manual indicates that custom tag names must be lower case on UNIX.

So that's it. It has taken me two months' worth of columns...practically a mini-novel! There's probably more to using custom tags than you originally thought. It's really great to know the power and possibilities available with them. These solutions can definitely come in handy in some environments. As always, check out the Allaire reference manuals and user guides to learn more and find real examples. But, most important, try things out yourself. There's no better way to learn!

More Stories By Charlie Arehart

A veteran ColdFusion developer since 1997, Charlie Arehart is a long-time contributor to the community and a recognized Adobe Community Expert. He's a certified Advanced CF Developer and Instructor for CF 4/5/6/7 and served as tech editor of CFDJ until 2003. Now an independent contractor (carehart.org) living in Alpharetta, GA, Charlie provides high-level troubleshooting/tuning assistance and training/mentoring for CF teams. He helps run the Online ColdFusion Meetup (coldfusionmeetup.com, an online CF user group), is a contributor to the CF8 WACK books by Ben Forta, and is frequently invited to speak at developer conferences and user groups worldwide.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


@ThingsExpo Stories
High-velocity engineering teams are applying not only continuous delivery processes, but also lessons in experimentation from established leaders like Amazon, Netflix, and Facebook. These companies have made experimentation a foundation for their release processes, allowing them to try out major feature releases and redesigns within smaller groups before making them broadly available. In his session at 21st Cloud Expo, Brian Lucas, Senior Staff Engineer at Optimizely, will discuss how by using...
In this strange new world where more and more power is drawn from business technology, companies are effectively straddling two paths on the road to innovation and transformation into digital enterprises. The first path is the heritage trail – with “legacy” technology forming the background. Here, extant technologies are transformed by core IT teams to provide more API-driven approaches. Legacy systems can restrict companies that are transitioning into digital enterprises. To truly become a lead...
SYS-CON Events announced today that Daiya Industry will exhibit at the Japanese Pavilion at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Ruby Development Inc. builds new services in short period of time and provides a continuous support of those services based on Ruby on Rails. For more information, please visit https://github.com/RubyDevInc.
As businesses evolve, they need technology that is simple to help them succeed today and flexible enough to help them build for tomorrow. Chrome is fit for the workplace of the future — providing a secure, consistent user experience across a range of devices that can be used anywhere. In her session at 21st Cloud Expo, Vidya Nagarajan, a Senior Product Manager at Google, will take a look at various options as to how ChromeOS can be leveraged to interact with people on the devices, and formats th...
SYS-CON Events announced today that Yuasa System will exhibit at the Japan External Trade Organization (JETRO) Pavilion at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Yuasa System is introducing a multi-purpose endurance testing system for flexible displays, OLED devices, flexible substrates, flat cables, and films in smartphones, wearables, automobiles, and healthcare.
SYS-CON Events announced today that Taica will exhibit at the Japan External Trade Organization (JETRO) Pavilion at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Taica manufacturers Alpha-GEL brand silicone components and materials, which maintain outstanding performance over a wide temperature range -40C to +200C. For more information, visit http://www.taica.co.jp/english/.
As hybrid cloud becomes the de-facto standard mode of operation for most enterprises, new challenges arise on how to efficiently and economically share data across environments. In his session at 21st Cloud Expo, Dr. Allon Cohen, VP of Product at Elastifile, will explore new techniques and best practices that help enterprise IT benefit from the advantages of hybrid cloud environments by enabling data availability for both legacy enterprise and cloud-native mission critical applications. By rev...
Organizations do not need a Big Data strategy; they need a business strategy that incorporates Big Data. Most organizations lack a road map for using Big Data to optimize key business processes, deliver a differentiated customer experience, or uncover new business opportunities. They do not understand what’s possible with respect to integrating Big Data into the business model.
Recently, REAN Cloud built a digital concierge for a North Carolina hospital that had observed that most patient call button questions were repetitive. In addition, the paper-based process used to measure patient health metrics was laborious, not in real-time and sometimes error-prone. In their session at 21st Cloud Expo, Sean Finnerty, Executive Director, Practice Lead, Health Care & Life Science at REAN Cloud, and Dr. S.P.T. Krishnan, Principal Architect at REAN Cloud, will discuss how they b...
Enterprises have taken advantage of IoT to achieve important revenue and cost advantages. What is less apparent is how incumbent enterprises operating at scale have, following success with IoT, built analytic, operations management and software development capabilities – ranging from autonomous vehicles to manageable robotics installations. They have embraced these capabilities as if they were Silicon Valley startups. As a result, many firms employ new business models that place enormous impor...
SYS-CON Events announced today that Dasher Technologies will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 - Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Dasher Technologies, Inc. ® is a premier IT solution provider that delivers expert technical resources along with trusted account executives to architect and deliver complete IT solutions and services to help our clients execute their goals, plans and objectives. Since 1999, we'v...
SYS-CON Events announced today that MIRAI Inc. will exhibit at the Japan External Trade Organization (JETRO) Pavilion at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. MIRAI Inc. are IT consultants from the public sector whose mission is to solve social issues by technology and innovation and to create a meaningful future for people.
SYS-CON Events announced today that TidalScale, a leading provider of systems and services, will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 - Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. TidalScale has been involved in shaping the computing landscape. They've designed, developed and deployed some of the most important and successful systems and services in the history of the computing industry - internet, Ethernet, operating s...
SYS-CON Events announced today that TidalScale will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. TidalScale is the leading provider of Software-Defined Servers that bring flexibility to modern data centers by right-sizing servers on the fly to fit any data set or workload. TidalScale’s award-winning inverse hypervisor technology combines multiple commodity servers (including their ass...
Amazon is pursuing new markets and disrupting industries at an incredible pace. Almost every industry seems to be in its crosshairs. Companies and industries that once thought they were safe are now worried about being “Amazoned.”. The new watch word should be “Be afraid. Be very afraid.” In his session 21st Cloud Expo, Chris Kocher, a co-founder of Grey Heron, will address questions such as: What new areas is Amazon disrupting? How are they doing this? Where are they likely to go? What are th...
SYS-CON Events announced today that IBM has been named “Diamond Sponsor” of SYS-CON's 21st Cloud Expo, which will take place on October 31 through November 2nd 2017 at the Santa Clara Convention Center in Santa Clara, California.
Infoblox delivers Actionable Network Intelligence to enterprise, government, and service provider customers around the world. They are the industry leader in DNS, DHCP, and IP address management, the category known as DDI. We empower thousands of organizations to control and secure their networks from the core-enabling them to increase efficiency and visibility, improve customer service, and meet compliance requirements.
Join IBM November 1 at 21st Cloud Expo at the Santa Clara Convention Center in Santa Clara, CA, and learn how IBM Watson can bring cognitive services and AI to intelligent, unmanned systems. Cognitive analysis impacts today’s systems with unparalleled ability that were previously available only to manned, back-end operations. Thanks to cloud processing, IBM Watson can bring cognitive services and AI to intelligent, unmanned systems. Imagine a robot vacuum that becomes your personal assistant tha...
SYS-CON Events announced today that IBM has been named “Diamond Sponsor” of SYS-CON's 21st Cloud Expo, which will take place on October 31 through November 2nd 2017 at the Santa Clara Convention Center in Santa Clara, California.
In his Opening Keynote at 21st Cloud Expo, John Considine, General Manager of IBM Cloud Infrastructure, will lead you through the exciting evolution of the cloud. He'll look at this major disruption from the perspective of technology, business models, and what this means for enterprises of all sizes. John Considine is General Manager of Cloud Infrastructure Services at IBM. In that role he is responsible for leading IBM’s public cloud infrastructure including strategy, development, and offering ...