Using custom UI controls in extensions | Developing Extensions for Macromedia Dreamweaver 8

< Day Day Up >

In addition to the standard HTML form elements, Dreamweaver supports custom controls to help you create flexible, professional-looking interfaces, as described in the following list:

Editable select lists (also known as combo boxes) that let you combine the functionality of a select list with that of a text box
Database controls that facilitate the display of data hierarchies and fields
Tree controls that organize information into expandable and collapsible nodes
Color button controls that let you add color picker interfaces to your extensions

Editable select lists

Extension UIs often contain pop-up lists that are defined using the select tag. In Dreamweaver, you can make pop-up lists in extensions editable by adding editable="true" to the select tag. To set a default value, set the editText attribute and the value that you want the select list to display.

The following example shows the settings for an editable select list:


 <select name="travelOptions" style="width:250px" editable="true"  editText="other (please  specify)"> <option value="plane">plane</option> <option value="car">car</option> <option value="bus">bus</option> </select>

When you use select lists in your extensions, check for the presence and value of the editable attribute. If no value is present, the select list returns the default value of false, which indicates that the select list is not editable.

As with standard, noneditable select lists, editable select lists have a selectedIndex property (see "Objects, properties, and methods of the Dreamweaver DOM" on page 129). This property returns-1 if the text box is selected.

To read the value of an active editable text box into an extension, read the value of the editText property. The editText property returns the string that the user entered into the editable text box, the value of the editText attribute, or an empty string if no text has been entered and no value has been specified for editText.

Dreamweaver adds the following custom attributes for the select tag to control editable pop-up lists:

Attribute name	Description	Accepted Values
`editable`	Declares that the pop-up list has an editable text area	A Boolean value of `true` or `false`
`editText`	Holds or sets text within the editable text area	A string of any value

NOTE

Editable select lists are available in Dreamweaver.

The following example creates a Command extension that contains an editable select list using common JavaScript functions:

To create the example:

Create a new blank file in a text editor.

Enter the following code:


 <html> <head>   <title>Editable Dropdown Test</title>   <script language="javascript">   function getAlert()   {     var i=document.myForm.mySelect.selectedIndex;     if (i>=0)     {       alert("Selected index: " + i + "\n" + "Selected text " + document.myForm.mySelect .options[i].text);     }     else     {       alert("Nothing is selected" + "\n" + "or you entered a value");     }   }   function commandButtons()   {     return new Array("OK", "getAlert()", "Cancel", "window.close()");   }   </script> </head> <body> <div name="test"> <form name="myForm"> <table>    <tr>     <td colspan="2">     <h4>Select your favorite</h4>     </td>   </tr>   <tr>     <td>Sport:</td>     <td>     <select name="mySelect" editable="true" style="width:150px"       editText="Editable Text">       <option> Baseball</option>       <option> Football </option>       <option> Soccer </option>     </select>     </td>   </tr> </table> </form> </div> </body> </html>

Save the file as EditableSelectTest.htm in the Dreamweaver Configuration/Commands folder.

To test the example:

1.	Restart Dreamweaver.
2.	Select Commands > EditableSelectTest. When you select a value from the list, an alert message displays the index of the value and the text. If you enter a value, an alert message indicates that nothing is selected.

Database controls

Using Dreamweaver, you can extend the HTML select tag to create a database tree control. You can also add a variable grid control. The database tree control displays database schema, and the variable grid control displays tabular information.

The following figure shows an advanced Recordset dialog box that uses a database tree control and a variable grid control:

Adding a database tree control

The database tree control has the following attributes:

Attribute name	Description
`name`	Name of the database tree control
`control.style`	Width and height, in pixels
`type`	Type of control
`connection`	Name of the database connection that is defined in the Connection Manager; if empty, the control is empty.
`noexpandbuttons`	When this attribute is specified, the tree control does not draw the expand Plus (+) or collapse Minus (-) indicators or the associated arrows on the Macintosh. This attribute is useful for drawing multicolumn list controls.
`showheaders`	When this attribute is specified, the tree control displays a header at the top that lists the name of each column.

Any option tags that are placed inside the select tag are ignored.

To add a database tree control to a dialog box, you can use the following sample code with appropriate substitutions for quoted variables:


 <select name="DBTree" style="width:400px;height:110px" type="mmdatabasetree"  connection="connectionName" noexpandbuttons showHeaders></select>

You can change the connection attribute to retrieve selected data and display it in the tree. You can use the DBTreeControl attribute as a JavaScript wrapper object for the new tag. For more examples, see the DBTreeControlClass.js file in the Configuration/Shared/Common/Scripts folder.

Adding a variable grid control

The variable grid control has the following attributes:

Attribute name	Description
`name`	Name of the variable grid control
`style`	Width of the control, in pixels
`type`	Type of control
`columns`	Each column must have a name, separated by a comma
`columnWidth`	Width of each column, each separated by a comma. The columns are of equal width if you do not specify widths.

The following example adds a simple variable grid control to a dialog box:


 <select name="ParamList" style="width:515px;" type="mmparameterlist columns"="Name,SQL  Data  Type,Direction,Default Value,Run-time Value" size=6></select>

The following example creates a variable grid control that is 500 pixels wide, with five columns of various widths:

 <select    name="ParamList"    style="width:800px;"   type="mmparameterlist"   columns="Name,SQL Data Type,Direction, Default Value,Run-time Value"   columnWidth="100,25,11,"    size=6>

This example creates two blank columns that are 182 pixels wide. (The specified columns total 136. The total width of the variable grid control is 500. The remaining space after the first three columns are placed is 364. Two columns remain; 364 divided by 2 is 182.)

