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
"We provide IoT solutions. We provide the most compatible solutions for many applications. Our solutions are industry agnostic and also protocol agnostic," explained Richard Han, Head of Sales and Marketing and Engineering at Systena America, in this SYS-CON.tv interview at @ThingsExpo, held June 6-8, 2017, at the Javits Center in New York City, NY.
SYS-CON Events announced today that Calligo, an innovative cloud service provider offering mid-sized companies the highest levels of data privacy and security, has been named "Bronze Sponsor" of 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. Calligo offers unparalleled application performance guarantees, commercial flexibility and a personalised support service from its globally located cloud plat...
Internet of @ThingsExpo, taking place October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 21st Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal and enterprise IT since the creation of the Worldwide Web more than 20 years ago. All major researchers estimate there will be tens of billions devic...
"The Striim platform is a full end-to-end streaming integration and analytics platform that is middleware that covers a lot of different use cases," explained Steve Wilkes, Founder and CTO at Striim, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
"We are focused on SAP running in the clouds, to make this super easy because we believe in the tremendous value of those powerful worlds - SAP and the cloud," explained Frank Stienhans, CTO of Ocean9, Inc., in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
DX World EXPO, LLC., a Lighthouse Point, Florida-based startup trade show producer and the creator of "DXWorldEXPO® - Digital Transformation Conference & Expo" has announced its executive management team. The team is headed by Levent Selamoglu, who has been named CEO. "Now is the time for a truly global DX event, to bring together the leading minds from the technology world in a conversation about Digital Transformation," he said in making the announcement.
SYS-CON Events announced today that DXWorldExpo has been named “Global Sponsor” of 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. Digital Transformation is the key issue driving the global enterprise IT business. Digital Transformation is most prominent among Global 2000 enterprises and government institutions.
SYS-CON Events announced today that Datera, that offers a radically new data management architecture, has been named "Exhibitor" of 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. Datera is transforming the traditional datacenter model through modern cloud simplicity. The technology industry is at another major inflection point. The rise of mobile, the Internet of Things, data storage and Big...
"MobiDev is a Ukraine-based software development company. We do mobile development, and we're specialists in that. But we do full stack software development for entrepreneurs, for emerging companies, and for enterprise ventures," explained Alan Winters, U.S. Head of Business Development at MobiDev, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
"We've been engaging with a lot of customers including Panasonic, we've been involved with Cisco and now we're working with the U.S. government - the Department of Homeland Security," explained Peter Jung, Chief Product Officer at Pulzze Systems, in this SYS-CON.tv interview at @ThingsExpo, held June 6-8, 2017, at the Javits Center in New York City, NY.
While the focus and objectives of IoT initiatives are many and diverse, they all share a few common attributes, and one of those is the network. Commonly, that network includes the Internet, over which there isn't any real control for performance and availability. Or is there? The current state of the art for Big Data analytics, as applied to network telemetry, offers new opportunities for improving and assuring operational integrity. In his session at @ThingsExpo, Jim Frey, Vice President of S...
SYS-CON Events announced today that DXWorldExpo has been named “Global Sponsor” of 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. Digital Transformation is the key issue driving the global enterprise IT business. Digital Transformation is most prominent among Global 2000 enterprises and government institutions.
In his opening keynote at 20th Cloud Expo, Michael Maximilien, Research Scientist, Architect, and Engineer at IBM, discussed the full potential of the cloud and social data requires artificial intelligence. By mixing Cloud Foundry and the rich set of Watson services, IBM's Bluemix is the best cloud operating system for enterprises today, providing rapid development and deployment of applications that can take advantage of the rich catalog of Watson services to help drive insights from the vast t...
SYS-CON Events announced today that EnterpriseTech has been named “Media Sponsor” of 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. EnterpriseTech is a professional resource for news and intelligence covering the migration of high-end technologies into the enterprise and business-IT industry, with a special focus on high-tech solutions in new product development, workload management, increased effic...
SYS-CON Events announced today that Massive Networks, that helps your business operate seamlessly with fast, reliable, and secure internet and network solutions, has been named "Exhibitor" of 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. As a premier telecommunications provider, Massive Networks is headquartered out of Louisville, Colorado. With years of experience under their belt, their team of...
SYS-CON Events announced today that Cloud Academy named "Bronze Sponsor" of 21st International Cloud Expo which will take place October 31 - November 2, 2017 at the Santa Clara Convention Center in Santa Clara, CA. Cloud Academy is the industry’s most innovative, vendor-neutral cloud technology training platform. Cloud Academy provides continuous learning solutions for individuals and enterprise teams for Amazon Web Services, Microsoft Azure, Google Cloud Platform, and the most popular cloud com...
SYS-CON Events announced today that Cloudistics, an on-premises cloud computing company, has been named “Bronze Sponsor” of 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. Cloudistics delivers a complete public cloud experience with composable on-premises infrastructures to medium and large enterprises. Its software-defined technology natively converges network, storage, compute, virtualization, and ...
SYS-CON Events announced today that CHEETAH Training & Innovation 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. CHEETAH Training & Innovation is a cloud consulting and IT training firm specializing in improving clients cloud strategies and infrastructures for medium to large companies.
SYS-CON Events announced today that Datanami has been named “Media Sponsor” of 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. Datanami is a communication channel dedicated to providing insight, analysis and up-to-the-minute information about emerging trends and solutions in Big Data. The publication sheds light on all cutting-edge technologies including networking, storage and applications, and thei...
The current age of digital transformation means that IT organizations must adapt their toolset to cover all digital experiences, beyond just the end users’. Today’s businesses can no longer focus solely on the digital interactions they manage with employees or customers; they must now contend with non-traditional factors. Whether it's the power of brand to make or break a company, the need to monitor across all locations 24/7, or the ability to proactively resolve issues, companies must adapt to...