Tuesday, September 04, 2007
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: Adobe, ColdFusion, Custom Tags, Dreamweaver
posted by Luis
