| An MXP file is nothing more than a package containing all the separate files that constitute an extension, along with a set of instructions on where each file should go and what changes should be made to menus .xml to support the extension. Creating an MXP involves collecting all the files, coding the instructions as an XML file, and using the Extension Manager to generate the package. Aside from a brief dip into some new XML, all the hard work is done by the time you're ready to package. Task 1: Collect your materials This sounds easy. Create a folder, somewhere outside the Configuration folder, and copy all the various files that constitute your extension into this folder. If your extension consists of only one or two files, and you're not creating any custom subfolders , it's a no-brainer. For more complex extensions, it takes a little bit of planning to assure that no one gets left out. Some tips: -
If your extension involves custom folders (a custom objects, behaviors category, or a shared folder, for instance), you don't need to copy those folders to the staging areathough if it helps you keep your organization straight, it doesn't hurt to copy them. -
If your extension consists of several filesespecially if they need to be stored in several different folders inside the Configuration foldermake a list of files (and where each should be stored) before you start collecting them. -
If your extension requires changes to menus.xml, make a note of those changes. Add them to the list of files you're already creating. -
If your extension includes different files with the same names (an object, command, and inspector all named Flash Detector.htm, for instance), you need to put them in different subfolders inside your collection folder. Whether you use subfolders or not doesn't matter, as far as the MXP-making process goes. It's just a way of allowing files with identical names to share space in preparation for packaging. note Technically, collecting the files is optional. It is possible to create an MXP package while your various extension files are still in their Development folders, scattered throughout the Dreamweaver Configuration folder. It's much easier, however, and safer to keep track of the files to be packaged if they're all in one place.
Collecting Materials for a Simple Extension: Set Page Properties Behavior (Chapter 3, Workshop #2) This simple behavior consists of only two files (HTML and JS), creates no special folders, and doesn't make any changes to the menus. The materials list is simple: -
Set Page Properties.htm -
Set Page Properties.js Collecting Materials for a Multifile Extension: Custom Horizontal Rule Object (Chapter 3, Workshop #3, and Chapter 6, Workshop #2) The list of materials to assemble for this extension includes the following: Figure C.1 shows the collection folder for this extension. Figure C.1. The files comprising the Custom Horizontal Rule object, assembled in a collection folder and ready for packaging.  Collecting Materials for an Extension with Menu Changes: Table Helper Floating Panel (Chapter 7, Workshop #1) This extension consists of only one file, so that part of the job is easy. But the checklist of materials also includes the menu changes: <menuitem name="Rest_ore All" id="DWMenu_Window_RestoreAll" /> add this: <separator /> <menuitem name="Table Helper" enabled="true" command="dw.toggleFloater('TableHelper')"  checked="dw.getFloaterVisibility('TableHelper')" id="RocketLaura_TableHelper_Floater"/> Task 2: Create the MXI (instructions) file This is the most painstaking part of the packaging process. The package requires an XML file, with the extension .mxi, containing instructions on where to put files, how to change menus, and what folders to create; as well as information on what the extension is supposed to do, who its author is, and so forth. The XML syntax for this file is very exacting. Saving the MXI File The installer file is simply an XML file saved with the .mxi extension. Its filename, however, must be valid on both Windows and Macintosh platforms, and can have no spaces. It can be saved anywhere on your hard drive, but because all pathnames to the extension files must be relative to the MXI file, it makes the most sense to save it in the collection folder with your other extension files. Structure of an MXI File Lucky for you, the Macromedia Extension Manager comes with detailed documentation, a sample file, and a blank template file to use in creating the MXI document. To find them, locate the application folder for the Extension Manager on your computer, and look inside. Inside the Samples/Dreamweaver subfolder, you see the following: -
Sample.htm A very simple command file. -
Sample.mxi An MXI instruction sheet for packaging the Sample.htm command file extension. -
Blank.mxi A blank MXI template to use in constructing your own MXI files. This file is nicely commented to help you fill it out. The contents of Sample.mxi, a simple but properly structured MXI file, are shown here: <macromedia-extension name="Hello, World" version="1.0" type="Command"> <! List the required/compatible products > <products> <product name="Dreamweaver" version="3" primary="true" /> </products> <! Describe the author > <author name="Macromedia" /> <! Describe the extension > <description> <![CDATA[ This is a sample extension.<br><br> It displays a javascript alert that says "Hello, World!". ]]> </description> <! Describe where the extension shows in the UI of the product > <ui-access> <![CDATA[ Access from the 'Hello, World' entry in the Commands menu. ]]> </ui-access> <! Describe the files that comprise the extension > <files> <file name="Sample.htm" destination="$dreamweaver/configuration/commands" /> </files> <! Describe the changes to the configuration > <configuration-changes> <! Add an entry to the commands menu > <menu-insert insertAfter="DWMenu_Commands_SortTable" skipSeparator="true"> <menuitem name="Hello, World" file="Commands/Sample.htm" id="Sample_HelloWorld" /> <separator id="Sample_HelloWorld_Separator" /> </menu-insert> </configuration-changes> </macromedia-extension> Unfortunately, both Sample.mxi and Blank.mxi are limited in only providing options for relatively simple extensions. Tables C.1 through C.16 provide more detailed specifications for the possible contents of the MXI file, along with syntax requirements. Use these tables in conjunction with the Blank.mxi template to construct your instruction file. note Note that the tables do not present an exhaustive list of elementsthey cover only those elements used for creating extension types covered in this book. A much more detailed set of instructions and syntax requirements is available in PDF form on the Macromedia Exchange Web site (http://www.macromedia.com/exchange/dreamweaver).
Table C.1 describes <macromedia-extension> , which is the main tag for extension installation files. Table C.1. MXI File: <macromedia-extension> | Attributes | Contents | Container | Examples | | id A unique extension ID to be created by Macromedia after you submit your extension. Never add or modify this attribute yourself. | <description> required <ui-access> required <products> required | None (this is the parent tag for the document) | <macromedia-extension name = "My Object" version = 1.0" type = "object" > <description> <ui-access> <products> </macromedia-extension> | | version The version number of the extension, in the format a[.b[.c]]. Valid entries include 1 , 2.5 , 3.0.2 type Indicates the kind of extension. Valid entries are object , command , behavior or action , browserProfile , translator , dictionary , encoding , floater , propertyInspector , jsExtension , query , template , thirdPartyTags , plugin , report , flashbuttonstyle , suite [*] [requires-restart] Indicates whether Dreamweaver must be restarted after the extension is installed. Valid entries are true and false . If omitted, this defaults to false . (For Dreamweaver 3, this attribute is ignored, and the program must always be restarted.) | <configuration changes> required only if the extension changes the menus or shortcuts files | | <macromedia-extension name = "Automatic Alt Text" version = 2" type = "command" > <description> <ui-access> <products> <configuration-changes> </macromedia-extension> | [*] A suite is a group of extensions installed as a unit. Table C.2 describes <products> . This tag is the container for one or more <products/> tags. Table C.2. MXI File: <products> | Attributes | Contents | Container | Examples | | None | One or more <products /> tags | <macromedia extension> | <products> <product /> <product / </products> | Table C.3 describes <product /> . Each instance of this tag specifies a Macromedia product(s) with which the extension is compatible. At least one <product/> tag must be defined. Table C.3. MXI File: <product /> | Attributes | Contents | Container | Examples | | name The name of a product. Valid entries are Dreamweaver , Fireworks , Flash , UltraDev | None (empty tag) | <products> | <product name = "Dreamweaver" version = "4" primary = "true" /> | | [version] The minimum version number that the extension should be used for. | | | [primary] Indicates whether the specified product is the one the extension was primarily intended for. | | | [required] Indicates whether the specified product is required for the extension to work properly. | | Table C.4 describes <author /> , which contains the extension author's name. This information will appear in the Extension Manager window. Table C.4. MXI File: <author /> | Attributes | Contents | Container | Examples | | name The author's name | None (empty tag) | <macromedia extension> | <author name = "Rocket Laura" /> | Table C.5 shows <description> . This tag describes what the extension does or is used for. This information will appear in the Extension Manager window. Table C.5. MXI File: <description> | Attributes | Contents | Container | Examples | | None | <![CDATA[ Put the descriptive text here. You can use and <br> to format the information. ]]> | <macromedia extension> | <description> <![CDATA[This command automatically inserts ALT text based on link or file name information to all images in the document.<br>Images which already have ALT text are ignored.]]</description> | Table C.6 describes <ui-access> . This tag specifies where to find the extension in the Dreamweaver user interface. This information will appear in the Extension Manager window. Table C.6. MXI File: <ui-access> | Attributes | Contents | Container | Examples | | None | <![CDATA[ Put the descriptive text here. You can use and <br> to format the information. ]]> | <macromedia extension> | <ui-access><![CDATA[Run this command by choosing Modify: Add Automatic Alt Text.]] </ui-access> | Table C.7 describes <files> , which is the container for one or more <file/> tags. Table C.7. MXI File: <files> | Attributes | Contents | Container | Examples | | None | One or more <file/> tags. | <macromedia extension> | <files> <file /> <file /> </files> | Table C.8 describes <file /> . Each instance of this tag provides information about a specific file to be installed as part of the extension. Table C.8. MXI File: <file /> | Attributes | Contents | Container | Examples | | source The nameof other file. It can include a path relative to the location of the installation file (the extension's files don't all have to be in the same folder). Use color , slash, or backslash to separate folder names and before the filename in the path. Don't use the same filenames as MM extensions unless your extension is intended as a substitute for the MM extension. | None (empty tag) | <files> | <file name="Automatic Alt Text.htm" destination="$dreamweaver/ commands" /> | | destination The name of the folder that the file will be copied to. If the folder doesn't exist, it will be created during installation. Valid entries begin with $dreamweaver , which refers to the DW Configuration folder. This attribute is not case-sensitive. Use a color, slash, or backslash between folder names in the path. | | | [platform] Indicates what platform the file is intended for. If a platform is specified, the extension is installed only on that platform. Valid entries are mac and win . | | | [shared] Indicates whether the file is used by more than one extension. (If the extension is uninstalled , shared files won't be removed.) Valid entries are true and false . | | | [systemfile] Indicates whether the file is used by anything other than extensions. | | Table C.9 describes <configuration-changes> . This tag is the container for tags specifying changes to menus, shortcuts, server behaviors, server formats, and data sources. Table C.9. MXI File: <configuration-changes> | Attributes | Contents | Container | Examples | | None | Any combination of <menu-remove> , <menu-insert> , <shortcut-remove> , <shortcut-insert> , <server-behavior changes> , <server format-changes> , <server-format definition-changes> , <data-source changes> tags. | <macromedia extension> | <configuration-changes> <menu-insert > <menuitem /> </menu-insert> </configuration-changes> | Table C.10 describes <menu-remove /> . Each instance of this tag specifies a menu bar, menu, menu item, or format to remove from the interface. Table C.10. MXI File: <menu-remove /> | Attributes | Contents | Container | Examples | | id Unique ID of the item to be removed. Note that menu bars and menus won't be removed unless they're empty. | None (empty tag) | Any of the following: <configuration changes> , <server- behavior-changes> , <server-format- changes> , <server- format-definition- changes> , <data- source-changes> | <menu-remove id ="DWContext_RemoteSite_ Checkout" /> | Table C.11 describes <menu-insert > . Each instance of this tag specifies where to insert a menu bar, menu, menu item, or format. Table C.11. MXI File: <menu-insert > | Attributes | Contents | Container | Examples | | Use only one of the following four attributes, determining the relationship of the new item to an existing menu item: | Contents of this tag will be inserted as a block into menus.xml file. When used When used When used | Any of the following: configuration changes> , <server behavior-changes> , <server-format changes> , <server format-definition- changes> , <data- source-changes> | <menu-insert insertAfter="DWMenu_ Happy"> <menu name="Campers" id="Menu_1"> </menu-insert> | | insertAfter [*] , insertBefore , appendTo , prePendTo Value must be an existing item's unique ID. | format- definition> parent tag, contents must include one or more <format> tags. | | | *[skipSeparator] If the insertAfter attribute is specified, assign true or false to this attribute to indicate whether the newly inserted item should be placed after any separator that follows the existing item. | Elsewhere, contents must include one or more <menu> and/or <menuitem> tags. [*] | | [*] See the discussion on menus.xml entries in Chapter 7, "Creating Custom Floating Panels," for details of how to format menu entries. Table C.12 describes <shortcut-remove /> . Each instance of this tag specifies a keyboard to remove from the menus.xml file. Table C.12. MXI File: <shortcut-remove /> | Attributes | Contents | Container | Examples | | id U nique ID of the shortcut to be removed. | None (empty tag) | <configuration changes> | <shortcut-remove id="DWFroggie"> | Table C.13 describes <shortcut-insert > . Each instance of this tag specifies a keyboard shortcut to be added to a particular location in the menus.xml file. Table C.13. MXI File: <shortcut-insert > | Attributes | Contents | Container | Examples | | listId Unique ID of the shortcut list in which to insert the new shortcut | <shortcut> tag Contents of this tag will be inserted as a block into menus.xml file. | <configuration changes> | <shortcut-insert listId="DWFrogList"> <shortcut> </shortcut-insert> | *See the discussion on menus.xml entries in Chapter 7 for details of how to format shortcuts. Table C.14 describes <ftp-extension-map-changes> . This container tag specifies a change to the FTPExtensionMap.txt file. (This file defines whether the file is downloaded/uploaded to an FTP server as ASCII or binary.) Table C.14. MXI File: <ftp-extension-map-changes> | Attributes | Contents | Container | Example | | None | May contain one <ftp extension insert> tag; and/or one <ftp-extension- remove> tag. | <configuration changes> | <ftp-extension-map-changes> <ftp-extension-insert> <ftp-extension-remove /> </ ftp-extension-map-changes > | Table C.15 describes < ftp-extension-remove /> . This tag specifies the extension to be removed from the SourceFormat.txt file. Table C.15. MXI File: < ftp-extension-remove /> | Attributes | Contents | Container | Examples | | extension The file extension, such as GIF or JPG , to be removed. | None (empty tag) | <ftp-extension map-changes> | <ftp-extension-remove extension="JPG" /> | Table C.16 describes <ftp-extension-insert /> . This tag specifies a change to the FTPExtensionMap.txt file. Table C.16. MXI File: <ftp-extension-insert /> | Attributes | Contents | Container | Examples | | extension The file extension, tag) such as GIF or JPG. type Format to use when uploading. Accepted values are ASCII and Binary . mac-creator Macintosh creator code. If you don't know the code, use ???? . mac-file-type If you don't know this, use ???? | None (empty | <ftp-extension map-changes> | <ftp-extension-insert extension="GIF" type="ASCII" mac- creator="MKBY" mac-file- type="GIFf"> | The following is an alternate blank MXI template file, including many more specialized options that can be used in place of Blank.mxi. <!remove this comment for each tag attribute, assign a value or remove the attribute> <!remove this comment not all tags will be required for all extensions some tags may be present more than once for a given extension> <macromedia-extension name version type requires-restart> <products> <product name version primary required /> </products> <author name /> <description> <![CDATA[ <!remove this comment and add your descriptive text here> ]]> </description> <ui-access> <![CDATA[ <!remove this comment and add user access information here> ]]> </ui-access> <files> <file name destination platform shared systemfile winextension/> </files> <configuration-changes> <menu-remove id /> <menu-insert insertAfter insertBefore appendTo prependTo skipSeparator> <menu name id platform> <menuitem name id key platform file command enabled checked dynamic arguments /> </menu> </menu-insert> <shortcut-remove id> <shortcut-insert listId> <shortcut key id command file platform /> </shortcut-insert> <ftp-extension-map-changes> <ftp-extension-insert extension type mac-creator macfile-type /> <ftp-extension-remove extension /> </ftp-extension-map-changes> </configuration-changes> </macromedia-extension> note You can download the alternate blank template shown above from the book's companion web site, www.newriders.com.
Creating a Simple MXI: Set Page Properties Behavior With all the above resources to work from, creating this installation file shouldn't be too difficult. An example of what the completed MXI file might look like is shown as follows. In particular, take note of the following: -
<product> specification Unless you're sure an extension will work with a particular version of Dreamweaver or UltraDev, don't specify it here. -
<file> Each file in the extension requires its own entry here. The destination attribute determines where the file will be installed. It's not case-sensitive, but must begin with $dreamweaver . <macromedia-extension name="Set Page Properties" version="1.0" type="behavior" requires-restart="true"> <products> <product name="Dreamweaver" version="6" primary="true" /> </products> <author name="RocketLaura" /> <description> <![CDATA[ Create a JavaScript that lets page visitors change page and text colors.<br> All default page, text, link colors can be specified. ]]> </description> <ui-access> <![CDATA[ Access from the Behaviors menu. ]]> </ui-access> <files> <file name="Set Page Properties.htm" destination="$dreamweaver/configuration/ behaviors/actions" /> <file name="Set Page Properties.js" destination="$dreamweaver/configuration/ behaviors/actions" /> </files> </macromedia-extension> Creating an MXI for a Multifile Extension: Custom Horizontal Rule Object An example of what the MXI file for this extension might look like is shown as follows. In particular, note the various <file> entries. Note the following: -
files Every file in the extension must be given an entry, including each GIF. -
filenames Because the files for this extension have collected into various subfolders for the packaging process, we must specify a relative pathname for each. (The pathname must be relative to the installation file. These names assume that the MXI file is being stored at the root level of the collection folder.) -
destinations This extension requires a custom folder (in the Objects folder). By specifying a folder in the destination path that doesn't yet exist in the user's Configuration folder, you instruct the installer to create that folder. <macromedia-extension name="Custom Horizontal Rule" version="1.0" type="object" requires-restart="true"> <products> <product name="Dreamweaver" version="4" primary="true" required="true" /> </products> <author name="RocketLaura" /> <description> <![CDATA[ This object inserts a horizonatal rule, with an insertion dialog box for setting attributes, and an inspector that displays the color attribute. <br><br> ]]> </description> <ui-access> <![CDATA[ Access from the My Stuff category of the Insert bar. ]]> </ui-access> <files> <file name="objects/Custom HR.htm" destination="$dreamweaver/configuration/objects/My Stuff" /> <file name="objects/Custom HR.js" destination="$dreamweaver/configuration/objects/My Stuff" /> <file name="inspectors/Custom HR.htm" destination="$dreamweaver/configuration/inspectors" /> <file name="inspectors/customhr.gif" destination="$dreamweaver/configuration/inspectors" /> </files> </macromedia-extension> Creating an MXI for an Extension with Menu Changes: Table Helper Floating Panel An example of what the installer file for the Table Helper might look like is shown as follows. In particular, pay attention to the following: -
<configuration-changes> Because this extension changes the menus, you must include this set of tags. -
<menu-insert> The alternate blank MXI template (shown in the section titled "The Structure of an MXI File") shows all the options you have for specifying exactly where your new menuitem should go. The MXI shown for Table Helper is set to insert the new menuitem after the existing menu entry that has the ID value of DWMenu_Window_RestoreAll . -
<menuitem> This line is a re-creation of the syntax you originally developed for Table Helper. It will be placed exactly as it appears here, in the user's menus.xml file. Again, the alternate blank template shown previously shows the various options you could use in this line. <macromedia-extension name="Table Helper" version="1.0" type="floater" requires-restart="true"> <products> <product name="Dreamweaver" version="4" primary="true"/> <product name="UltraDev"/> </products> <author name="RocketLaura" /> <description> <![CDATA[ This panel provides comprehensive information about the cell dimensions and structure of a selected table. ]]> </description> <ui-access> <![CDATA[ Access from the 'Table Helper' entry in the Window menu. ]]> </ui-access> <files> <file name="TableHelper.htm" destination="$dreamweaver/configuration/floaters" / > </files> <configuration-changes> <menu-insert insertAfter="DWMenu_Window_RestoreAll"> <menuitem name="Table Helper" id="RocketLaura_TableHelper_Floater" command="dw.toggleFloater('TableHelper')" enabled="true" checked="dw.getFloaterVisibility( 'TableHelper')" /> </menu-insert> </configuration-changes> </macromedia-extension> note It's important to understand what's happening in the MXI file. If you don't want to spend time hand-coding every MXI file you need, try out Public Domain's MXI File Creator extension, available from the Macromedia Dreamweaver Exchange. This extension creates a Dreamweaver command that allows you to enter all the relevant information for your MXI file (in plain old English) and then writes the MXI file for you.
Task 3: Package the Extension Into an MXP (Installer) File After you've assembled all your bits and pieces into the folder you've designated as your staging area, and you've created the MXI file with instructions for turning those pieces into an extension, it's time to create the installer package. Follow these steps: -
Launch the Macromedia Extension Manager. -
Go to File > Package Extension. -
In the dialog box that appears, select your MXI file. -
Click Open. -
Assign a name to the MXP file. Make sure the name contains no special characters or spaces, and ends with the .mxp extension. -
Click Save. If there's any problem with the MXI file, you'll get an explanatory error message. (Usually, errors have to do with incorrect syntax or incorrectly referenced extension files.) Leave the Extension Manager, remedy the problem, and try again. If everything is correctly set up, you'll get a lovely message telling you the file was created successfully. Congratulations! You made your first installer file. Figure C.2 shows the completed installer files for the Set Page Properties, Flash Detector, and Table Helper extensions. Figure C.2. The completed MXP files for your three sample extensions.   |
