Accessibility
Adobe
Sign in Privacy My Adobe

Extension User Interface Guidelines

Dreamweaver | Fireworks | Macromedia Flash

Dreamweaver

This text provides guidelines for creating extensions to Dreamweaver that complement Dreamweaver's user interface.

You'll need to follow the required guidelines (see "UI requirements") to obtain Macromedia certification of your extension. Following the guidelines in "Additional UI suggestions" is not required, but will make your extension more consistent with the look and feel of the Dreamweaver user interface.

Following all of these guidelines will help make your extensions easier for users to understand and work with. Many of the guidelines are intuitive; others that aren't as obvious are intended to make your extensions look right across platforms. The guidelines are not intended to stifle your creativity; try to provide a distinctive look and feel while retaining familiar UI concepts and interaction paradigms. Web designers want a user interface that doesn't distract them from using the product to create Web pages.

This document assumes that you're familiar with the Dreamweaver API and with creating extensions to Dreamweaver. If you aren't, see Extending Dreamweaver.

UI requirements

An extension must meet the following UI requirements to obtain Macromedia certification.

 
Fonts, colors, and branding

  • Don't set fonts or background colors. If no fonts or colors are set, Dreamweaver automatically chooses the right font and colors for both Windows and Macintosh (black text on a gray background), ensuring your dialog boxes and other UI elements look right and match the rest of Dreamweaver.
  • Don't use font styles, such as bold and italic.
  • If you want to add your own branding or company logo, place it at the bottom of a dialog box or on the right side of a Property inspector. (If you include help text in a dialog box, you may place the company logo inside the help-text table cell.) Clicking the company logo should open the company's Web page in the user's default browser. You can also include an About button on a dialog box that displays an HTML page or another dialog box containing information about you or your company.
  • To include brief help text in a dialog box, place it in a table cell at the bottom of the dialog box, setting the cell's background color to #D3D3D3.
    Branding image

 
Buttons

  • Object and behavior dialog boxes automatically contain two default buttons: OK and Cancel. You can display a Help button by defining the displayHelp() function; otherwise, buttons are not customizable.
  • The commandButtons() function defines the buttons that appear in a command dialog box. You must explicitly define each of these buttons. Buttons defined with commandButtons() are automatically placed in the top right corner of the dialog box.
  • In a command dialog box, the OK button (or its equivalent) should always appear first, followed by Apply (if applicable), other buttons that apply to the operation of the command as a whole (if any), Cancel, and Help—in that order.
  • Buttons that help the user set values in the dialog box (such as a Browse button next to a text field) should be placed in the main body of the dialog box, not on the right side (where OK and other whole command buttons are located).
  • You must define buttons in floating palettes or Property inspectors using <INPUT> tags.

 
