Guide to ColdFusion Administrator Extensions

Introduction

Welcome to the ColdFusion Administrator Extension Guide. For a few releases now ColdFusion has supported the addition of extensions to the ColdFusion Administrators. Basically this is just the ability to add to the navigation menu of your Administrator. Only a few people have done it and I thought that a simple guide to create an extension and an set of tips would perhaps encourage others to write their own extensions. I've also included a list of known extensions at the bottom of this page. Please email me if you would like to have your extension added.

Last Updated: November 13, 2008

Adding Links

At a basic level, the documented support for extending the Administrator is based on adding links. You have two ways of doing this.

The first, and older method, is to create a file named extensionscustom.cfm. This file is saved in the administrator folder. The file should only contain links. Since the Administrator uses frames, you should specify a target of content to keep any content you create within the frame:

<a href="foo.cfm" target="content">Foo</a><br/>
<a href="goo.cfm" target="content">Goo</a><br/>

You can add any number of links and they will appear in the left hand navigation under a section called Custom Extensions. Here is an example:

While this works, a better method was added to ColdFusion 8. (Props go to Jason Delmore for "sneaking" this in. Shhh, don't tell anyone!) Inside your administrator folder you will find a file named custommenu.xml. If you open this in an editor you will see:

<?xml version="1.0" encoding="iso-8859-1"?>
<menu>
<!-- To use the xml custom menu extension simply copy and modify the following example <menu> block. Treat menuitem as you would an anchor tag. The submenu label attribtute will be shown as a top-level button on the menu.
   The first menuitem is an example of targetting the main content frame.
   The second menuitem is an example of opening up new window.
   The third menuitem is an example of using javascript to open up new windows with size specifications or tabs

   <submenu label="Custom Server Settings">
      <menuitem href="settings/server_settings.cfm" target="content">Settings</menuitem>
      <menuitem href="settings/limits.cfm" target="_blank">Request Tuning</menuitem>
      <menuitem href="javascript:var newwin = window.open('settings/caching.cfm','newwin','height=200,width=400,status=yes,toolbar=no,resizable=yes,titlebar=no');" target="_self">Caching</menuitem>
   </submenu>
-->

</menu>

This is a simple XML file that you can use to add your own links. Unlike the previous method, however, you can add your own sections as well. You could create one section for various security tools and another for items related to server management. Here is a simple example:

<submenu label="My Tools">
   <menuitem href="spoolmail/" target="content">SpoolMail</menuitem>
</submenu>

This creates a section named My Tools with one link to a folder with the name SpoolMail. This renders in your browser like so:

Creating Extensions

Now that you know how to create the link, how do you actually create the extension? In general you can write any code you want to for your extension. So for example, you could add a basic clock to your Administrator like so:

1. Add this to custommenu.xml

<submenu label="My Tools">
   <menuitem href="time.cfm" target="content">The Time</menuitem>
</submenu>

2. Create a new file named time.cfm and use this code:

<cfoutput>The time is #timeFormat(now())#.</cfoutput>

3. Reload your ColdFusion Administrator and click on The Time:

That's it! Of course, it looks rather ugly. There are two quick tweaks we can do to pretty things up a bit. First, we can include header.cfm and footer.cfm:

<cfinclude template="header.cfm">

<cfoutput>The time is #timeFormat(now())#.</cfoutput>

<cfinclude template="footer.cfm">

These two files exist in the Administrator folder and create - as you can guess, the top and bottom UI used in the rest of the site. Unfortunately the Administrator code is encrypted so we can't see how they build pages, but we can easily view source. Doing so reveals that a particular class is used for page titles. We can add that as well:

<cfinclude template="header.cfm">

<h2 class="pageHeader">The Time</h2>

<cfoutput>The time is #timeFormat(now())#.</cfoutput>

<cfinclude template="footer.cfm">

Now we are getting somewhere! [Note - I may build out a full CSS list later on if people want. Basically I just worked on what I saw in view source for things like tables and forms.]

Tips

In no particular order, here are some tips to consider when building extensions.

Folders

While it may be obvious, you should build your extension in a subfolder under the administrator folder. This way there won't be conflicts with Adobe-provided files. Also, if an upgrade wipes out the root folder, this provides an easy way for you to quickly copy out your extension. If you do use a folder, be sure to edit the cfincludes for the header and footer.

Security

If you place your files under the administrator folder, they will automatically be protected by the ColdFusion Administrator's security system UNLESS you use your own Application.cfm file. If you do, be sure to add this line of code:

<cfinclude template="../Application.cfm">

This will ensure the built-in Administrator security is run before your custom code.

You are not required to place your files under the administrator so this may not be a concern for you.

Security 2

Unfortunately, if you use Administrator User Roles under ColdFusion 8, non-Admin users will not be able to run your extensions.

Last Page Support

If you want the Administrator to remember your page as the last one visited (like it does for other pages), add the following code to your extension:

<cfset cookie.CFADMIN_LASTPAGE_ADMIN = cgi.SCRIPT_NAME>

Thanks go to Yaron Kohn for this tip!

Extension List

The following is a list of known extensions. Please send me any ones you would like to add to this list. I'm also include links to projects that include support for custom extensions. While the project may not solely be an extension, it shows an example of using this feature.

  • SpoolMail - A free, open source extension that gives you the ability to read undelivered mail created by ColdFusion. For developers working on a local system with no mail server, this is an excellent way to check the email your application is generating.
  • Seeker - A ColdFusion-Lucene integration kit, the project also includes an extension to help yo manage your Lucene collections.
  • Cache Clearer - When you enable caching in the ColdFusion Administrator, the only way you can clear the cache is by clearing the entire machine cache. This extension lets you specify a file or folder and only CFMs and CFCs under that folder will be cleared.
  • Verity Searcher - A tool to let you quickly search Verity collections from the Administrator. Useful for ad hoc queries against collections without needing to build a temporary script.
  • CertMan - A Coldfusion Administrator Extension that allows adding/viewing/removing of SSL certificates in the Java certificate store from within the Administrator.
  • CFAdmin Utility Extensions - Some common utilities for the ColdFusion administrator. Things that are hidden or take multiple clicks are just now 2 clicks away.
  • CodeCop - CodeCop is a ColdFusion code checker. It will read selected code on the local system and report back possible issues.