A simple insert object example

This example adds an object to the Insert bar so users can add a line through (strike through) selected text by clicking a button. This object is useful if a user needs to make editorial comments in a document.

Because this example performs text manipulation, you may want to explore some of the objects from the Text pop-up menu in the HTML category on the Insert bar as models. For example, look at the Bold, Emphasis, and Heading object files to see similar functionality, where Dreamweaver wraps a tag around selected text.

You will perform the following steps to create the strike-through insert object:

The title of the object is specified between the opening and closing title tags. You also specify that the scripting language is JavaScript.

Add the JavaScript functions

In this example, the JavaScript functions define the behavior and insert code for the Strikethrough object. You must place all the API functions in the head section of the file. The existing object files, such as Configuration/Objects/Text/Em.htm, follow a similar pattern of functions and comments.

The first function the object definition file uses is isDOMRequired(), which tells whether the Design view needs to be synchronized to the existing Code view before execution continues. However, because the Superscript object might be used with many other objects in the Code view, it does not require a forced synchronization.

Add the isDOMRequired() function

Next, decide whether to use objectTag() or insertObject() for the next function. The Strikethrough object simply wraps the s tag around the selected text, so it doesn’t meet the criteria for using the insertObject() function (see insertObject()).

Within the objectTag() function, use dw.getFocus() to determine whether the Code view is the current view. If the Code view has input focus, the function should wrap the appropriate (uppercase or lowercase) tag around the selected text. If the Design view has input focus, the function can use dom.applyCharacterMarkup() to assign the formatting to the selected text. Remember that this function works only for supported tags (see dom.applyCharacterMarkup() in the Dreamweaver API Reference). For other tags or operations, you may need to use other API functions. After Dreamweaver applies the formatting, it should return the insertion point (cursor) to the document without any messages or prompting. The following procedure shows how the objectTag() function now reads.

Add the objectTag() function

Instead of including the JavaScript functions in the head section of the HTML file, you can create a separate JavaScript file. This separate organization is useful for objects that contain several functions, or functions that might be shared by other objects.

Separate the HTML object definition file from the supporting JavaScript functions

Create the image for the Insert bar

Edit the insertbar.xml file

Next, you need to edit the insertbar.xml file so Dreamweaver can associate these two items with the Insert bar interface.

 Before you edit the insertbar.xml file, you might want to copy the original one as insertbar.xml.bak, so you have a backup.

The code within the insertbar.xml file identifies all the existing objects on the Insert bar.

• Each category tag in the XML file creates a category in the interface.

• Each menubutton tag creates a pop-up menu on the Insert bar.

• Each button tag in the XML file places an icon on the Insert bar and connects it to the proper HTML file or function.

Add the new object to the Insert bar

The new object appears at the beginning of the Common category on the Insert bar.

Add a dialog box

You can add a form to your object to let the user enter parameters before Dreamweaver inserts the specified code (for example, the Hyperlink object requests the text, link, target, category index, title, and access key values from the user). In this example, you add a form to the Strikethrough object from the previous example. The form opens a dialog box that provides the user with the option to change the text color to red as well as to add the strike-through tag.

This example assumes you have already created a separate JavaScript file called Strikethrough.js.

First, in Strikethrough.js, you add the function that the form calls if the user changes the text color. This function is similar to the objectTag() function for the Strikethrough object, but is an optional function.

Create the function

Next, in the Strikethrough.htm file, you add the form. The form for this example is a simple check box that calls the fontColorRed() function when the user clicks on it. You use the form tag to define your form, and the table tag for layout control (otherwise, the dialog box might wrap words or size awkwardly).

Add the form

Test the dialog box

Build an Insert bar pop-up menu

The Dreamweaver Insert bar introduces a new organization for objects. The Insert bar now supports pop-up menus to help organize objects into smaller groups, as shown in the following figure.

The following example builds a new category on the Insert bar called Editorial and then adds a pop-up menu to that category. The pop-up menu contains the Strikethrough object you already created and groups it with a Blue Text object you create. The objects in the Editorial category let users:

• Make editorial comments in a file

• Strike through the content they want to remove or make new content blue

Organize the files

Create the Blue Text object

Now you can create an image for the Blue Text Object.

Create the image

Next, you edit the insertbar.xml file. This file defines the objects on the Insert bar and their locations. Notice the various menubutton tags and their attributes within the category tags; these menubutton tags define each pop-up menu in the HTML category. Within the menubutton tags, each button tag defines an item in the pop-up menu.

Edit the insertbar.xml

Test the new pop-up menu