Dialog box layout

  • Use tables to lay out your dialog boxes.
  • To vertically align all elements in the table cells, set valign = baseline. This will align text properly with form objects (text fields, radio buttons, and so on).
  • Set the nowrap attribute in any cell where the text must stay on one line.
  • For text fields in forms, don't use the size attribute; it doesn't give reliable results on the Macintosh. Instead, use style="width:230px" for wide text fields (to hold file URLs, for instance) and style="width:135px" for narrower ones.
  • Capitalize the first letter of each word in label text.
  • Labels appear to the left of controls. They are right-aligned (align = "right") and end with a colon. Do not wrap label text.
  • Set the first text field in a dialog box to have focus when the box opens. If there is a default value in the first text field, have it highlighted so users can change the value without having to click in the field first. (Dreamweaver's Email Link and Table objects are examples of the correct way to do this.)
  • If a control consists of more than one line (such as a multiline text field), align the control's labels with the top row of the text displayed or entered in the control.
    Dialog box guidelines

 
Help

  • You must include a Help button in your extension, unless you use a tabbed dialog box or your Help text is extremely short (see below).
  • When the user clicks the Help button, do one of three things:
  • Display a dialog box that contains Help text.
  • Open an HTML page in a browser. You can place this page in Configuration/Shared/YourFolder/ (by including it in your extension package file) or on your Web site.
  • Show Help text in another layer.
  • Instead of a Help button, you can create a tabbed dialog box (using layers) and make one of the tabs a Help tab.
  • Your Help text should generally provide more information than can fit at the bottom of your dialog box. However, if your Help text does consist of one short paragraph or less, you can place the text directly in the dialog box instead of providing a Help button. Place the text in a table cell at the bottom of the dialog box. Use a slightly lighter shade of gray (#D3D3D3) for the background color of the table cell to offset it from the rest of the dialog box.
  • Your Help text should include, at minimum, explanations of each field or value the user can control, and/or a procedure describing how to use the extension.

 
Dialog box size

  • Don't try to fit too much into a dialog box.
  • The HTML area for dialog boxes has a minimum size of 200 x 50 pixels and a maximum of 511 x 434 pixels. If the content of the HTML area exceeds this maximum in either dimension, Dreamweaver automatically adds scroll bars to ensure that the entire dialog box fits within the total window size of 640 x 480 pixels (this includes the title bar, the column of OK/Cancel buttons, and everything else). Scroll bars in a dialog box are poor UI design; Macromedia won't approve a dialog box that Dreamweaver adds scroll bars to. Use a better layout rather than a bigger dialog box.
  • If you have too much content to fit into a dialog box without using scroll bars, remove or redesign your content. Try moving help information out of the dialog box and into another dialog box or an HTML page, or try creating a tabbed dialog box using layers. See the Drag Layer behavior for an example.
  • In some circumstances, you can make your controls fit better in a dialog box by removing space between table cells and by using the <nowrap> tag.
  • Don't set a height or width for your dialog boxes; Dreamweaver sets dialog box sizes automatically.

 

Additional UI suggestions

The following UI guidelines are not required for Macromedia certification, but are recommended to improve consistency with Dreamweaver's look and feel.

 
Invalid data and error checking

  • Allow the user to enter invalid values in fields as long as those values don't result in display problems. This is for two reasons:
  • An attribute's specification may change (after your extension is released) to allow new values; the user should be allowed to enter such values.
  • The user may want to provide a temporary placeholder, such as the name of an image file or document that has not been created yet.
  • If the entered value is an obvious mistake, or could cause a crash or display problem in Dreamweaver or a browser, display a warning and restore the previous value.

 
Lists

  • A list can appear as either a pop-up list or a multiline list (created with the <select> tag). If you want the user to select a single item from the list, use the pop-up. If multiple items are to be configured, use a multiline list. For example, the Change Property behavior sets a single property on a single object, so it uses pop-up lists for object selection:
    List Dialog box
  • The Swap Image behavior can assign new source files to several images at once, so it uses a multiline list for object selection:
    List Dialog box
  • Additive lists are multiline lists that allow the user to add and delete items. The behavior examples above present lists of preexisting objects. When the user can build a list, use plus and minus buttons for adding and deleting lines, and use a mini-form below the list for editing a particular list item. For example:
    List Dialog box
  • A plus (+) button adds a new element to a list. When clicked, it can display a pop-up menu, display a dialog box to allow the user to enter a value, or add a value specified elsewhere. In an editable list, the plus button adds a new empty item, and the user can type a value. New items are added at the index of the selected element, or at the end of the list if nothing is selected (unless the list is sorted). Dim the plus button when no items can be added to the list.
  • A minus (-) button removes the selected element.Dim it when no items can be added to the list.
  • A down arrow button moves the selected element down one place in the list; an up arrow button moves the selected element up. Dim these buttons when nothing is selected, or when the selected element cannot be moved up or down any further.
  • The images for these buttons are located in the Configuration/Shared/MM/Images folder.
  • Double-clicking a list element causes some action to occur, such as displaying a dialog box to allow the user to edit the value, or applying a style.

 
Property inspector layout

A given layout looks different on Macintosh and Windows. Test your Property inspector on both platforms; try to find a layout that makes all fields visible and selectable on both platforms, even if that layout isn't perfect for either platform.

 
Miscellaneous

  • As noted in Extending Dreamweaver, Dreamweaver does not support links or frames in an extension, and it can't browse the Web directly. However, an extension can launch a browser window displaying a specific URL, and it can launch other commands and behaviors.
  • To allow rapid content creation, fill in your form fields with default values automatically.
  • To use an image (such as a folder icon) as a button, use the tag <input type="image">.
  • If you're creating your extension's UI using Dreamweaver, use the Insert Rollover command to make buttons highlight when pointed to.
  • Use checkboxes for controls that can be selected or deselected independently. If you want a set of controls to be mutually exclusive, use radio buttons instead.
  • In a set of radio buttons, always set one of the radio buttons to be selected by default.
  • Don't use windowDimensions() to set the size of your dialog box; instead, rearrange the fields in the dialog box, or use layers.

Fireworks

This document provides guidelines for creating extensions that complement the Fireworks user interface. In addition to the testing guidelines, you should follow these user interface (UI) guidelines to obtain Macromedia certification of your extension. This document assumes that you're familiar with the Fireworks API and with creating extensions to Fireworks. If you aren't, see the Extending Fireworks documentation--available on your Fireworks MX CD or in printed form through the Macromedia online store.

Each Fireworks extension type has its own UI guidelines. Each set is outline below.

Libraries
Textures, Patterns and Styles
Dictionaries
Keyboard Shortcuts
JSF Commands without User Interface
Commands with SWF Movie User Interface
Miscellaneous SWF Interface Design Notes

Libraries

  • The file name of the Library should use initial capitalization for each major word.
  • Give meaningful names to the Library extension, the Library PNG file and any symbols therein; for example, "Navigation Bars," "Recycle Animation," or "Beveled Gray Button."

Textures, Patterns, and Styles

  • Texture and Pattern image file names should use initial capitalization for each major word.
  • Give the Textures and Patterns meaningful names; for example, "Burlap," "Denim," or "Blue Water."
  • Give the Style extension, the Style (STL) file, and the individual styles therein meaningful names; for example, "Blue Plaid Bevel" or "Green Embossed Text."

Dictionaries

  • The dictionary file name should use initial capitalization for each major word.
  • Give the dictionary file name a meaningful name such as "Company Acronyms" or "Employee Names."

Keyboard Shortcuts

  • The Keyboard shortcut file name should use initial capitalization for each major word.
  • Make both Macintosh and Windows version of your shortcuts, and title the files with the appropriate XML file extensions.

JSF Commands without User Interface

  • Give the Command extension and the Command JSF file meaningful names; for example, "Convert to Grayscale" or "Distribute to Layers."
  • The JSF file name and the extension-specific folder name within the Commands folder should use initial capitalization for each major word.

Commands with SWF Movie User Interface

  • Give the Command extension and the command's SWF movie file meaningful names; for example, "Align" or "Add Arrowheads."
  • The command's SWF movie file name should use initial capitalization for each major word.
  • The command name must appear in the title bar of the dialog or panel.
  • Text labels for controls should use sentence capitalization.
  • Labels appear to the left of controls. They are right-aligned and end with a colon. Do not wrap label text.
  • If a control consists of more than one line (such as a multi-line text field), align the control's labels with the top row of the text displayed or entered in the control.
  • In a dialog or panel with more than one screen, be sure that controls that are located in the same place across multiple screens do not move around as you change screens. For example, Back, Next, and OK buttons on the bottom of the dialog should be placed at the same coordinates on each screen.
  • Buttons which cause a dialog to appear must end with an ellipsis (...). For example, a Browse button must appear as "Browse..."
  • If the command's SWF movie is a dialog, the dialog must have a Cancel button so that the user may cancel the dialog without applying the command.
  • In a command dialog box, the OK button (or its equivalent) should always appear first, followed by Apply (if applicable) and then Cancel.
  • You must include a Help button in your extension, unless your Help text is extremely short (see below).
    When the user clicks the Help button, do one of three things:

    • Display a dialog box that contains Help text.
    • Open an HTML page in a browser. You can place this page in Configuration/Commands/YourFolder/ (by including it in your extension package file) or on your website.
    • Show Help text in another frame or scene of your SWF movie.

    Your Help text should generally provide more information than can fit at the bottom of your dialog. Your Help text should include, at minimum, explanations of each field or value the user can control, and/or a procedure describing how to use the extension.

  • Sample user interface organization following Fireworks Style Guidelines.

Miscellaneous SWF Interface Design Notes

  • To allow rapid content creation, automatically fill in your form fields with default values.
  • Use checkboxes for controls that can be selected or deselected independently. If you want a set of controls to be mutually exclusive, use radio buttons instead.
  • In a set of radio buttons, always set one of the buttons as the default selection.
  • Allow the user to enter invalid values in fields as long as those values don't result in display problems. This is for two reasons:

    1. An attribute's specification may change (after your extension is released) to allow new values; the user should be allowed to enter such values.
    2. The user may want to provide a temporary placeholder, such as the name of an image file or document that has not yet been created.
  • If the user enters an invalid value and it is an obvious mistake, or could cause a crash or display problem in Fireworks or a browser, display a warning and restore the previous value.
  • Add your own branding or company logo at the bottom of the dialog box or SWF movie panel, if you wish. Clicking on the company logo should display developer contact information or open the company's web page in the user's default browser.

 

Macromedia Flash

This document provides guidelines for creating extensions for Flash. You'll need to follow the required guidelines to obtain Macromedia certification of your extension. Follow all of these guidelines to make your extensions easier for the users to understand and use. Each type of extension has its own guidelines.

Libraries
Smart Clips
ActionScripts
Samples
Publish templates
Generator objects
Keyboard shortcuts
Utilities


Libraries

  • In a complicated Library extension, use frame comments or guide layers to explain how the extension was created.
  • Give the Library extension and any nested symbols meaningful names, for example, "Roman Numeral Counter" or "feather_graphic".
  • If a Library extension includes nested symbols, organize those symbols in a folder named "MasterSymbolName Assets". Replace "MasterSymbolName" with name of your Library extension.
  • If the Library extension is complicated, create an HTML help file that contains instructions. Place this file in the Flash MX>extensions Help folder. This folder is created by the Extension Manager. Name the file "ReadMe", prefixed with the name of your Library.

Smart Clips

  • Give the Smart Clip and any nested symbols meaningful names, for example,"Toggle Switch", or "Puzzle Piece".
  • Provide a clear and detailed description of each parameter in the Description panel of the Define Clip Parameter dialog.
  • If you author a Smart Clip, it is encouraged (but not mandatory) that you create a custom SWF UI to accompany it. This SWF UI file will be stored in the Flash MX>Libraries>Smart Clip UI folder. This folder is created by the Extension Manager.
  • When linking a custom SWF UI to your Smart Clip, the path would follow the convention "Smart Clip UI:myCustomUI.swf". This is a relative path to the folder where the SWF UI is stored, using the colon to separate the folder name from the file name.

ActionScripts

  • Use the comment action to add explanations to your script. Describe each section of your script.
  • Assume the new users will be trying to understand your scripts based on your comments.
  • Name variables and function in a consistent and meaningful way.
  • Follow good authoring practices as outlined in the ActionScript Reference Guide.
  • ActionScript files should be installed into a folder called "ActionScript" within the main Flash MX folder. The Extension Manager will create this folder if it does not already exist.

Samples

  • In a complicated sample, use frame comments or guide layers to explain how the sample was created.
  • Use the comment action to explain any ActionScript in the sample.
  • Give all symbols meaningful names.
  • Samples that are single FLA files can be installed in the Flash MX>Samples folder.
  • Samples that involve multiple files can also be installed outside of this folder. For the best results, create a new folder with the name of your Sample inside the Flash MX folder. This is done by following the documentation examples included with the Extension Manager.

Publish templates

  • Follow the guidelines in the Publishing and Exporting>About HTML publishing templates and Publishing and Exporting>Customizing HTML publishing templates sections of Using Flash or Flash Help.

Generator objects

  • Follow the guidelines in the Generator 2 "Extending Generator" documentation.

Keyboard shortcuts

  • Make both Macintosh and Windows version of your shortcuts, and title the files with the appropriate .mfx and .wfx file extensions.

Utilities

  • If you submit a Flash projector as a Utility, you must include the FLA source file. The Exchange QA team will examine the file to evaluate any potential issues, before the Utility is allowed to be distributed on the Exchange.