Dolly is a Java application for generating new InDesign plug-in projects. It is included with the Plug-in SDK. Dolly has a simple user interface, but it can also be used from the command line. User interface version of Dolly has a limited amount of settings that you can adjust. Using command line tool opens up a bigger range of options via manipulating the XML document directly. You can create many different input files and use them as templates for your plug-in development. In this blog post, I’ll show you how to use the command line to generate new InDesign plug-in projects.

Running Dolly

First, we’ll launch Dolly from the command line. Dolly is located inside the plug-in SDK: /devtools/sdktools/dollyxs.

We’ll need to open command prompt or terminal and set the current directory to /devtools/sdktools/dollyxs. Let’s first try running Dolly with user interface option turned on.

Windows: DollyXs.bat win-input.xml
Mac: DollyXs.sh mac-input.xml

You should be able to see the UI for Dolly:

The input files win-input.xml and mac-input.xml are the default XML documents that Dolly uses to generate projects. They define the properties of your new plug-in, such as whether you’re creating a model or a UI plug-in or if it is for InDesign or InCopy. It is not necessary to provide these files explicitly when running Dolly with UI.
Now close Dolly and try launching it with user interface disabled. To do that we’ll use the -q flag.

Windows: DollyXs.bat -q win-input.xml
Mac: DollyXs.sh -q mac-input.xml

If we look at mac-project-dir or win-project-dir attributes in the XML document we’ll see the location where the project was created. If you haven’t used Dolly before, the chance is that you got an error ‘Failed to create output file… ‘ when trying to create a project. It is because your mac-project-dir or win-project-dir point to an invalid location, like:

mac-project-dir="/id8sdk/build/mac/prj"

In the next part, we’ll try and use our own XML input file to generate projects using Dolly command line tool.

Creating custom input file

Copy win-input.xml or mac-input.xml and rename it myInputFile.xml. This is going to be the file we’ll be working on.

We’ll now define some general information about our plugin. Open myInputFile.xml and change author field to your name. Edit the value of long-name and change it to “MyPlugin”.

author="Alex"
long-name="MyPlugin"

We’ll also update the location of our project to something more suitable. That should fix any errors that we might have encountered before. Change mac-project-dir to /build/mac/prj and win-project-dir to /build/win/prj.

mac-project-dir="/Users/Alex/Desktop/Adobe_InDesign_CS6_Plugin_SDK/build/mac/prj"
win-project-dir="/Users/Alex/Desktop/Adobe_InDesign_CS6_Plugin_SDK/build/win/prj"

Dolly is going to generate some .cpp and header files for us. Let’s put them all in the same place so they are easily accessible. We can do this by assigning the same path to mac-id-header-dir, mac-source-dir, win-id-header-dir and win-source-dir. Make sure to use backslash for Windows paths or Dolly will throw an error when generating the project.

mac-id-header-dir="../../../source/sdksamples/myplugin"
mac-source-dir="../../../source/sdksamples/myplugin"
win-id-header-dir="..\..\..\source\sdksamples\myplugin"
win-source-dir="..\..\..\source\sdksamples\myplugin"

Even though we’re defining paths for source and header files twice, Dolly will create just one copy of each file. If you’re using Windows, Dolly will not create files in directories defined for Mac and vice versa.

The last changes we’re going to make are prefix-id and short-name. We’ll also set the type of our plug-in. The prefix-id of a plug-in is the ID value that InDesign will use to identify our plug-in. It is used to determine IDs of the boss classes, implementations and interfaces in our project. It must be a hexadecimal value. For the purpose of this tutorial, let’s set it to “0xef190”. For your own plug-ins, you need to obtain a unique prefix-id from Adobe Developers Connection.

Change the value of short-name to “MP”, short for MyPlugin. This attribute is used to prefix project file names for your plug-in. Therefore, it is advisable to keep it short.

prefix-id="0xef190"
short-name="MP"

We’re going to set the type of our plug-in to kUIPlugIn. Make sure the letter I is capital or Dolly will create a model plug-in instead.