This variable grid control also has a JavaScript wrapper object that should be used to access and manipulate the variable grid control's data. You can find the implementation in the GridControlClass.js file in the Configuration/Shared/MM/Scripts/Class folder.

Adding tree controls

Tree controls display data in a hierarchical format and let users expand and collapse nodes in the tree. The MM:trEECONTROL tag lets you create tree controls for any type of information; unlike the database tree control that is described in "Adding a database tree control" on page 117, no association with a database is required. The Dreamweaver Keyboard Shortcuts editor uses the tree control, as shown in the following figure:

Creating a tree control

The MM:trEECONTROL tag creates a tree control and can use one or more tags to add structure, as described in the following list:

MM:TREECOLUMN is an empty, optional tag that defines a column in the tree control.
MM:TREENODE is an optional tag that defines a node in the tree. It is a nonempty tag that can contain only other MM:TREENODE tags.

MM:TREECONTROL tags have the following attributes:

Attribute name	Description
`name`	Name of the tree control
`size`	Optional. Number of rows that show in the control; default is 5 rows
`theControl`	Optional. If the number of nodes in the `theControl` attribute exceeds the value of the size attribute, scrollbars appear
`multiple`	Optional. Allows multiple selections; default is single-selection
`style`	Optional. Style definition for height and width of tree control; if specified, takes precedence over the `size` attribute
`noheaders`	Optional. Specifies that the column headers should not appear

MM:trEECOLUMN tags have the following attributes:

Attribute name	Description
`name`	Name of the column
`value`	String to appear in column header
`width`	Width of the column in pixels (percentage not supported); default is 100
`align`	Optional. Specifies whether the text in the column should be aligned left, right, or center; default is left
`state`	Specifies whether the column is visible or hidden

For readability, trEECOLUMN tags should follow immediately after the MM:treeControl tag, as shown in the following example:

 <MM:TREECONTROL name="tree1"> <MM:TREECOLUMN name="Column1" width="100" state="visible"> <MM:TREECOLUMN name="Column2" width="80" state="visible"> ...  </MM:TREECONTROL>

The MM:TREENODE attributes are described in the following table:

Attribute name	Description
`name`	Name of the node
`value`	Contains the content for the given node. For more than one column, this is a pipe-delimited string. To specify an empty column, place a single space character before the pipe (\|).
`state`	Specifies that the node is expanded or collapsed with the strings `"expanded"` or `"collapsed"`.
`selected`	You can select multiple nodes by setting this attribute on more than one tree node, if the tree has a MULTIPLE attribute.
`icon`	Optional. The index of built-in icon to use, starting with 0: 0 = no icon; 1 = DW document icon; 2 = Multidocument icon

For example, the following tree control has all its nodes expanded:

 <mm:treecontrol name="test" style="height:300px;width:300px"> <mm:treenode value="rootnode1" state="expanded"> <mm:treenode value="node1" state="expanded"></mm:treenode> <mm:treenode value="node3" state="expanded"></mm:treenode> </mm:treenode> <mm:treenode value="rootnode2"  state="expanded"> <mm:treenode value="node2" state="expanded"></mm:treenode> <mm:treenode value="node4" state="expanded"></mm:treenode> </mm:treenode> </mm:treecontrol>

Manipulating content within a tree control

Tree controls and the nodes within them are implemented as HTML tags. They are parsed by Dreamweaver and stored in the document tree. These tags can be manipulated in the same way as any other document node. For more information on DOM functions and methods, see Chapter 5, "The Dreamweaver Document Object Model," on page 127.

Adding nodes

To add a node to an existing tree control programmatically, set the innerHTML property of the MM:trEECONTROL tag or one of the existing MM:trEENODE tags. Setting the inner HTML property of a tree node creates a nested node.

The following example adds a node to the top level of a tree:

 var tree = document.myTreeControl; //add a top-level node to the bottom of the tree tree.innerHTML = tree.innerHTML + '<mm:treenode name="node3" value="node3">';

Adding a child node

To add a child node to the currently selected node set the innerHTML property of the selected node.

The following example adds a child node to the currently selected node:


 var tree = document.myTreeControl; var selNode = tree.selectedNodes[0]; //deselect the node, so we can select the new one selnode.removeAttribute("selected"); //add the new node to the top of the selected node's children selNode.innerHTML = '<mm:treenode name="item10" value="New item11" expanded selected>' +  selNode.innerHTML;

Deleting nodes

To delete the currently selected node from the document structure, use the innerHTML or outerHTML properties.

The following example deletes the entire selected node and any children:

 var tree = document.myTreeControl; var selNode = tree.selectedNodes[0]; selNode.outerHTML = "";

A color button control for extensions

In addition to the standard input types such as text, checkbox, and button, Dreamweaver supports mmcolorbutton, an additional input type in extensions.

Specifying <input type="mmcolorbutton"> in your code causes a color picker to appear in the UI. You can set the default color for the color picker by setting a value attribute on the input tag. If you do not set a value, the color picker appears grey by default and the value property of the input object returns an empty string.

The following example shows a valid mmcolorbutton tag:

 <input type="mmcolorbutton" name="colorbutton" value="#FF0000">  <input type="mmcolorbutton" name="colorbutton" value="teal">

A color button has one event, onChange, which is triggered when the color changes.

You might want to keep a text box and a color picker synchronized. The following example creates a text box that synchronizes the color of the text box with the color of the color picker:


 <input type = "mmcolorbutton" name="fgcolorPicker" onChange="document.fgcolorText .value=this.value"> <input type = "test" name="fgcolorText" onBlur="document.fgColorPicker.value=this.value">

In this example, when the user changes the value of the text box and then tabs or clicks elsewhere, the color picker updates to show the color that is specified in the text box. Whenever the user selects a new color with the color picker, the text box updates to show the hex value for that color.

< Day Day Up >