Packaging widgets with the Adobe Widget Browser

This tutorial shows how to package an existing HTML and JavaScript widget using the Adobe Widget Browser so that it can be shared with other users of the Widget Browser.

The Widget Browser is an Adobe AIR application that lets you preview and configure widgets using a visual interface. 'The term widget has many definitions, but in this context, a widget is a combination of small pieces of HTML, CSS, and JavaScript code that work together to make a complex web page component. Accordions, tabbed panels, and image lightboxes are examples of widgets.

As a first step, you need to either build or find a working widget that you want to package. Many JavaScript widgets have flexible licenses that allow for this type of use. Just be sure to check the license that comes with the widget.

Once you have your widget, you start by creating an OpenAjax Metadata OAM file, which is an XML file that contains all of the information about the widget. The format of this file follows a standard for describing JavaScript widgets that was developed with the OpenAjax Alliance. This file contains links to:

• the JavaScript JS and CSS files that make up the widget
• the JavaScript, HTML, and CSS code that needs to be inserted in the HTML page for the widget
• any properties that the user can customize

For this example, I will start with the jQuery UI button. The ZIP file that accompanies this article contains a jQueryUIButton.html file with an example of a working jQuery UI button widget. To package this widget, you will need to create an OpenAjax Metafile that points to all the files required for the jQuery UI button. This file will also include the code and properties needed to enable users to create their own presets for the widget in the Widget Browser and insert the widget in their Dreamweaver sites.

In the body of jQueryUIButton.html you will see a <div> tag, which is the HTML markup that becomes the button, and a JavaScript constructor, which specifies the id of the div to be turned into a jQuery UI button.

Note: In jQuery, $ is shorthand notation for jQuery. You can replace $ with jQuery if you need to avoid conflicts with other JavaScript frameworks.

The following code will find the <div> tag with the id set to myButton and call the button function, which will turn it into a jQuery UI button.

Follow these steps to begin creating the OpenAjax Metafile for the example widget:

1. Create a new OpenAjax Metafile named jQueryButton_oam.xml. This is an XML file with a <widget> parent tag.
2. Add the following code:

3. Set the id attribute to a unique ID for the widget.

It's a good practice to use a sample page location on the web. The name attribute specifies the name of the widget and the version attribute specifies the version of the widget.

4. Add a description of the widget in the <description> tag as follows you can use html tags to format the description :

5. Add <javascript> and <content> tags to specify the JavaScript constructor and HTML markup that will be inserted in the body; for example:

The location="beforeContent" attribute of the javascript tag indicates that the JavaScript block should appear before the HTML markup.

Now you're ready to add references to JavaScript and CSS files. If you look at the head of the sample widget HTML file, you'll see that the JavaScript file has links for jQuery, the JavaScript file for jQuery UI, and the base jQuery UI cascading style sheet file.

6. Add a <requires> tag and the following three <require> tags to the OAM file to ensure these links are added to the head.

See the jQueryPushButton1_oam.xml sample file for the example XML created using the steps until this point.

Note: You can also provide local copies of the JS and CSS files and have them copied to your site when you insert the widget if you do not want to refer to them via the Google API link on the web. See the jQueryPushButtonLocal_oam.xml sample file for an example of referencing the files locally.

After installing and starting the Adobe Widget Browser, the first thing you need to do is enable widget projects.

1. Click Options and select Enable Widget Projects.

This will add the Widget Projects button next to the Adobe Exchange and My Widgets buttons see Figure 1 .

Now that you have enabled widget projects you're ready to create a widget project.

2. Click Widget Projects.
3. Click the Create Widget button at the bottom right of the Widget Projects screen.
4. Select the jQueryButton_oam.xml file that you just created or the jQueryPushButton1_oam.xml version from the sample files see Figure 2 .

If all goes well you will see the message "Validation succeeded with warnings" in the Status pane. Don't worry about the warnings for now, they will be addressed later in the tutorial.

If the validation did not succeed, make sure that your XML file is well formed. A useful technique is to open the file in Dreamweaver and choose File > Validate As XML to make sure the XML validates.

5. Once the OAM file validates successfully click the Preview tab to see a preview of the widget.

Packaging a widget into a ZIP file is straightforward:

1. Click the Package button at the bottom of the screen.
2. Confirm that the operation was successful by looking for the "Zip packaging succeeded" message in the Results pane. The path to the ZIP file is also shown in the Results pane.

Importing the widget

Once you have packaged the widget you can import it and then insert it into a page with Dreamweaver.

1. On the Adobe Widget Browser main screen, click My Widgets.
2. Click the Import Widget button at the bottom right.
3. Select the widget you packaged up in the previous step. By default it is named jQueryUIPushButton.zip.
4. Click OK.
5. After the widget is imported, click the jQuery UI Push Button widget.

Inserting the widget with Dreamweaver

Now that the Widget has been added to My Widgets it will show up in Dreamweaver when you click Widget in the Insert panel or the Insert menu.

1. Start Dreamweaver.
2. Create a new blank HTML page.
3. Choose Insert > Widget or click Widget in the Insert panel.
4. In the Widget dialog box, select jQuery UI Simple Button as the Widget.
5. Click OK.

The widget code should be added to your page and links to the css and javascript files added to the head.

6. Save the page.

Dreamweaver will copy any local files to your site, display a dialog box listing any files that need to be copied to your site, and fix up the links so that the URLs are mapped correctly.

