Dreamweaver Widget Packager:Developer's Guide to the WDF

From Adobe Labs

The ultimate reference for the Widget Description File (WDF) format is the Open Ajax Alliance (OAA) Widget Metadata Specification, of which this is an implementation. The following document describes the tags and attributes from the Widget Metatdata that the Adobe Widget Packager uses to create a Widget Extension for Dreamweaver.

A word about file naming

In order to be considered OAA-compliant, widget description filenames must match the pattern *oam.xml. Thus SpryTootip_oam.xml, YUIComboBox-oam.xml, and jQuery_Menubar_oam.xml would all be valid WDF filenames.

The dw namespace

The OAA specification allows for custom, namespaced tags and attributes to be added to the Widget Metadata where needed by specific tools. We have added several of these tags and attributes, mostly to aid in the generation and installation of Dreamweaver extension files. Because they are not part of the standard Widget metadata, all such tags and attributes are optional. If you include them in your WDF, you must add a namespace declaration to the xml tag at the top of the file, as follows: xmlns:dw="http://ns.adobe.com/dreamweaver".

A sample widget descriptor file

<?xml version="1.0" encoding="utf-8" xmlns:dw="http://ns.adobe.com/dreamweaver" ?>

<widget id="http://mywebsite.com/widget/" name="myUI Calendar" version="1.5" aboutUri="http://developer.my.com/myUI/calendar/">

<authors>
	<author name="A.J. Developer" />
	<author name="Mr. Anderson" />
</authors>

<description type="text/plain">
	<![CDATA[
	Creates a calendar using the myUI Calendar component.
	<br />
	The Calendar component is a UI control that lets users choose one or more dates from a graphical
	calendar presented in a single-page or multi-page interface. Calendars are generated entirely via 
	JavaScript and can be navigated without any page refreshes.
	]]>
</description>

<categories>
	<category name="myUI"/>
</categories>

<icons>
	<icon src="images/calendar_widget_small.png" width="18" height="18" />
	<icon src="images/calendar_widget_large.png" width="36" height="36" />
	<icon src="images/calendar_widget_xlarge.png" width="50" height="50" />
</icons>

<requires>
	<require type="javascript" src="myUI/1.5/common/myUI-dom-event.js" includeRef="true" dw:shared="true" />
	<require type="css" src="myUI/1.5/calendar/assets/calendar.css" includeRef="false" />
	<require type="image" src="myUI/1.5/assets/calendar_placeholder.png" />
</requires>

<javascript>
	<![CDATA[
	
  		
  		@@functionName@@ = function() {
   		   calendarInstance = new myUI.widget.Calendar("cal1","@@unique_ID@@");
   		  calendarInstance.render();
  		}
  		myUI.util.Event.onDOMReady(@@functionName@@);
	
	]]>
</javascript>


<content view="default">
<![CDATA[
<div class="myUI-skin-blue">
<div id="@@id@@"><!--UniqueInsID=myUI.Calendar.Calendar--></div>
</div>
]]>
</content>

<properties>
  <property name="unique_ID" format="id" default="calendarID" datatype="string" />
  <property name="functionName" default="createCalendar" datatype="String" format="id"/>
</properties>

