Wednesday, September 19, 2007

ColdFusion makes Worse than Failure

Today's Worse Than Failure entry looks at some ColdFusion code. I'm not sure whether this is a good thing or a bad thing. On the positive side, the WTF was more about the code itself than the language. On the negative side, it was some pretty inept code.

Labels: , , ,

posted by Luis - 2 comments

Tuesday, September 04, 2007

Documenting ColdFusion custom tags in Dreamweaver (4/4)

Part 4: Creating the Dreamweaver Extension

In part 2 we created our tag editor; in Part 3 we created our documentation. In this part we package these files up as a Dreamweaver extension. To create the extension we start with a .mxi file. Editing .mxi files can be tricky in Dreamweaver. I usually create the file as .xml, then rename it when I'm ready to create my extension. We begin by defining the name, version, Dreamweaver version required, author and description of our extension.

<macromedia-extension name="Our Template Extension" version="1.0"
type="
Suite" requires-restart="True">
<products>
<product name="
Dreamweaver" version="6" primary="true" />
</products>

<author name="
Luis Matthews" />

<description>
<![CDATA[A custom tag definition for CF_ourtemplate]]>
</description>

Next we tell Dreamweaver where to place the files we created. Some of our files go into the Taglibraries directory, others go into the Reference directory.

<files>
<file source="
cf_ourtemplate.htm"
destination="
$dreamweaver/configuration/Taglibraries/ourTags" />
<file source="
cf_ourtemplate.vtm"
destination="
$dreamweaver/configuration/Taglibraries/ourTags" />
<file source="
TagChooser.xml"
destination="
$dreamweaver/configuration/Taglibraries/ourTags" />
<file source="
Reference.xml"
destination="
$dreamweaver/Configuration/Content/Reference/our/" />
<file source="
default.htm"
destination="
$dreamweaver/Configuration/Content/Reference/our/" />
<file source="
ourtemplate.htm"
destination="
$dreamweaver/Configuration/Content/Reference/our/" />
</files>

Finally, we tell Dreamweaver what type of files our tag is used for, and what .vtm files to use.

<configuration-changes>
<taglibrary-changes>
<taglibrary-insert>
<taglibrary doctypes="
ColdFusion,CFC,DWTemplate_CF" id="ourTags"
name="
Our Tags" servermodel="Cold Fusion"
tagchooser="
ourTags/TagChooser.xml">
<tagref file="
ourTags/cf_ourtemplate.vtm" name="cf_ourtemplate" />
</taglibrary>
</taglibrary-insert>
</taglibrary-changes>
</configuration-changes>

</macromedia-extension>

Once our .mxi is created, we simply open the Macromedia Extension Manager, Choose File->Package Extension, Select our .mxi file and let the extension manager create the extension. Once this is complete, you can double-click your .mxp file to install your extension.

I hope that you found this series useful. There is a lot more that can be done with Dreamweaver Extensions and ColdFusion Custom Tags. Custom Tags have had a bit of a bum rap in recent years, but I believe that they still can be quite useful in the right situation.

Labels: , , ,

posted by Luis - 0 comments

Documenting ColdFusion custom tags in Dreamweaver (3/4)

Part 3: Documentation

In part 2, I talked about creating the tag editor for our custom tag. In this part we document our tag within Dreamweaver's reference and tie that reference into the tag editor. We'll start by creating a Reference.xml file, since this is the first tag we're documenting. For future tags, we'll simple edit our existing Reference.xml. We could use one of Dreamweaver's existing ones, but we'll create our own reference book in our own directory in order to prevent problems when upgrading Dreamweaver. This will also keep our tags together. Our Reference.xml looks like this.

<?xml version="0.81" encoding="iso-8859-1" standalone="yes" ?>
<book name="
Our Custom Tag Reference" language="our">
<topic_title name="
Tag"/>
<subtopic_title name="Description"/>
<default location="
default.htm"/>

<topic name="
cf_ourtemplate" location="ourtemplate.htm"
id="
Description">
<subtopic name="
Attributes" id="Attributes"/>
<subtopic name="
Example" id="Example"/>
</topic>

</book>

The main things that concern us here are the book name, book language, default location and our topics. We've set the book name to "Our Custom Tag Reference". The Language is set to "our" since this is our custom reference rather than say an HTML reference. The default location specifies an HTML file to be loaded by default when the book is opened. Our default.html simply has a description of what the reference exists for.

Our custom Tag Reference
Select the tag that you wish more information on. The second select box allows you to navigate the sections of the documentation.

The Topics and subtopics defin

e what sections will show up within each topic/subtopic dropdown in Dreamweaver's reference. You are not constrained to the same subtopics within each topic. In this case I've defined three subtopics for the topic of cf_ourtemplate

  • Description
  • Attributes
  • Example

Finally we get to the file on

this topic. ourtemplate.htm needs to contain a div with an id for each of the subtopics. The subtopics themselves and the content are up to you. I've included an example in the source. Once we have this installed in Dreamweaver we'll see a new entry in the References tab.

In the final part I'll explain how to package these files up and distribute them within Dreamweaver.

