| As with Property inspectors, we don't have access to the code for most of the Dreamweaver standard floaters . All of the floating panels listed in the Window menu are coded into the program at C-level, and so are inaccessible to us. There is, however, a documented API for creating floaters as extensions. Floater extensions are different from C-coded floaters in two ways that will impact us: -
Floaters coded as extensions always float on top of the current document or go behind it, depending on the user setting for "all other panels" in the Edit > Preferences > Panels dialog box. -
Floaters coded as extensions cannot have icons in their title tabs. Their title bars always display a name , determined by the page title. Floating Panels in the Configuration Folder Floater extensions live in the Configuration folder at the root level of the Floaters folder. Supporting files called on by floaters can live in subfolders within the Floaters folder. Figure 7.2 shows a list of the contents of the Floaters folder, in its default state. (There's not much in there, because the standard Dreamweaver floaters are not coded as extensions.) Figure 7.2. The Configuration/Floaters folder. Supporting files can be stored in subfolders, but all main floater files must be stored at the root level.  Floating Panel Files Each floating panel is created from one or more files: -
HTML file (required). This is the main floater file. Without this file, there is no floating panel. -
JS file (optional). As usual, the JavaScript portion of the floater can be saved in the HTML file or separately in a linked JS file. It's customary, though not required, to match this file's name with that of the main file (for example, MyFloater.htm and MyFloater.js). -
Supporting media files (optional). Floaters can contain graphics or even SWF (Flash) movies, as desired. These can be stored in the Floaters folder, preferably in a subfolder. Macromedia recommends, however, that multiple support files be stored in a custom folder in the Configuration/Shared folder. (This can be the same custom folder you create for help documents, shared JavaScript files, and any other support files for any extensions you develop.) The Structure of a Floating Panel File Because the possible purposes of floaters are so varied, the API is simple and openended. At their simplest, floater files require very littlejust a few API functions to help display and process information, and some kind of method to hide and show the floater. At their most complex, they can include API functions that watch the user's document for editing changes, and constantly collect and process information. Required Elements Not much is required to create a floater. A floater file must exist at the root level of the Floaters folder. Beyond that, the API requires just the following: -
Filename. The floater filename (obviously a required element!), minus its .htm or .html extension, becomes the floater's official name for scripting purposes. It's therefore safest, though not required, to avoid spaces and special characters . The filename must also not be one of the reserved floater names that Dreamweaver uses for its own built-in floaters. These names are behaviors , css styles , data bindings , frames , history , html , html styles , launcher , layers , library , objects , properties , server behaviors , site files , site map , templates , and timelines . -
Means of hiding and showing the floater. Because floating panels are not visible by default, each floater must have its opening (and closing) triggered by some other element in the Dreamweaver interface. The API provides two methods for this: dw.toggleFloater() and dw.setFloaterVisibility() . The first of these methods, dw.toggleFloater() , toggles the visibility of a floateropening it if it's closed and closing it if it's open . It takes one parameter, the name of the floater (as specified in the previous section), like this: dw.toggleFloater("myFloater"); The second method, dw.setFloaterVisibility() , can be used to hide or show a floater. It takes two parameters, the floater name and true/false, to open or close the floaterlike this to open a floater: dw.setFloaterVisibility("myFloater",true); or like this to close the floater: dw.setFloaterVisibility("myFloater",false); Either of these methods can be placed anywherecommand, menu command, object, behavior, you name itbut the most common method of opening and closing floaters is to place one of them in a <menuitem/> entry in the menus.xml file. The following line, for instance, entered in menus .xml, would open MyFloater: <menuitem name="My Floater" enabled="true" command="dw.toggleFloater('MyFloater')" checked="dw.getFloaterVisibility ('MyFloater')" id="MyStuff_MyFloaterOpener"/> What does this code do? If placed in the Window menu, it creates a My Floater menu item in that menu. The checked parameter uses a related API method, dw.getFloaterVisibility() , to determine if the floater named MyFloater is currently open; if it is, the menu item will display with a checkmark next to its name. (Note that this method gets the visibility, rather than setting it.) Instead of a file parameter, which would specify a command file for Dreamweaver to process when the user chooses the menu item, the command parameter instructs Dreamweaver to execute the dw.toggleFloater() method when the user chooses the menu item, opening or closing the floater named MyFloater . -
Page title. The floater file's <title> appears in the title bar of the floating panel. (As noted previously, there is no way to show image icons in the title bar the way that the Dreamweaver built-in floaters do.) -
Body content. No scripting or <form> elements are required, unless you want the floater to actually be interactive. Any content placed inside the <body> tags becomes the body of the floating panel. Note, however, that Dreamweaver does not process onLoad event handlers placed in floater file <body> tags. Use initialTabs() or initialPosition() to get around this. (This is discussed in more detail later in this chapter.) Optional Elements Okay, so a floater doesn't need much. But it can take advantage of various optional elements, if they're defined: -
<form> . Form elements are used in floaters just as they're used everywhere else in the APIto allow user input and interactivity. -
initialPosition() function. The first time a user calls up a floating panel, this function determines where on the screen the panel appears. If the function is not defined, the panel appears in the center of the screen. The function should return a string representing "leftPositionPixels, topPositionPixels" . It takes one optional parameter, platform , which can accept Mac or Win as values. Thus, the following code places the floater at coordinates of 60,60 on Macintosh and 100,100 on Windows: function initialPosition(Mac) { return "60,60"; } function initialPosition(Win) { return "100,100"; } The initialPosition() function is called automatically, but it is only called once in the floater's lifetime because after that Dreamweaver remembers the panel's position so it will always appear where the user last left it. -
isDockable() function. This function, called automatically as part of the API process every time the floater appears, determines whether or not the floater appears with a docking bar at its top, allowing it to be docked with other panels. The function should return true / false . The absence of this function is the same as returning true . -
getDockingSide() function. This function determines how the floater will integrate with the Dreamweaver MX integrated workspace (Windows only). Assuming that the user is working in the integrated workspace (not the classic workspace), it specifies where in the integrated application window the panel will be docked. It takes no parameters and should return a string containing either the word left or right , and either the word top or bottom . For instance, the following code creates a floater that docks at the upper left of the application window (below the Insert bar, in other words): function getDockingSide() { return "left top"; } This function has no effect unless the integrated workspace is being used, so it is inactive for Dreamweaver/Mac and for Dreamweaver/Windows in classic workspace. -
isAvailableInCodeView() function. This function determines whether the panel will be grayed-out when the user is working in Code view. The function takes no parameters and should return true / false . -
displayHelp() function. Dockable floating panels all appear with the standard Options menu icon in the upper-right corner. Clicking on that icon displays the panel's Options menu, which includesamong other itemsa Help command. If the displayHelp() function is defined in the floater's HTML or JS file, this function is executed when the user clicks the chooses Help from the panel's Options menu. Without this function, the Help command is nonfunctionaland probably confusing to users, who will wonder why it doesn't work. (Note that if the isDockable() function returns false , there is no docking bar or options menu icon at the top of the floater window.) -
selectionChanged() function. As long as the floater is visible onscreen (that is, open), this function is called every time the user changes the insertion point, selection, or focus. It returns nothing, but can be used to make the floater responsive to user focus as he works. Examples of this functionality include the frames panel, which changes its display depending on which part of the frameset has focus; the behavior panel, which changes its title bar, depending on what tag the user has selected; and so on. Because selectionChanged() is called so frequently, it can impact Dreamweaver performance. Therefore, this function should be used only if absolutely necessary. -
documentEdited() function. As long as the floater is visible onscreen (that is, open), this function is called every time the document is edited. It returns nothing, but can be used to make the floater responsive to document changes as they happen. Examples of this functionality include the code inspector, in which changes made in the design window are immediately reflected in the panel's code display; the layers panel, in which changes in layer name, visibility and zindex are immediately registered; and so on. Because documentEdited() is called so frequently, it can impact Dreamweaver performance. Therefore, this function should only be used if absolutely necessary. API Procedure for Floating Panels The procedure for floating panels begins when one of the floater-opening commands is called ( dw.setFloaterVisibility() , dw.toggleFloater() , dw.getFloaterVisibility() ). At that point, the following events occur: -
Dreamweaver searches the Configuration/Floaters folder for a filename matching the floater name plus the .htm or .html extension. If this file is found, it's now loaded. -
If the floater is being loaded for the first time, Dreamweaver looks for and calls the initialTabs() and initialPosition() functions. -
If documentEdited() and selectionChanged() are defined, Dreamweaver calls them now, on the assumption that both document and selection have probably changed since the panel was last open. -
The documentEdited() and selectionChanged() functions continue to be called as needed, as long as the panel is open. Event handlers attached to form elements in the floater are also called as needed. -
When the user quits Dreamweaver, the program saves all panels' current position, visibility, dimensions, and tab groupings. These will be restored the next time the program is launched. Figure 7.3 shows a diagram of this process. Figure 7.3. The API procedure for floating panels.  Note that after Dreamweaver loads a floater file, it doesn't load the file again until the user quits and relaunches the program. When you're testing extensions, simply reloading extensions from the Insert bar won't reload floaters; you need to quit the program and start it up again.  |