plugin-type="kUIPlugIn"

Generating MyPlugin

It’s time to use our XML file to generate MyPlugin project with Dolly.

Windows: DollyXs.bat -q myInputFile.xml
Mac: DollyXs.sh -q myInputFile.xml

Once we run the command, Dolly is going to generate source files in /source/sdksamples/myplugin/ as we specified in our XML file.

Same with the project files. Our Xcode MyPlugin project will be generated in /build/mac/prj and Visual Studio project will be in /build/win/prj .

Open either MyPlugin.xcodeproj or MyPlugin.sln and you’re done! You’ve successfully created an InDesign plug-in using Dolly.

Find out more

If you would like to know more about manipulating the XML input file or Dolly in general, be sure to read the Readme.txt located in /devtools/sdktools/dollyxs/. You can find more information on InDesign Plugin development in the getting-started.pdf in /docs/guides/.

We welcome questions and comments!

myInputFile.xml

<?xml version="1.0" encoding="UTF-8"?>
<code

</code>


Benefits of using EVE

• Updating dialogs by adding and removing widgets is made easier because the layout of all widgets is adjusted for you.
• Where text is different sizes on different operating systems you don’t have to worry about calculating extra whitespace.
• English dialogs can be smaller because you don’t need to leave room for anticipated localised text, so your dialogs look good in all languages.
• EVE automatically resizes text, buttons, checkboxes, radio buttons and drop-down lists so you needn’t worry about text being clipped.

A quick introduction to EVE

In order to use EVE widgets in your dialog definitions you’ll need to add an include to your FR file.

#include "EveInfo.fh"

This file is a very useful resource since it lists all of the EVE widgets which are available out of the box, so do have a look inside.

In order to have your dialog use EVE you’ll need to add WidgetEveInfo to its type definition.


type BscDlgDialogBoss(kViewRsrcType) : DialogBoss(ClassID = kBscDlgDialogBoss)
{
   WidgetEveInfo;
};


Finally you can change your dialog definition to use EVE by changing it to use EVE widgets and by adding the necessary EVE layout constants to the dialog itself (since you’ve now made the dialog an EVE dialog by adding WidgetEveInfo to its type definition).

Since all dialogs have an OK and Cancel button and some other content, here’s a complete dialog definition that uses EVE to layout an OK and Cancel button.


resource BscDlgDialogBoss (kSDKDefDialogResourceID + index_enUS)
{
   __FILE__, __LINE__,
   kBscDlgDialogWidgetID, // WidgetID
   kPMRsrcID_None, // RsrcID
   kBindNone, // Binding
   Frame(0,0,388,112) // Frame (l,t,r,b)
   kTrue, kTrue, // Visible, Enabled
   kBscDlgDialogTitleKey, // Dialog name
   {
      // Add dialog content here (like EVEStaticTextWidget..)

   },
   
   kEVEArrangeChildrenInRow | kEVESmallMargin,
};


If you are familiar with InDesign plug-in development you’ll notice that the general format of the dialog definition is the same as usual except for some EVE layout additions and the use of widget names prefixed with EVE.

How do I convert my existing dialogs to use EVE?

The InDesign plug-in SDK includes an EVEConverter tool which enables you to very quickly EVE-ize your dialog definitions however it’s output is less than optimal. Be aware that the tool will also convert any panel definitions to use EVE so you should keep a backup copy of your original FR file so that you can replace the EVE-ized panel definition with your original non-EVE panel definition. The EVEConverter tool is a great first step to get a feel for EVE and how to use it.

Once you are better acquainted with EVE it becomes easier to hand craft your conversions or do some of them by hand. It all depends on how complex your dialogs are and if you are using any custom widgets. As a rule of thumb you might use the EVE converter first, then go over the output by hand to remove any excess spacer widgets or superfluous generic panel definitions.

The plug-in SDK also includes a porting guide which includes a chapter on using EVE. You can obtain the plug-in SDK from here http://www.adobe.com/devnet/indesign/sdk.html.