Labels: , , ,

posted by Luis - 0 comments

Documenting ColdFusion custom tags in Dreamweaver (2/4)

Part 2: Basic tag editor

In part 1, I explained that we'll need to create two files for basic tag editing. In this part we'll begin by creating a file called cf_ourtemplate.vtm. The contents will look like this.


<TAG NAME="cf_ourtemplate" endtag="yes">
<TAGFORMAT NLBEFORETAG="
1" NLAFTERTAG="1"/>
<TAGDIALOG FILE="
cf_ourtemplate.htm"/>

<ATTRIBUTES>
<ATTRIB NAME="
title" TYPE="TEXT"/>
<ATTRIB NAME="
theme" TYPE="ENUMERATED">
<ATTRIBOPTION VALUE="
basic"/>
<ATTRIBOPTION VALUE="
full"/>
</ATTRIB>
</ATTRIBUTES>
</TAG>

Our opening <TAG> defines the name of our tag, and whether or not the tag requires and end tag. <TAGFORMAT> can be left alone. <TAGDIALOG> defines where our tag editor .htm file resides. We next move down to the <ATTRIBUTES SECTION>. For our purposes there are two types of <ATTRIB> that we're concerned with. The first type is "TEXT" which will simply define an attribute with a space to fill in the value. The second type is "ENUMERATED", which will give you a dropdown list of choices. You define those choices using <ATTRIBOPTION>. At this point our .vtm file is complete.

Our tag editor is probably the most complex part of this process. Fortunately there are a lot of examples already built into Dreamweaver. Simple find a tag that has an editor that functions like what you are trying to do, and use that tag editor file as a template. Fortunately our tag editor for this example is fairly simple. The source code will be very helpful here. I'm not going to replicate the entire file since it's quite long. This is basically a standard HTML file with some custom javascript.

<script src="../../Shared/Common/Scripts/dwscripts.js"></script>
<script src="
../../Shared/Common/Scripts/ListControlClass.js"></script>
<script src="
../../Shared/Common/Scripts/tagDialogsCmn.js"></script>
<script>

var THEMELIST;
var theUIObjects;
var applyType =
"dynamic";

function inspectTag(tagNodeObj)
function applyTag(tagNodeObj)

function initializeUI()
{
var theThemeScaleCap = new
Array("basic","full");
var theThemeScaleVal = new
Array("basic","full");
THEMELIST = new ListControl(
"thethemescale");
theUIObjects = new
Array(THEMELIST);
tagDialog.populateDropDownList(THEMELIST, theThemeScaleCap,
theThemeScaleVal, 1);
}

</script>

We start by including some .js files and defining some variables. Next comes the inspectTag and applyTag functions which I've truncated since they are identical each time. Finally we have the initializeUI function where we define the values for our theme list and populate the drop-down box. next we'll include the required stylesheet.

<link href="../../fields.css" rel="stylesheet" type="text/css">

finally we'll add our text field and our dropdown.


<input name="thetitle" type="text" class="basicTextField"
id=
"attr:cf_ourtemplate:title" attname="title" required="true" />
<select name=
"thethemescale" class="oneWordOptionList"
id=
"attr:ccf_ourtemplate:themescale" attname="theme" editable="false">
</select>

That's basically it. For further reference on this topic, see Extending Dreamweaver -> Extension APIs -> Tag Libraries and Editors under Dreamweaver's help menu. In Part 3, l'll explain how to create custom documentation for our tag within Dreamweaver.

Labels: , , ,

posted by Luis - 0 comments

Documenting ColdFusion custom tags in Dreamweaver (1/4)

Part 1: Introduction

I've been meaning to post on this topic for a bit, and after reading Ray Camden's post on custom tags, I thought now would be a good time. I realize that a lot of developers use CFEclipse these days, but for those who use Dreamweaver or have others sharing a server that use Dreamweaver, documenting custom tags within Dreamweaver can be quite helpful. In our case, we have application developers and editors/designers that share templates and other UI elements. We've also used this technique to encapsulate complex capabilities into simple tags for our editors/designers.

During these articles we're going to look at a fictional tag called <cf_ourtemplate> that contains attributes of "title" and "theme". Our tag has two themes called "basic" and "full". How the tag functions and what those themes are is irrelevant to this exercise, so I'll leave that to your imagination. When we're done we should have something that looks like the following.

In order to bring this to life, we're going to need to create

  • a cf_ourtemplate.vtm, cf_ourtemplate.htm, and TagChooser.xmlile to define the inline hints and the tag editor
  • a Reference.xml, default.htm, and a ourtemplate.htm file for documentation
  • a .mxi file to make installing into Dreamweaver easier

It is not my intention for this series to be an exhaustive reference. To that end, in instances where a more detailed reference is available, or where the reference code is self-explanatory, I'll keep my explanations to a minimum. In the second part, I'll discuss creating the vtm and htm files for basic tag editing. Before moving on, you may wish to download the source code.

Labels: , , ,

posted by Luis - 0 comments
Template design by MLP Design
Licensed under CC-NC 3.0