<dw:extension>
	<dw:translator>
	<dw:widgetRegExp><![CDATA[UniqueInsID\s*=\s*myUI\.Calendar\.Calendar\s*(\w*|.*)\s*=\s*new\s*
(myUI\.widget\.Calendar)\s*\(\s*["']\w+["']\s*,\s*["']([^"']+)["']\);]]></widgetRegExp>
	<dw:help src="http://mywebsite.com/widget/help">My Widget Help Page</dw:help>
	</dw:translator>
</dw:extension>

</widget>

The root element of a widget description file. Each widget description file describes a single widget.

Attributes

id

(Required) Unique ID
A uri to serve as a unique identifier for your widget. You may want to post this xml file at the location specified in id, but that is not required. You only need to ensure that this is a unique uri.

name

(Required) The widget name

This value will be used as the menu item name in the Insert menu, and as a tooltip when the user mouses over the widget icon in the Insert panel. It will also be used in the Property inspector and in the tabbed outline that appears around the widget HTML in Design view, if a Property inspector and translator are generated.

version

(Required) The widget version
The version can be specified in the form of #[.#]*, such as "1", "1.1" or "1.20.2", followed by an optional arbitrary string (e.g., "1.20.2Beta" or "1.1 Build 543").

aboutUri

(Optional) The URI of a web page that contains descriptive information about this widget.

Example

<widget id="http://mywebsite.com/widget/calendar_oam.xml"
    name="myUI Calendar"
    version="1.5"
    aboutUri="http://developer.my.com/myUI/calendar/">
  ...
</widget>

<description>

Provides a textual description for its parent element (in this case, the <widget> tag). This information will appear in the Description field in the Extension Manager when a Dreamweaver user installs the Widget Extension. The contents of this tag should be wrapped in CDATA markers to preserve special characters such as < and >. This field may have HTML in it for formatting purposes. Required.

Parent

<widget>

Attributes

type

Either "text/plain" (the default) or "text/html".

Example

<widget>
	<description type="text/plain">
  		<![CDATA[Creates a Button using Yahoo's User Interface Button Widget.]]>
	</description>
...
</widget>

<authors>

Holds zero or more <author> elements.

Parent

<widget>

<author>

One author of the widget. Defaults to Anonymous if no author is provided or the tag does not exist in the file.

Parent

<authors>

Attributes

name

The name of the widget author. This information will appear in the Author field in the Extension Manager. Required.

Example

<widget>
...
<authors>
  <author name="A.J. Developer">
</author>
...
</widget>

<categories>

Holds one or more <category> elements. The Widget packager will currently only use the first category.

Parent

<widget>

<category>

A single category. Defaults to Web Widgets if none are provided.

Parent

<categories>

Attributes

name

The category name. This value will be used as the submenu name in the Insert menu, and as the category in which the widget will appear in the Insert panel.
Required

Example

<widget>
...
<categories>
  <category name="JaxTown Widgets">
</category>
...
</widget>

<icons>

Holds zero or more <icon> elements.

Parent

<widget>

<icon>

A single widget icon. Different icons can be specified for different purposes; the purpose will be devined from the height and width attributes. That is, the icon size that is best suited for the Extension Manager, the Insert panel, or the Property inspector will be selected from among the available choices.

If the sizes available do not match those needed for Dreamweaver, the icons will scale. An 18x18 icon should be provided for the Insert Panel and 36x36 icon should be provided for the property inspector and for the icon in the Extension Manager. A .png file is required for the Extension Manager.

Parent

<icons>

Attributes

src

The path to the icon file, either relative to the WDF or absolute using a http:// uri.

height

The height of the icon in pixels.

width

The width of the icon in pixels.

Example

<widget>
...
<icons>
  <icon src="images/calendar_widget_small.png" width="18" height="18" />
  <icon src="images/calendar_widget_large.png" width="36" height="36" />
  <icon src="images/calendar_widget_xlarge.png" width="50" height="50" />
</icons>
...
</widget>

<requires>

Holds zero or more <require> elements.

Parent

<widget>

<require>

A single file or other asset on which this widget depends.

Parent

<requires>

Attributes

type

(Required) The type of the asset. Possible require types: "css", "javascript", "image", "media", "folder", "library" or "other" .
If you specify type="css" a <link> tag referencing the css file will be added to the head of the html page the widget is inserted in.

If you specify type="jascascript" a &ltscript> tag referencing the javascript file will be added to the head of the html page the widget is inserted in.

If you specify "image", "media", or "other" the file will be copied relative to the html page the widget is inserted into. But, no references will be added to it in the html page.

Use type="folder" to specify that all contents of a folder should be copied document relative.
NOTE: that if you use the folder type your Widget will NOT be able to be installed from the web by specifying a url to the oam xml file via http.

Use type="library" to copy all the files in the specified folder site relative. No references to the files will be added to the document unless explicitly specified with another <require> tag with corresponding name attribute.

src

(Required) The path to the asset file, either relative to the WDF or you can specify an absolute uri using http://.

target

(Optional) The relative URL within the deployed package where the asset file should be placed. This attribute is not applicable if you specify a uri reference in the src attribute. If not specified targets defaults to the same as src.

includeRef

(Optional) A boolean value indicating whether to include a reference to the asset in the head of the document. Defaults to true for css and javascript files, false for images.

dw:shared

(Optional) A boolean value indicating whether this file is shared among multiple widgets. This namespaced attribute is unique to the Adobe implementation of the OAA spec.
It prevents the Extension Manager from prompting the user if it encounters a file of the same name at the target location.

Example

<widget>
...
<requires>
  <require type="javascript" src="myUI/1.5/common/myUI-dom-event.js" includeRef="true" dw:shared="true" />
  <require type="css" src="myUI/1.5/calendar/assets/calendar.css" includeRef="true" />
  <require type="image" src="myUI/1.5/assets/calendar_placeholder.png" includeRef="false" />
</requires>
...
</widget>

<properties>

Holds zero or more <property> elements.

Parent

<widget>

<property>

Used to generate a unique ID for each instance of the Widget and link it to the Javascript code. This is required to enable multiple widgets to run in a page and to allow for deletion of corresponding javascript references when a Widget is deleted in the Design View within Dreamweaver.

Parent

<properties>

Attributes

name

(Required) The name of the property. Each property requires a unique name. For example if you specify name="unique_ID" when the widget is inserted Dreamweaver searches for the pattern @@unique_ID@@ in both the <script> and <javascript> sections and substitutes a unique ID using the value specifyed in the default attribute, appending a number to it that does not match any existing id's in the current page. The same unique ID will be used across the code in the <javascript> section and the html specified in the <content> tag. This ensures that each Widget has a unique ID and wires up the Javascript to the html.

format

(Required) Specifies the format of the property. Currently only format="id" is supported. The property default value is incremented with each new instance of the widget only if the format="id" and datatype="string."

default

Specifies the default string to be used in the replacement. A number will be appended to it to ensure it is unique in the current page.

datatype

Specifies the datatype of the property. The default and only supported value is "string."

Example

<properties>
  <property name="unique_ID" format="id" default="calendarID" datatype="string" />
  <property name="functionName" default="createCalendar" datatype="String" format="id"/>
</properties>

The above example would cause all instances of @@unique_ID@@ to have a unique name start with the string "calendarID", for example "calendarID1". And would ensure that each instance of @@functionName@@ has a unique function signature.

<javascript>

Specifies a block of JavaScript logic that must be included in the page for the widget to run. Any JavaScript logic that contains (or might contain) characters that are significant to XML parsers, such as <, >, or symbols, should be placed within a CDATA section.

Parent

<widget>

Attributes

location

Example

<widget>
...
<javascript>
	<![CDATA[
	
  		@@functionName@@ = function() {
   		  calendarInstance = new myUI.widget.Calendar("cal1","@@unique_ID@@");
   		  calendarInstance.render();
  		}
  		myUI.util.Event.onDOMReady(@@functionName@@);
	
	]]>
</javascript>
...
</widget>

<content>

Specifies the markup (usually HTML) that provides the widget's presentation.

The Ajax content and logic that initializes the widget and provides its visual rendering can be specified using a combination of declarative markup and/or procedural JavaScript logic. Declarative markup is placed within the <content> element, which specifies either the markup snippet (usually HTML) that needs to be spliced into the web page. JavaScript can be located either as <script> elements within the <content> or contained within one or more separate <javascript> elements.

Any content that contains (or might contain) characters that are significant to XML parsers, such as <, >, or symbols, should be placed within a CDATA section.

Parent

<widget>

Attributes

view: Allows for multiple alternate <content> elements for a particular widget. Currently the Packager only supports the 'default' option, which is also the default value.
src: An external file containing the markup to be inserted into the user's document. This attribute is optional; if not supplied, the contents of the tag will be used.

Example

<widget>
...
<content view="default">
<![CDATA[
	<div id"@@unique_ID@@" /div>
]]>
</content>
...
</widget>

<dw:extension>

A custom container tag for information to Dreamweaver needed to display the tabbed outline in design view and the property inspector when the widget is selected in Design View. This tag and all of its children are optional; however, you are strongly encouraged to provide regular expressions to match your widget's constructor so that your users can make use of the Property Inspector with your widget.

Parent

<widget>

<dw:ui-access>

This tag is only required if you are creating an advanced extension that installs the Widget into a non standard location (not in the Insert Menu and Insert Panel). You can use this tag to specify how the Dreamweaver user should access the Web Widget from the Dreamweaver user interface. This text will appear appended at the end of the Description in the Extension Manager interface when the Web Widget extension is selected.

Parent

<dw:extension>

<dw:translator>

Specifies all the translator and property inspector information needed by Dreamweaver. For more information about translators and how to use them, please visit the <a href="http://livedocs.adobe.com/en_US/Dreamweaver/9.0_API/index.html">Dreamweaver API Docs</a>.

Parent

<dw:extension>

<dw:widgetRegExp>

Regular expression used to find a unique ID in the <javascript> tag of the WDF. The first match in the regular expression should be the unique ID. Helps in triggering the unique translator for the widget. Enclose the regular expression under CDATA. If you are unfamiliar with Regular Expressions you may want to reference the <a href="http://developer.mozilla.org/En/Core_JavaScript_1.5_Guide:Regular_Expressions">Javascript 1.5 Guide to Regular Expressions</a>.

Parent

<dw:translator>

For Example:

If I wanted to create a regular expression to match the following javascript constructor :

swfobject.embedSWF(viewerUrl, "@@id@@", "420", "445");

I would use the following regular expression in <dw:widgetRegExp>

<dw:widgetRegExp><![CDATA[swfobject.embedSWF\(viewerUrl,\s*"(\w+)"]]></dw:widgetRegExp>

Note that we are using \ to escape the open parenthesis. \s* means that it will look for zero or more space characters preceding the second parameter which will be sorrounded by double quotes "". The (\w+) is the important part it matches against the unique ID that gets put in by the @@id@@ template specified in the <javascript> tag.

<dw:widgetConstructor>

The constructor used in the <javascript> tag to construct an instance of the widget. There should be exactly 1 <dw:widgetConstructor> tag in the WDF. If it is not included, the default is set to the widget name (with "." instead of " ").

Parent

<dw:translator>

Example:

In the above example to match against the javascript constructor swfobject.embedSWF you would specify the following:

<dw:widgetConstructor>swfobject.embedSWF</dw:widgetConstructor>

<dw:help>

Specifies the help URL where users can learn more about the widget. It is shown in the property inspector. There should be exactly 1 <help> tag in the WDF. If there is no content included, the packager will use the default widget name followed by "Help."

Parent

<dw:translator>

Attributes

src: Specifies the source URL of the help page.

</javascript>

Retrieved from "http://labs.adobe.com/wiki/index.php/Dreamweaver_Widget_Packager:Developer%27s_Guide_to_the_WDF"

Search

Personal tools

Views

Dreamweaver Widget Packager:Developer's Guide to the WDF

From Adobe Labs

A word about file naming

The dw namespace

A sample widget descriptor file

<widget>

Attributes

Example

<description>

Parent

Attributes

Example

<authors>

Parent

<author>

Parent

Attributes

Example

<categories>

Parent

<category>

Parent

Attributes

Example

<icons>

Parent

<icon>

Parent

Attributes

Example

<requires>

Parent

<require>

Parent

Attributes

Example

<properties>

Parent

<property>

Parent

Attributes

Example

<javascript>

Parent

Attributes

Example

<content>

Parent

Attributes

Example

<dw:extension>

Parent

<dw:ui-access>

Parent

<dw:translator>

Parent

<dw:widgetRegExp>

Parent

<dw:widgetConstructor>

Parent

<dw:help>

Parent

Attributes