| ListControl interface elements are found throughout the Dreamweaver interface. Any time the interface presents multiple selection lists that interact with each other, those are ListControls. Any time a panel or dialog box displays a selection list that includes + and buttons (and maybe up and down arrows), that's another ListControl. Figure 10.1 shows just a few of the many examples of ListControl elements Dreamweaver provides for its users. Figure 10.1. Several ListControl elements at work in the Dreamweaver interface. How are ListControls created? Unlike tree structures or color buttons, ListControls are not custom form elements. There's nothing official in the API about them. They're nothing more than <select> input elements (form lists or menus ) with some extra coding to govern their functionality. That extra coding is not built into the API. Rather, it's tucked away in the ListControlClass.js file, in the Shared/Common/Scripts folder. To take advantage of that extra coding, all you have to do is link your extension file to ListControlClass.js. Specifications Using a ListControl involves making changes to both the interface layout and the scripting of an extension file. The ListControl Element in the Interface To add a ListControl element to your interface, your <form> code should include the following: -
A named <select> form element, representing the list. The <select> element can occur in or out of layers . -
(Optional) A table cell or layer above the one containing the list that contains the buttons at the list's head. In this cell or layer, place the following shared images (found in the Shared/MM/Images/ folder), all coded as image button form elements, in order: -
btnAdd.gif -
btnDelete.gif -
btnUp.gif -
btnDown.gif note To create multiple button states (grayed out, normal, and so on), you'll need to access the ImageButton class, discussed in the following section. If your ListControl includes images, this portion of the layout table will look like the one shown in Figure 10.2. (The form shown is from Commands/Insert Nav Bar.htm. Note that the <select> element itself has been assigned a pixel width using the style property.) Figure 10.2. A form including a ListControl element, shown in Dreamweaver Code and Design view. Scripting a ListControl Element Before you can add a ListControl element to an extension file, you must link to ListControlClass.js. Add the following script tag to the <head> section: <script src="../Shared/Common/Scripts/ListControlClass.js"></script> Depending on where in the Configuration folder your extension file is stored, the relative path in this <script> tag will vary. Next, the ListControl element should be added to the <script> section of the extension file like this: -
At the top of the head's <script> section, declare a global variable to be used as the name of the ListControlbut don't give it a value: var MyList; -
In the initializeUI() function, use a constructor statement (a line of code that generates a new instance of a class, like the ListControl class) to create a new ListControl from the global variable, referring to the name of your <select> form element: MyList = new ListControl( selectName ); The name of the new ListControl must be the same as the global variable created in the previous step. The constructor has one argument, the name of the <select> element to be connected to this new ListControl. All the ListControl methods, as described in ListControlClass.js, are now available to you! Table 10.1 details the specifications of these methods . note It's important to remember that the visual element is the HTML <select> menu. The ListControl object is a JavaScript object, which has its own properties and methods but has no visual interface of its own. That's why the <select> element and the ListControl object must be created separately, and then joined so that they function together. Table 10.1. Methods of the ListControl Object Class. To Access These Methods, Your Extension File Must Be Llinked to the Class File. | Creating and Managing ListControl Structures | | Syntax | Description | | list.refresh() | Captures the current selection | | list.enable() | Enables control if not already enabled | | list.disable() | Disables control if not already disabled | | Putting Information into a List | | Syntax | Description | | list.init() | Sets the list to the current HTML text and values | | list.setAll (labelList,valueList) | Sets the entire list at once | | list.add() | Adds a new blank line after the selected line | | list.add (labelString) | Adds text | | list.add (labelString, valueString) | Adds text and an associated value | | list.append() | Appends a new blank line to the end of the list | | list.append (valueString) | Appends default text | | list.append (valueString, value) | Appends text and an associated value | | list.del() | Deletes the selected line | | list.set (textstring) | Sets the text of the current selection | | list.set (textString, n ) | Sets the text of the n th item | | list.init() | Sets the entire list to the current HTML text and values | | list.setValue (value) | Sets the value of the current selection | | list.setValue (value, n ) | Set the value of the n th item | | list.setIndex( n ) | Sets the selection to the number given as n | | Getting Information from a List | | Syntax | Description | | list.get() | Returns the current selection text | | list.get( n ) | Returns the text of item n (starts at zero) | | list.get('all') | Returns an array of all text items | | list.getValue() | Returns the current selection value | | list.getValue( n ) | Returns value item n (starts at zero) | | list.getValue ('all') | Returns an array of all value items | | list.getValue ('multiple') | Returns an array of all selected value items | | list.getIndex() | Returns the selected index | | list.getLen() | Returns the list length | | list.pickValue ( value ) | Sets the selection to the item with the given value | ListControl Practice Nervous about using ListControl elements? There's no need to be. ListControls are remarkably simpleand lots of fun to work with. This practice session will help you get comfortable with this wonderful interface tool. Task 1: Build a basic command file to play with ListControl lists can be used anywhere a standard popup menu or list is possiblein dialog boxes for commands, objects, and behaviors, or in Property inspectors or floating panels. For this practice session (and the rest of the practice sessions throughout this chapter), we'll practice on the easiest kind of extension to set upthe command. Our first task is to create the command. We'll build the framework and create a very simple dialog box with a <select> list form element. -
Start by creating a simple command file to practice with. In your text editor, create a new file. Enter the following framework code: <html> <head> <title>ListControl Practice</title> <script language="JavaScript"> function myCommand() { //command statements here } </script> </head> <body> </body> </html> When the code is in place, save the file in the Configuration/Commands folder as ListControl Practice.htm. -
It's not important what this command does (at the moment, it does nothing). But you want it to have a dialog box that includes a <select> element you can play with and a set of OK and Cancel buttons so that you can close the dialog box with or without executing the command's main function ( myCommand() ). To accomplish this, add the following code to your command file (new code shown in bold): <html> <head> <title>ListControl Practice</title> <script language="JavaScript"> function myCommand() { } function commandButtons() { return new Array("Apply","myCommand()","Close","window.close()"); } </script> </head> <body> <form name="myForm"> <select name="mySelect" size="5" > <option>**nothing yet**</option> </select> </form> </body> </html> Why does the <select> element contain only one option, **nothing yet** ? Because the list will be populated (filled with entries) dynamically after it has been turned into a ListControl element. Note also that the commandButtons() function defines Apply and Close, instead of OK and Cancel, buttons. As you'll see in the following tasks , this makes running diagnostics easier. -
To make sure your command works, try it out in Dreamweaver. The resulting dialog box should look like the one shown in Figure 10.3. Figure 10.3. The ListControl Practice dialog box. Task 2: Create a ListControl object and attach it to the <select> element Okay, you have a <select> form element in place. Now it's time to officially turn that <select> menu into a ListControl element, or list. This involves following the steps outlined in the earlier section "The ListControl Element in the Interface." -
First, you must be linked to the shared file that defines the ListControl class. To establish this link, revise your command file's <head> section by adding the following code (shown in bold): <head> <title>ListControl Practice</title> <script src="../Shared/Common/Scripts/ListControlClass.js"></script> <script language="JavaScript"> This code links your command file to the Macromedia shared file where the ListControl class is defined. Note how the relative path to the shared file is constructed . (Up one folder, and then down into the Shared/MM/Scripts/Class folder to find the ListControlClass.js file.) -
Add a global variable to your command file's main <script> section, like this (new code is in bold): <script language="JavaScript"> var myList; function myCommand() { //command statements here } etc </script> -
Now you need an initializeUI() function, set to create a new ListControl element when the document loads (new code is in bold): <script language="JavaScript"> var myList; //thisfunction creates the ListControl element function initializeUI(){ myList=new ListControl('mySelect'); } etc other functions </script> </head> <body onLoad=" initializeUI() "> That's it! Believe it or not, that's all you have to do to create a ListControl element. Of course, if you try out your command in Dreamweaver right now, the <select> won't behave any differently because you haven't used any ListControl methods to control it. But you're on the road! Task 3: Initialize the ListControl list One of the prime purposes of ListControl elements is to allow easy creation of dynamically populated popup menusin other words, popup menus whose entries will be created based on conditions in the user's computer at runtime. (If you did the exercises in Chapter 5, remember the Automatic Alt Text commandits dialog box included a popup menu of images in the user 's document.) In this task, we'll add the list.setAll() method to our initializeUI() function to generate entries for the list. -
To generate all entries for a ListControl element, use the list.setAll() method. Check the syntax requirements for this method in Table 10.1 and you'll see that it takes two arguments: list and valueList . The first is an array of strings that will become the labels of items in the ListControl element; the second is an array of strings that will become the values of items. So, start by adding two arrays to the initializeUI() function (new code is in bold): function initializeUI(){ myList=new ListControl('mySelect'); var listArray = new Array("A Night at the Opera","A Day at the Races","Duck Soup","Horse Feathers","Animal Crackers","Monkey Business"); var valArray = new Array("opera","races","soup","horse","animal","monkey"); } What you've done here is create six menu items for the <select> list, each complete with a label (the contents of listArray ) and a value (the contents of valArray ). -
Now that you have what you need for the list.setAll() methods' required parameters, add the method to your initializeUI() function (new code is in bold): function initializeUI(){ myList=new ListControl('mySelect'); var listArray = new Array("A Night at the Opera","A Day at the Races","Duck Soup","Horse Feathers","Animal Crackers","Monkey Business"); var valArray = new Array("opera","races","soup","horse","animal","monkey"); myList.setAll(listArray,valArray); } -
Try it out. Reload extensions in Dreamweaver and choose Commands > ListControl Practice. The command calls up a dialog box like that shown in Figure 10.4. Figure 10.4. The ListControl ListControl Practice dialog box, with its <select> list initialized . Note that ListControl elements must be initialized in this way. If you fill the <select> list with entries by hard-coding each <option> element into the HTML of your extension file, instead of using list.setAll() , Dreamweaver won't recognize those entries for scripting purposes, and you won't be able to control them using ListControl methods entries. Task 4: Examine the list Now that you have a fully populated list in your dialog box, you want to quickly learn about itincluding what entries it contains and which entry (or entries) the user has selected. You can do this with the various get- related methods of the ListControl object. For this practice session, you'll program the ListControl Practice command to get information when the user clicks OK, which means adding new code to the myCommand() function. -
Revise the myCommand() function to determine how many items are in the list, like this: function myCommand() { var myMessage=myList.getLen(); window.alert(myMessage); } -
After this code is in place, try it out. In Dreamweaver, reload extensions and choose Commands > ListControl Practice. In the dialog box, click OK. An alert window should open with the number 6 showing as its message. That's because there are six items in the list. -
Now ask about the selection. Revise your myCommand() function to look like this: function myCommand() { var myMessage=myList.get(); window.alert(myMessage); } As Table 10.1 showed you, the list.get() method accesses the label of the selected list item. -
Try this code out. Reload Dreamweaver extensions, choose the command, select an item from the list, and click OK. Depending on which item you choose from the list, the resulting dialog box will look something like Figure 10.5. Figure 10.5. The ListControl Practice command, displaying the currently selected list item. -
Take a few moments now to explore the other get methods. For each method, use the myCommand() function to put your collected information into the alert window that this command calls up. Task 5: Add and remove list items After a ListControl list has been initialized, you might want to add or remove individual entries, one at a time, as the user interacts with the dialog box or panel that contains the list. To do this, use one of the list.add() or list.remove() list.add() or list.remove() methods shown in Table 10.1. -
To add a new list item when the user clicks OK, revise your myCommand() function like this (new code is in bold): function myCommand() { myList.add("A Night in Casablanca"); } -
When this code is in place, reload extensions in Dreamweaver and try it out. Choose Commands > ListControl Practice. In the dialog box that appears, select the first item in the list and click OK. Then select the last item in the list and click OK. Every time you click OK, another menu item named A Night in Casablanca appears. -
To remove any list item when the user clicks OK, revise your myCommand() function like this (new code is in bold): function myCommand() { myList.del(); } -
When you're done, try this one out. In the ListControl Practice dialog box, select any menu item and click OK. It's gone! -
After you have the hang of this, explore some of the other methods that have to do with adding and removing entries. Tinker until you have a good idea what each method does that is unique. Task 6: Move items up (and down) in the list Rearranging the list is not quite as easy as adding and removing elements, because there is no list.rearrange() method. To rearrange items in the list, you need to use one of the list.get() methods to collect the labels and values from the list, rearrange those values, and then use one of the list.set() methods to re-insert those items. -
Because this is a more complex operation, you'll create two new functions in your command file to hold the instructions for moving an item up and down. Start by adding the framework code for the moveUp() function to your <script> tag: function moveUp(){ //get selected item (name, value, and index) //determine if it's the first item //get the item above the item (name and value) //put the selected item into the position above (index - 1) //put the other item into the current position (index) //change selection to the position above (index 1) } Can you see what logic the framework is following? In each function, you want to collect the information from the currently selected item and the item above it. Then you want to put that information in the proper slotin other words, the slot above and the current slot. And finally, you want the selection in the list to change, so now the slot above is selected. -
Now add the code to the framework (new code is in bold): function moveUp(){ //get selected item (name, value, and index) var myName=myList.get(); var myValue=myList.getValue(); var myIndex=myList.getIndex(); //determine if it's the top item if (myIndex==0) { return; } //get the item above the item (name and value) var upName=myList.get(myIndex-1); var upValue=myList.getValue(myIndex-1); //put the selected item into the position above (index - 1) myList.set(myName,myIndex-1); myList.setValue(myValue,myIndex-1); //put the other item into the current position (index) myList.set(upName,myIndex); myList.setValue(upValue,myIndex); //select the position above myList.setIndex(myIndex-1); } As you can see, after the logic has been laid out, writing the code is fairly simple. It just involves several trips to Table 10.1, to take advantage of the various ListControl methods. -
After you have the moveUp() function in place, revise the myCommand() function to call the moveUp() function: function myCommand() { moveUp(); } The myCommand() function, remember, gets executed when the user clicks OK. By calling moveUp() from here, you're turning the OK button into a sort of Up button. -
Try it out. When you get the ListControl Practice dialog box open, select the item at the bottom of the list (Monkey Business) and click OK to move it up. If it doesn't work, tinker with your code until it does. -
After you have the moveUp() function in place, the moveDown() function is quick and straightforwardjust a matter of duplicating the moveUp() function and changing a few directional items within. In your code, select the entire moveUp() function and duplicate it so that you have two in your <script> tag. Then make the following changes (shown in bold): function move Down (){ //get selected item (name, value, and index) var myName=myList.get(); var myValue=myList.getValue(); var myIndex=myList.getIndex(); //determine if it's the last item if (myIndex==( myList.getLen()-1) ) { return; } //get the item below the item (name and value) var down Name=myList.get(myIndex + 1); var down Value=myList.getValue(myIndex + 1); //put the selected item into the position below (index + 1) myList.set(myName,myIndex + 1); myList.setValue(myValue,myIndex + 1); //put the other item into the current position (index) myList.set( down Name,myIndex); myList.setValue( down Value,myIndex); //select the position below myList.setIndex(myIndex + 1); } -
To see how this function works, change the myCommand() function so that it calls this function (new code is in bold): function myCommand() { move Down (); } -
Try it out. In the ListControl Practice dialog box, select the first item and use OK as a down button to scoot the item down the list. That's all there is to coding a simple ListControl element. Now let's see how to spiff things up a little by adding some graphic appeal . Task 7: Add button graphics to the interface As shown earlier in Figure 10.2, a common arrangement of buttons for ListControls is to have a + and button on the left, and up and down buttons on the right. Each of those buttons is a graphic from the Shared/MM/Images folder. In this task, we'll access the shared graphics and add those four images to the ListControl Practice file. -
Start by refining the layout of your dialog box, creating a table to contain the image buttons in its top row and the <select> element into its bottom row. Figure 10.6 shows what the revised layout should look like. The revised code for your <body> section should look like this (new code is in bold): <body onLoad="initializeUI()"> <form name="myForm"> <table> <tr> <td align="left"> </td> <td align="right"> </td> </tr> <tr> <td colspan="2"> <select name="mySelect" size="5" > <option>**nothing yet**</option> </select> </td> </tr> </table> </form> </body> Figure 10.6. The ListControl Practice command file, with the layout adjusted to fit image buttons at the top. -
Now add all four buttons (add, remove, up, down) to the top row of the table two to each cell. It's easiest to do this in Dreamweaver Design view, but you can code it by hand if you like. If you're working in Design view, to insert each button choose Insert > Form Objects > Image Field. In the Select Image Source dialog box, navigate to the Configuration/Shared/MM/Images folder and place btnAdd.gif and btnDel.gif in the top left cell and btnUp.gif and btnDown.gif in the top right cell. Name each button to match its filename, minus the extension (for instance, btnAdd for the btnAdd.gif graphic).For accessibility, also add alt text to each button, such as Add Item or Move Item Up in List . Figure 10.7 shows this happening. Figure 10.7. Using Dreamweaver Design view to add the four buttons to the ListControl Practice dialog box. If you're creating the code by hand, the code for the top row of your table should end up looking like this: <tr> <td> <input name="btnAdd" type="image" src="../Shared/MM/Images/btnAdd.gif" width="20" height="18" border="0" alt="Add Item"> <input name="btnDel" type="image" src="../Shared/MM/Images/btnDel.gif" width="20" height="18" border="0" alt="Remove Item"> </td> <td align="right"> <input name="btnUp" type="image" src="../Shared/MM/Images/btnUp.gif" width="20" height="18" border="0" alt="Move Item Up in List"> <input name="btnDown" type="image" src="../Shared/MM/Images/btnDown.gif" width="20" height="18" border="0" alt="Move Item Down in List"> </td> </tr> Task 8: Add event handlers to the images As long as you have the images in there, you might as well put them to work. By attaching event handlers to the images, you can use them to trigger the ListControl methods you've been working with. -
For the Up and Down buttons, add event handlers that include function calls for the moveUp() and moveDown() functions (new code is in bold): <input name="btnUp" type="image" src="../Shared/MM/Images/btnUp.gif" width="20" height="18" border="0" alt="Move Item Up in List" onClick="moveUp()" > <input name="btnDown" type="image" src="../Shared/MM/Images/btnDown.gif" width="20" height="18" border="0" alt="Move Item Down in List" onClick="moveDown()" > -
Try it out. In the ListControl Practice dialog box, clicking the Up and Down buttons should move the selected list item up and down in the list. Just like all of the other lists in Dreamweaver. -
For the Add and Remove buttons, add the following event handlers (shown in bold): <input name="btnAdd" type="image" src="../Shared/MM/Images/btnAdd.gif" width="20" height="18" border="0"alt="Add Item" onClick="myList.add('Love Happy','happy')" > <input name="btnRemove" type="image" src="../Shared/MM/Images/btnDel.gif" width="20" height="18" border="0"alt="Remove Item" onClick="myList.del()" > -
Try out this functionality. Clicking the + button adds Love Happy to the menu; clicking the button removes the selected menu item. note Of course, in the real world, an Add button that kept adding the same menu item over and over would be fairly useless. Instead of this limited functionality, you would probably call up a dialog box to ask the user what menu item she would like to add. For purposes of this practice, however, we're keeping things simple and adding hard-coded information only. |