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