You have successfully created a widget package and tested that you can insert the widget in your page with Dreamweaver. The next step is to enable users to customize the look and behavior of the widget and create their own presets. You first need to identify the properties that you want to be customizable. These might include JavaScript parameters that are passed to the widget constructor to change the behavior of the widget. You may also want to enable users to override the default CSS styles to change the look of the widget.

You specify properties in the OAM file to display UI controls in the Adobe Widget Browser that the user can use to modify the CSS or JavaScript code in the page.

1. To add a control to specify the widget border and another control to set the button's background color, add the following <property> tags to the <properties> section of the OAM file:

This will create controls that are visible in the Adobe Widget Browser when you click Configure in the bottom left of the presets list from the Preview pane see Figure 3 .

The <title> text is used as the control label. The datatype and format attributes specify the type of control. The defaultValue attribute specifies the default value for the default preset.

The text in the <description> tag is displayed as a tooltip when you move the pointer over the control.

Now you need to add the CSS code in the <dw:css> tag that will change the look of the widget when the control values are updated. The name attributes from the property tags will be used to do a variable substitution with the value that the user selects from the control.

2. Add the following code to the OAM file:

3. Save your changes.

See the jQueryPushButton2_oam.xml sample file for the example XML created using the steps until this point.

The @@propertyName@@ notation indicates that the value from the corresponding control will be substituted here. The ui-button class is added dynamically by the jQuery button code at run time. In this example, you are overriding default styles in the external style sheet because the rules in the head of the document are taking precedence over the rules in the external default style sheet.

Note: You need to set background-image: none; to override the background image that is specified in the external CSS file and display the background color instead.

Note: It is often helpful to try out the widget in Dreamweaver using the Live Code option to see which styles are being applied by the JavaScript code. If you are having problems applying CSS rules to get your desired styling, the CSS Styles panel can help by showing which rules are being applied and how the CSS cascade is working.

Using unique IDs

To allow for more than one widget to be inserted in a page you should associate a unique ID with each widget. You add a <property> element to the <properties> section with format="id" to specify a unique ID, specify the property name in this example, __WID__ in the JavaScript constructor or the HTML markup, and make sure that any CSS styles specify the id so that you can apply different CSS style rules for multiple widgets in the same page.

1. Edit the OAM file to reflect the following changes:

2. Save your changes.

See the jQueryPushButton3_oam.xml sample file for the example XML created using the steps until this point.

3. Create a new widget package using the updated OAM file and import it into the Widget Browser.

In the code above, the defaultValue="jQueryUIButton" attribute specifies that the first time the widget is inserted in a page the __WID__ will be replaced with a unique ID starting with "jQueryUIButton". If that ID already is in use in the current page, then a number will be appended to ensure the ID is unique within the document; for example, jQueryUIButton1. The hidden="true" attribute hides the attribute so that it is not visible when the user clicks the Configure button in the Widget Browser. Since the Widget Browser and Dreamweaver take care of ensuring that the widget is unique there is no need to display it in the Widget Browser property configurator.

Note: If you want to specify other unique IDs you can do so using format="id" and another unique property name in place of __WID__. Then just use the @@propertyName@@ notation in the other sections of the OAM file to substitute in the matching unique ID.

Adding presets

Once you have all the properties you want to specify for your widget, it is easy to create Developer presets.

1. In the Widget Browser select the widget in Widget Projects.
2. Click Configure in the Preview pane.
3. Change the properties to get the look you want for your customized preset. For example, change the background color to aqua and set the border width to three pixels.
4. Change the preset name; for example, type Aqua Button.
5. Provide a description, for example, type Aqua background with thick border see Figure 4 .
6. Click Save Preset.

The new preset will show up in the list of presets see Figure 5 .

4. Click the Package button to create a new widget package ZIP file .

When you import this widget package you will see the preset you created listed under Developer Presets. This preset will now be available to everyone using this widget.

Add author and license information

You may have noticed that the widget is showing up as by "Anonymous". You will want to add author and license details to the widget.

1. Add the following tags in the OAM file:

2. Save your changes.

Adding icons

You can add an icon for a preview of the widget that is displayed in the Widget Browser and an icon that is used in the Property inspector when the widget is selected in Dreamweaver see Figure 6 .

1. Create a 300 x 200 pixel icon for the preview and a 36 x 36 pixel icon for the Property inspector.

2. Add them to the OAM file as follows:

3. Save your changes.

See the jQueryPushButton4_oam.xml sample file for the complete example.

When you've finished creating and packaging your widget, upload it to the Adobe Exchange to share it with other users of the Widget Browser.

1. From the main Adobe Exchange page click Upload To The Exchange.
2. Sign in if you haven't already done so.
3. Follow the on-screen instructions to upload the packaged ZIP file and fill out the relevant information.

The Upload Type should be set to Dreamweaver Content And Extensions. For the Categories setting, select Dreamweaver: Widget Browser/Open Ajax Widgets. For the Framework setting, select the appropriate Framework. For this example, select jQuery, but for other projects you might select another framework or Other if it does not rely on any of the listed JavaScript frameworks.

Thank you for submitting your widget!

For more detailed information about creating widgets as well as samples refer to the following resources:

• Widget Developer Documentation
• OpenAjax Metadata specification
• jQuery Plugin Tutorial, In-Depth for Absolute Beginners
• jQuery Plugins examples
• jQuery Cookbook