Macros

Macros provide an external plug-in interface, to extend the functionality of Designer. For example, you can run a macro to rename a field and update all associated script references, or to find scripts that consist entirely of comments.

Note: You should only run a macro if you trust the author of the script.

A macro is a JavaScript file (JS). You create JavaScript files in a JavaScript editor and run the scripts in Designer. The JavaScript in the macro has full access to the template model. In addition to the template DOM, there is an object in the root namespace called designer. The designer object provides methods that you can use to communicate directly with Designer. For example, one method allows you to launch a SWF dialog box and exchange strings with it, which allows you to build a custom user interface.

For more information about available scripting methods, see the Scripting Reference.

To set up macros for use in Designer, you create a subfolder structure for JavaScript files in the Designer installation folder, and run the JavaScript files from the Macros menu (Tools > Macros).

To set up macros for use in Designer

  1. Do one of the following actions:

    • For common macros (all languages), in the Designer installation folder, create a subfolder called macros. For example, <DesignerInstallationFolder>\macros.

    • For language specific macros, in the Designer installation folder, create a subfolder for each language (locale), and then create a macros folder in each locale folder. For example, <DesignerInstallationFolder>\EN\macros.

  2. In each macros folder, create one or more subfolders for JavaScript (JS) and macro.xml files.

  3. Save JavaScript and macro.xml files to the appropriate subfolders. Place any SWF files used by the macro JavaScript files in the same subfolder.

  4. In Designer, click Tools > Macros. The macros (common and language specific) are listed on the Macros menu.

About macro.xml configuration files

You create an macro.xml configuration file to rename the command that appears on the Macros menu for each JavaScript file in a subfolder. You add one macro.xml file to each subfolder containing one or more JavaScript files.

Notice the label and script tags in the following example macro.xml file. The label tag encloses the name of the command (Merge) that appears on the Macros menu. The script tag encloses the name of the associated JavaScript file (mergenodes.js).

Example macro.xml file:

<?xml version="1.0" encoding="UTF-8"?> 
<designerMacros> 
<!-- one or more macros that are in the same directory can be specified in the same macro.xml config file --> 
<macro> 
    <!-- used as menu command text --> 
    <label>Merge</label> 
    <!-- A macro key can refer to only one script file --> 
    <script>mergenodes.js</script> 
</macro> 
</designerMacros>

Using macro.xml configuration files is optional. When Designer refreshes the list of macros, it searches the macros subfolders for macro.xml files. If Designer does not locate a macro.xml file in a subfolder, the names of the JavaScript files appear on the Macros menu.

Organizing the macros subfolder

Create a least one subfolder under the macros folder to contain your JavaScript files. If you save JavaScript files directly in the macros folder, they do not appear on the Macros menu in Designer.

You can organize macros subfolders different ways. The method you choose, depends on your needs. Consider the number of JavaScript files you have, the number of macro.xml files to create, and the order of commands on the Macros menu.

One way to organize the macros subfolders is to save all JavaScript files in one subfolder. This way, you use one macro.xml file to specify the names of all JavaScript files in the folder, and names of the associated Macros menu commands. The order of the commands on the Macros menu, is the same as the order of macros listed in the macro.xml file.

Example macro.xml file containing multiple macros:

<?xml version="1.0" encoding="UTF-8"?> 
<designerMacros> 
<macro> 
    <label>Get Designer Locale</label> 
    <!-- Description - Get Designer locale --> 
    <script>getLocale.js</script> 
</macro> 
<macro> 
    <label>Hello World</label> 
    <!-- Description - Display Hello World --> 
    <script>helloWorld.js</script> 
</macro> 
<macro> 
    <label>Highlight Text</label> 
    <!-- Description - Highlight text areas --> 
    <script>HighlightFields.js</script> 
</macro> 
<macro> 
    <label>Refactor</label> 
    <!-- Description - Refactor --> 
    <script>refactor.js</script> 
</macro> 
<macro> 
    <label>Show Flex Sample</label> 
    <!-- Description - Show Flex Sample --> 
    <script>showFlexSample.js</script> 
</macro> 
</designerMacros>

Another way to organize the macros subfolders is to save JavaScript files in separate subfolders. You use a macro.xml file in each subfolder to specify the name of the JavaScript files, and name the related Macros menu commands. The order of the commands on the Macros menu, is the same as the order of subfolders and the macros listed in each macro.xml file.

Keep in mind that all the subfolders you create for JavaScript files must be a child of the macros parent folder (macros\MyMacros). Designer does not scan subfolders below the level of the first subfolder.After you add a JavaScript file to a macros subfolder, the name of the file appears under the Macros command on the Tools menu. If you want to display a name other than the JavaScript filename, you can create an XML configuration file named macro.xml to change the name.

Localizing macros

You create a subfolder structure in the Designer installation folder for the JavaScript files associated with macros. The subfolders structure you create depends on whether you plan to localize macros or not.

If you do not need to localize macros, because they are common to all languages, you create a subfolder named macros in the Designer installation folder. For example, c:\program files\Adobe\Designer\macros\. You then create one or more subfolders in the macros subfolder for the JavaScript files you want to run. You can create one subfolder for all JavaScript files or create a separate subfolder for each JavaScript file. Designer loads the JavaScript files in these subfolders, regardless of the locale option selected in the Form Locale list (Form Properties dialog box > Defaults panel).

If you need to localize macros, because they are locale (language) specific, you create a subfolder in the Designer installation folder for each locale. You then create a macros subfolder in each locale subfolder, and create one or more subfolders in the locale subfolder for the Javascript files. For example: c:\program files\Adobe\Designer\EN\macros\. Designer loads the JavaScript files in these folders based on Designer's application language.

Macro Logging

If you are unsure which macros Designer is loading, you can check the macros log file.

Designer creates a log file called MacrosLog.log in the Designer application data folder located here: C:\Documents and Settings\<username>\Application Data\Adobe\Designer\<Designer version number>.

The MacrosLog.log file lists the macros loaded in Designer.