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: March 23, 2009
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:
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.]
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!
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.