The code below works out of the box so you can copy and paste as much as you please.

#include "IScriptManager.h"
#include "IScriptEngine.h"
#include "IScriptRunner.h"
#include "IScriptUtils.h"
#include "JavaScriptID.h"

RunScriptParams params(scriptRunner);
scriptRunner->RunScript("alert('hello, world!');", params);

The above code uses JavaScript but you may use any script manager you like, including kAppleScriptMgrBoss for AppleScript and kOLEAutomationMgrBoss for Visual Basic. For a complete list of available scripting managers see ‘Script managers’ in chapter 10 ‘Scriptable Plug-in Fundamentals’ of the Programming Guide Volume 1 included in the plug-in SDK (available at http://www.adobe.com/devnet/indesign/sdk.html).

This posting highlights two samples that demonstrate two approaches — scripting and plug-in — to using Flex to create user interfaces for InDesign CS4. Each approach demonstrates how to achieve the following:

1. Locate an SWF (binary Flash file) relative to a script or plug-in.
2. Load the SWF in an existing InDesign user-interface widget.
3. Provide a way to call InDesign from the SWF’s ActionScript code. (You cannot directly target InDesign CS4′s scripting DOM with ActionScript.)
4. Provide a way to call ActionScript from InDesign code.

Scripting Approach

The scripting approach combines InDesign JavaScript (and its ScriptUI library) with Flash SWF. This was demonstrated originally in the InDesign CS4 Products SDK by the FlexUIBasicScriptUI sample. That sample shows how to create a panel with Flex and ScriptUI. Perhaps more than anything, it highlights the panel’s need to receive notifications from the application when relevant data changes. Since these notifications do not exist in the scripting DOM, I recommend using this approach for dialogs, which do not require notifications.

To back up the claim that this is a good technique for dialogs, and to demonstrate how you would do this, I implemented a new sample. It is demonstrated in the following video, which shows a simple dialog implemented with Flex and scripting. Eventually, we will add this sample to the SDK and maintain it there, but for your convenience, I have added rough and ready (CS4-compatible) sample files.

To run the sample, copy FlexScriptUIDialog.swf and FlexScriptUIDialog.jsx to your “Startup Scripts” folder (<InDesign>/Scripts/Startup Scripts). Note: <InDesign> is the InDesign application folder.

For details, see the comments in the included source files.

For information on how to compile the SWF, see Building Flex Files below.

Plug-In Approach

The plug-in approach can be used to implement more sophisticated user interfaces. The main difference from the scripting approach is that you can create a panel that behaves like a normal InDesign panel. (Script UI panels have a different appearance and do not behave like InDesign panels.) This includes the ability to watch for changes in a document and update the panel accordingly.

The InDesign CS4 Products SDK includes the FlexUIStroke sample. This sample demonstrates combining a C++ plug-in development with Flex. The plug-in portion provides the following:

• A native panel containing a Flash player widget
• An observer that watches for changes to the stroke weight in the current selection and updates the panel accordingly
• Code that alters the stroke weight in the InDesign object model

The following video demonstrates what is possible using the plug-in approach.

For details on this panel, see the documentation and source code in the InDesign CS4 Products SDK. Each sample is documented in the API Reference. Click on Samples > All Samples >, then select the FlexUIStroke sample.

For information on how to compile the SWF, see Building Flex Files below.

You will find the plug-in in one of the following locations (depending on your platform) in the SDK:

• <SDK>/build/win/prj/FlexUIStroke.sdk.vcproj
• <SDK>/build/mac/prj/FlexUIStroke.sdk.xcodeproj

Building Flex Files

To import and compile either Flex project using FlexBuilder 3, follow these steps :

1. Run Flex Builder 3.
2. Choose File > Import > Flex Project…
3. Select the Project Folder radio button
4. Browse to the Flex project folder (this folder should contain the .project file).
5. Uncheck the “Use default location” checkbox. This allows you to import the project in its current location.
6. Click Finish.

If you do not have FlexBuilder, it is possible to compile these mxml files using the free Flex SDK:

• mxmlc <…>/flexscriptuidialog/FlexScriptUIDialog.mxml
• mxmlc <…>/flexuistroke/flexuistrokemxml/src/flexuistroke.mxml

If you are not familiar with preflight, please first watch this introductory video:
http://www.adobe.com/designcenter/indesign/articles/lrvid4025_id.html).

This post will demonstrate how to interact with the preflight system using JavaScript. For illustration purposes, we show how to configure preflight to raise an error if the page size is something other than letter size (8.5”X 11”). We briefly highlight how it’s done in the UI, then show how to achieve the same results through scripting.

Importing a Preflight Profile

You can import a preflight profile through the Preflight Panel in InDesign: choose Preflight Panel > Define Profiles, then choose Load Profile from the drop-down menu in the Preflight Profiles window.

You also can load a profile with scripting.  The following JavaScript imports a profile called Test.idpp:

It’s easier to create profiles using the Preflight Panel than with scripting.  One workflow would be to create all profiles in the UI, export them to files, and import them using scripting.  This approach avoids the challenges involved with manually adding rules via JavaScript.

Creating a Profile

To create a preflight profile from the Preflight Panel, choose Preflight Panel > Define Profiles, then choose the plus sign (+) to add a new preflight profile.  Name the profile and fill in all data values for the available rules.

You also can create a profile with scripting.  The following adds a single profile called Test:

Preflight-profile names must be unique.  If the script above is executed more than once within the same InDesign instance, an error is raised, indicating that a profile with that name already exists.  To avoid this, either access the existing profile using app.preflightProfiles.itemByName(), or check to see if a profile exists and remove it as follows:

Adding Rules

A preflight profile contains a mutually exclusive set of rules.  To add a rule to a profile, follow these steps:

1. Add a rule to a profile by name.
2. Set the rule’s data values.
3. Set the rule’s reporting state.

Each step is described below.

1. Add a rule to a profile by name.Rules are added by name.   For information on rule names, see “Available Rules.”  The following adds the ADBE_PageSizeOrientation rule to the profile:

2. Set the rule’s data values.Many, but not all, rules have data properties.  For a complete specification of the rules available with InDesign CS4, see “Available Rules.”  The ADBE_PageSizeOrientation rule contains particular data properties that allow you to specify a page size.  The following sets the acceptable page height and width, a tolerance (fudge factor), and an option for handling page orientation:

3. Set the rule’s reporting state.This is done using the rule’s flag property.  There are several choices (disabled, information, warning, and error), controlled by the PreflightRuleFlag enumeration:

Processing a Profile

In the desktop version of InDesign, preflight errors are reported in the UI.  In scripting (especially for InDesign Server), the errors are generated on demand.  The following script processes an InDesign document.  If there are errors, it writes the results to a new PDF file.  For an example of the output, see the figure below the example.

If you would rather produce a text file, simply name your output file with a .txt extension.
Alternately, you may prefer to iterate the errors yourself.  The following demonstrates how to access the errors array:

Custom Rules

It is not possible to create custom rules through the Preflight Panel or scripting; however, this can be done through a C++ plug-in.  The InDesign CS4 Products SDK contains a sample, PreflightRule, that demonstrates how to add custom rules with a plug-in.

Available Rules

ADBE_BlankPages

ADBE_BleedSlug

ADBE_BleedTrimHazard

ADBE_Colorspace

ADBE_CrossReferences

ADBE_FontUsage

ADBE_ImageColorManagement

ADBE_ImageResolution

ADBE_PageCount

ADBE_PageSizeOrientation

ADBE_ScaledGraphics

ADBE_ScaledType

ADBE_SmallText

ADBE_SpotColorSetup

ADBE_StrokeRequirements

ADBE_TextOverrides

ADBE_TransparencyBlending

When it comes to schemas and validation, there are two types of IDML files:

• There are many single-file variants (snippets, assignments, ICML, etc.). These files need to be validated with the snippet schema.
• Packages are multi-file ZIP archives that represent an entire InDesign document. Packages need to be validated with the package schema.
  For more information on IDML files see the “IDML File Types” post.

Generating Schema Files

IDML can be extended by the scripting support in third-party plug-ins. For this reason, the schema used for validation must match a plug-in configuration. Rather than providing a static schema, InDesign provides a means to create a schema from your plug-in configuration. The following sample code demonstrates producing snippet and package schemas with JavaScript.

This snippet schema is used to validate all single-file variants of IDML. It comprises two files:

The package schema comprises one shared file and schema file for each type of XML file that can appear in an IDML package:

Finding Errors in IDML

For demonstration purposes, we need files that contain errors. Imagine the following IDML fragment in both a snippet file (test.idms) and package (test.idml) file. The IDML contains four fairly obvious errors; try to spot all four.

You may have found it difficult to spot all four errors. Imagine if this was buried in a huge XML file. Instead of trying to find errors ourselves, we use schema validation.

Schema Validation Basics

A RelaxNG schema can be used to verify the structural correctness of a document. It checks to make sure all XML nodes (elements, attributes, text data, etc.) are used at the right places in the document. It detects any unknown or unexpected nodes and ensures that required nodes are present.

InDesign’s RelaxNG schemas can be used to check the structure of a document; however, it does not check the content of these nodes. For example, it doesn’t check that all IDML references exist. It’s possible to do some non-RelaxNG-based error detection. This is discussed in “Additional Error Detection” below.

You can validate IDML files with any software that supports the compact form of RelaxNG. For snippet files, this is relatively straightforward: it amounts to pointing whatever validation engine you are using to the IDMarkupLanguage.rnc file (which includes the datatyps.rnc file).

Validating packages is more complex; there are two difficulties:

• Packages are ZIP archives, and most RelaxNG validation engines don’t deal with ZIP files.
• An IDML package comprises many XML files. The package schema comprises several schema files: there is one schema for each type of file that can appear in an IDML file. To validate a package, you need to match each XML file with its appropriate schema file.

Validating with IDMLTools

The InDesign CS4 Products SDK includes a Java package called IDMLTools. This package contains a validation application based on the Jing RelaxNG Validator, which handles both snippets and package files. It’s especially handy for package files, because it unzips the files and matches XML files to the appropriate schema file.
For information about setting up IDMLTools, see the IDML ReadMe. This amounts to the following:

• Add the IDMLTOOLS_HOME environment variable. This should contain the path to your IDMLTools folder. (Do not terminate with a trailing \ or /.)
• Add /bin to your search PATH environment variable. This provides easy access to the validation script.

Once set up, you can validate files by running the appropriate platform script, validate.bat on Windows and validate.sh on Mac OS. These scripts set the appropriate Java classpath and run the validation application. The validation application can be used to validate both types of IDML files (snippets and package files). Running the platform scripts with no arguments produces the following usage message:

Validator SchemaPath PackagePath [PackagePath...]

This means you validate by specifying a path to the schema folder, followed by paths to one or more package files that you want to validate.

Validating a Snippet

To validate the test.idms snippet, specify the path to the snippet schema, followed by the path to the actual snippet:

validate.bat “c:\idml-schema\snippet” test.idms

The validation application writes errors to standard error. Here are the results from validating test.idms:

Test.idms:143:10: error: required attributes missing
Test.idms:144:527: error: attribute “foo” not allowed at this point; ignored
Test.idms:145:14: error: element “RectData” not allowed in this context
Test.idms:146:15: error: element “Propertie” not allowed in this context

Validating a Package

To validate a package specify the path to the package schema, followed by the path to the IDML file:

validate.bat “c:\idml-schema\package” test.idml

The validation application unzips the archive to a temporary directory, validates each file against the appropriate schema file, then writes any errors to standard error.

Here are the results written when validating test.idml:

Spreads\Spread_ubd.xml:3:245: error: required attributes missing
Spreads\Spread_ubd.xml:27:527: error: attribute “foo” not allowed at this point; ignored
Spreads\Spread_ubd.xml:28:14: error: unknown element “RectData”
Spreads\Spread_ubd.xml:29:15: error: unknown element “Propertie”

Notice that the XML file containing the error is reported on the left. In this case, the error is in the Spread_ubd.xml file. Because package validation deals with multiple XML files in one pass, error results can come from several files.

Interpreting the Results

From the results above, we can deduce the four errors:

1. The Spread element is missing a required attribute. Unfortunately, Jing does not report which attribute is missing, but it is easy enough to look at the schema or Adobe InDesign CS4 IDML File Format Specification and determine that it is the Self attribute that is missing.
2. There is no “foo” attribute on the Rectangle element.
3. “RectData” is not a child of the Rectangle element.
4. Rectangle does not have a child element called “Propertie.” Looking at the schema, Adobe InDesign CS4 IDML File Format Specification, and numerous other examples, we can conclude that this element should be called “Properties” (with an ‘s’).

Additional Error Detection

The IDMLTools validation application includes some non-RelaxNG-based error detection. Currently, it checks for the following errors:

• Missing designmap.xml file.

• Missing or improper processing instruction at the top of the designmap.xml file.

• Missing package files included in designmap.xml; e.g., Spreads/Spread_ubd.xml in the following output:

Because Adobe distributes the source for IDMLTools, it’s possible to add additional error detection. You’ll find the code for these items in the Validator.preVerifyPackage() method.

• IDML files (or packages) are ZIP archives, containing numerous XML files. The entire set of these files represent a complete InDesign document. The files in an archive are described thoroughly in Adobe InDesign CS4 IDML File Format Specification. IDML files are identified by the *.idml file extension.
• Snippets are IDML-based files that describe a subset of an InDesign document. They are not archives, but single XML files that contain IDML. The application UI, scripting facility, and plug-in API allow you to export snippets from InDesign. Most commonly, such a snippet represents a page item or group of page items. These type of snippets usually are identified by the *.inds file extension.
• ICML (InCopy Markup Language) files are a special type of snippet. An ICML file represent s a single InCopy story using IDML. ICML files use the *.icml file extension.
• InCopy assignment files are another type of IDML snippet. They are used to allow multiple writers to work on one InDesign document. Assignment files use the *.icma extension.
• There are other features that leverage IDML; for example, exporting preflight profiles produces an IDML-based file.

The following is a 10 page InDesign CS4 document exported to SWF (Flash). 

You can turn the pages by clicking the text “Next”.  This text was converted to a button in InDesign.  After the first page you will also see a “Previous” button.

More interesting, you can use drag and drop to turn the pages as if you’re turning the pages of of a book or a magazine.  To turn the pages using drag and drop do the following: 

1. Hover the mouse cursor over the top right corner of the blue rectangle and drag it to the left.  You should see the page curl.
2. Click and drag to the left.
3. Release the mouse button when the page appears close to having turned.

If you need to export SWF from a plug-in, take a look at the ExportDynamicDocument code snippet in the InDesign CS4 Products SDK.  The above SWF was exported using that code snippet.

Note: We added a few enhancements (XFL export, and output file selection) in the 6.0.1 update.

The source file lives in the following location in the InDesign CS4 Products SDK.

  SDK/source/sdksamples/codesnippets/SnpExportDynamicDocument.cpp

The code snippet does the following in C++.

1. Creates a 10 page document.
• The pages dimensions are small to create the desired SWF size.
• At 100% scale this is 72 pixels per inch
2. Creates two text frames on the master pages and converts them both to buttons.
3. Adds appropriate events (back and next) to these two buttons.
4. Exports to SWF or XFL.

This last step demonstrates processing the kSWFExportCommandBoss and kXFLExportCommandBoss commands.

It’s more likely you would use scripting to build and export SWFs.  I anticipate adding an equivalent scripting sample in the near future.

Thanks,

Heath Lynn
Creative Suite Developer Technologies
Adobe Systems