Welcome to the third and final installment of this three part series on writing and packaging JSFL commands. In this last post I will go over how to update our Invisible Button command so that we can use a relative installation path to locate our XML form. I’ll also go over how to create an installer file (MXI) and package it (MXP) so that you can distribute your commands.

We have three things to accomplish in this tutorial:

1. Modify the JSFL command to use a relative installation path to find the XML UI dialog
2. Create an MXI file with instructions on how to package our command
3. Package our extension using Macromedia’s Extension Manager

Step 1

Let’s start by opening up our “Invisible Button.jsfl” file from your “My Commands” folder you have on your desktop.

If you haven’t read the first two parts of this series you’ll want to do that before continuing. If not, you’ll at least want to download the source files from part II as a starting point.

The fl object contains a property called configURI. This property contains the file URI for the location of the current user’s Flash configuration. Each machine user will have their own unique URI which in Windows will typically be something similar to “file:///C|/Documents and Settings/Username/Local Settings/Application Data/Macromedia/Flash 8/en/Configuration/.” Inside this folder you will find the folder “Commands” which contains files for any custom commands you might have installed already. This is the folder we’ll be targeting when we create our package so let’s change the xmlPath() to point to this folder when looking for the “Invisible Button.xml” file we created. To do that, simply change the beginning of your “Invisible Button.jsfl” script to read as follows:

var flash_doc = fl.getDocumentDOM();
var flash_lib = flash_doc.library;
var flash_tl  = flash_doc.getTimeline();
var flash_w = flash_doc.width;
var flash_h = flash_doc.height;

fl.trace(fl.configURI);
var result = flash_doc.xmlPanel(fl.configURI + "/Commands/Invisible Button.xml");

We’ve added the trace function so that we can find out the exact folder we are targeting on your machine. This line can be removed after you have found your folder. Create a new empty flash document so that we can test this modified command because the commands menu is only available when an FLA is open and in focus.

If you ran the command two things should have happened. First you should have gotten an error like this:

Second, the output window should have displayed and printed the fl.configURI for us to examine. The error was expected because we do not have our XML file located in this new folder. The trace was to find the correct location to copy our XML file to. Read the path printed in the output window and go to your OS and open up that folder through any preferred method. Once you have that folder open, look for the folder called commands and open that folder. Copy only the “Invisible Button.xml” file into that Commands folder and run your command again. This time you should not get an error and the command should function as expected. You can go ahead and delete the trace at this point, we won’t be needing it any longer.

Step 2

Now that we have the JSFL script and XML file complete we can create our installation file. Using your favorite text or XML editor, create a new document in your “My Commands” folder on your desktop called “Invisible Button.mxi.” Below is a basic template that you can copy into this file.

<macromedia-extension
  type="flash command"
  version="1.0.0"
  requires-restart="false"
  name="Invisible Button">

  <!– children will go here –>

</macromedia-extension>

This is a starting point for our MXI that we’ll build on. You’ll notice that the root node, macromedia-extension, has a number of settable attributes. The first attribute “type” defines the type of extension we are adding. For a complete list of extension types and further documentation on extensions read http://download.macromedia.com/pub/exchange/mxi_file_format.pdf. The second attribute “version” defines the version number for our extension. Requires-restart indicates whether Flash needs to be restarted after the installation and it doesn’t for a command. You can look up other types of extensions for their requirements. The last attribute is “name” and that’s the name of our command.

Inside the <macromedia-extension> node are a few child nodes that define information that is displayed inside of Extension Manager after the extension has been installed. The first node <author> defines the author’s name as displayed inside of extension manager.

  <author name="James O’Reilly" />

The second node product defines the product that the extension will be installed to. This is because the MXI format is used across many of the Macromedia products and Extension Manager needs to know which one to install to. Extension manager will install to the version indicated or later.

  <products>
    <product name="Flash" version="8" primary="true" />
  </products>

The next node defines the description of the product.

  <description>
    <![CDATA[Creates an invisible button and places it on the document in a new layer named “button” and automatically assigned a getURL call.  The button is created as a symbol called “invisible”.]]>
  </description>

The next node defines how the extention is accessed from within the product. In our example the user would need to go to the commands menu and select the command from there. A common notation for that is “Commands > Invisible Button” which is what we’ll use. You can type anything you see fit for your situation.

  <ui-access>
    <![CDATA[Commands > Invisible Button]]>
  </ui-access>

The next node defines any legal information you wish to display and will be prompted for the user to accept before installation.

  <license-agreement>
    <![CDATA[CDATA[James O’Reilly provides this extension ‘as is’ without any warranty of any kind as to the suitability of the extension for the licensees intended purpose. All risk as to the performance of the extension and it’s contents are the sole responsibility of you, the licensee.]]>
  </license-agreement>

Lastly is the node to define all of the files that make up this extension. The “source” attribute defines the location of the file and the “destination” attribute defines the location of the installation. We want to install to the Commands folder we found earlier and we can target that folder like this “$Flash\commands”. We have two files that make up our installation so we need to include both.

  <files>
    <file source="Invisible Button.jsfl" destination="$Flashcommands" />
    <file source="Invisible Button.xml" destination="$Flashcommands" />
  </files>

Step 3

After you’ve finished creating your MXI file open up Extension Manager. If your installation did not come with this program, you can download it for free from Adobe’s website here http://www.adobe.com/exchange/em_download/. From inside Extension manager select “File > Package Extension…” and browse to the “Invisible Button.mxi” file we just created. When prompted save the “Invisible Button.mxp” file to the same folder.

To install your new extension select “File > Install Extension…” from Extension Manager’s menu. Browse to the newly created “Invisible Button.mxp”. You will be prompted with a legal agreement and you will notice if you scroll down to the bottom the additional legal information you’ve added in your MXI file. Click OK to install and you’re done. You’ll see your new extension added to the list of Flash extensions.

To distribute this extension simply give out the MXP file as that file contains all of the necessary files to install the extension.

Open Flash, create a new document and test your new command. From here, think about commands that might make your life easier and write your own.

Download Final source code

This entry was posted on Thursday, August 24th, 2006 at 1:06 pm and is filed under Extending Flash. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.