I’m starting an InDesign SDK blog… The idea is that we will use this blog to make announcements and publish simple samples. That is my hope anyhow. I have to learn how to use the software though. So, this is more or less my “Hello World” posting.

Thanks,

Heath Lynn
Creative Suite Developer Technologies
Adobe Systems

InDesign CS4 adds the ability to export pages to Flash (SWF and XFL files).

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

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.

IDML (InDesign Markup Language) is an XML-based format, introduced in Adobe InDesign CS4, for representing InDesign content. IDML is used in several InDesign and InCopy file types:

• 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.

IDML is designed to be generated and manipulated by XML tools and programmers. To support this, IDML can be validated against a RelaxNG schema.

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.

We’ve received numerous requests for sample scripts that demonstrate working with the Adobe InDesign CS4 new live preflight feature. Several of these requests have come from InDesign Server partners who want to know how to use the new preflight engine. My Creative Suite Developer Technologies teammate Joe Stinson and I collaborated on the following information that we think will save you a lot of time when trying to script the new preflight feature.

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

One of the hardest aspects about scripting rules is discovering rule names and properties.  Due to the dynamic nature of rules (they really are just strings), specific rule names and properties do not show up in the Extend Script Tool Kit’s Object Model Viewer.  There are a couple ways to discover this information.  For your convenience, we’ve written a script that produces the following output.  This script (dumpLivePreflightRules.jsx) will be added to a future version of the SDK.  If you use a plug-in that adds custom rules, you’ll need to run the script to extract the new names and properties.

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

InDesign user-interface development can be expensive. It takes a lot of effort to implement a dialog or panel in ODFRC. Things should improve in future versions, with the possibility of using Flash-based user-interface tools like Flex and FlexBuilder. While this represents the future direction of InDesign user-interface development, there is a present reality in InDesign CS4. With an understanding of the current situation, you can implement Flash-based user-interfaces for InDesign CS4.

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

Here’s a nugget that will be of interest to those of you who regenerate Java/CORBA support for InDesign Server on the Mac. If you upgrade to Mac OS 10.6, you must rebuild the OmniORB tools with an x86_64 target to ensure that they run correctly. Setting up the OmniORB tools is coverred in Regenerating the Adobe InDesign CS4 Server Java API. You should get the x86_64 target by rebuilding the tools on the upgraded machine.

Perhaps you’ve come to native plug-in development from a more script-based background, or perhaps you have some existing script code you want to reuse in a new plug-in project. Whatever your background, it’s really handy to be able to run a script from a native plug-in, and it’s also surprisingly easy.

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"

InterfacePtr<IScriptManager> scriptManager(Utils<IScriptUtils>()->QueryScriptManager(kJavaScriptMgrBoss));
if (!scriptManager)
{
   return;
}

InterfacePtr<IScriptEngine> scriptEngine(scriptManager->QueryDefaultEngine());
if (!scriptEngine)
{
   return;
}

InterfacePtr<IScriptRunner> scriptRunner(scriptEngine, UseDefaultIID());
if (!scriptRunner)
{
   return;
}

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).

The Adobe Express View Engine (EVE) is the recommended method of laying out UI widgets in InDesign dialogs. The main benefit of using EVE is that widget geometry is calculated for you, so that when you add or remove widgets to a dialog all of the other widgets are shifted automatically without you having to recalculate sizes etc.

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..)

      EVEGenericPanelWidget
      (
         kInvalidWidgetID, // WidgetId
         0 // RsrcId
         0,
         kBindNone, // Frame binding
         Frame(0,0,0,0) // Frame is 0 for auto-sizing
         kTrue, // Visible
         kTrue, // Enabled
         kEVEAlignLeft | kEVELargeSpaceAfter | kEVEArrangeChildrenInColumn,
         {
            EVEDefaultButtonWidget
            (
               kOKButtonWidgetID, // WidgetID
               kSysButtonPMRsrcId, // RsrcID
               kBindNone, // Binding
               Frame(0,0,0,0) // Frame (l,t,r,b)
               kTrue, kTrue, // Visible, Enabled
               kSDKDefOKButtonApplicationKey, // Button text

               kEVELargeSpaceAfter,
            ),
            EVECancelButtonWidget
            (
               kCancelButton_WidgetID, // WidgetID
               kSysButtonPMRsrcId, // RsrcID
               kBindNone, // Binding
               Frame(0,0,0,0) // Frame (l,t,r,b)
               kTrue, kTrue, // Visible, Enabled
               kSDKDefCancelButtonApplicationKey, // Button name
               kTrue, // Change to Reset on option-click.
               
               kEVELargeSpaceAfter,
            ),
         } // End of EVE Generic panel child widgets
      ), // End of EVE Generic panel widget definition

   },
   
   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.

What is DollyXs?

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

author="Alex"
long-name="MyPlugin"
mac-debug-target-dir="../debug/sdk"
mac-id-header-dir="../../../source/sdksamples/myplugin"
mac-project-dir="/Users/Alex/Desktop/Adobe_InDesign_CS6_Plugin_SDK/build/mac/prj"
mac-release-target-dir="../release/sdk"
mac-sdk-dir="../../.."
mac-source-dir="../../../source/sdksamples/myplugin"
mac-target-type="i386"
product-type="kInDesignProduct, kInCopyProduct"
plugin-type="kUIPlugIn"
prefix-id="0xef190"
short-name="MP"
win-debug-intermediate-dir="..\objD"
win-debug-target-dir="..\debug\sdk"
win-id-header-dir="..\..\..\source\sdksamples\myplugin"
win-project-dir="/Users/Alex/Desktop/Adobe_InDesign_CS6_Plugin_SDK/build/win/prj"
win-release-intermediate-dir="..\objR"
win-release-target-dir="..\release\sdk"
win-sdk-dir="..\..\.."
win-source-dir="..\..\..\source\sdksamples\myplugin"
>
<vcproj-file/>
<rsp-cpp-file/>
<rsp-odfrc-file/>
<xcodeproj-file/>
<xcconfig-plugin-file/>
<xcconfig-plugin-debug-file/>
<xcconfig-plugin-release-file/>
<id-h-file/>
<id-cpp-file/>
<nostrip-file/>
<triggerresourcedeps-file/>
<factorylist-file/>
<rc-file/><fr-file/>
<enus-fr-file/>
<jajp-fr-file/>
<generate-menu/>
<impl-item impl-file="actioncomponent-impl-file" impl-id="kDollyActionComponentImpl" impl-name="DollyActionComponent"/>
<generate-dialog/>
<impl-item impl-file="dialogcontroller-impl-file" impl-id="kDollyDialogControllerImpl"
impl-name="DollyDialogController"/>
<impl-item impl-file="dialogobserver-impl-file" impl-id="kDollyDialogObserverImpl" impl-name="DollyDialogObserver"/>
<generate-panel/>

</code>

As you may have noticed, the InDesign CC SDK is available by request from http://www.adobe.com/devnet/indesign.html.

In this latest release we’ve added new samples to the SDK whilst some more basic features of plug-in development have also changed. We’ll talk about the new samples in future blog posts, but find below the more fundamental changes you need to know about if you are creating plug-ins for InDesign CC.

HiDPI support

Since InDesign CC supports the retina display of the MacBook Pro, plug-in developers now need to provide additional icons and cursors for their plug-ins.

To support HiDPI on Mac OS, plug-ins with icons should provide alternative versions of icons. The icons do not need to be HiDPI, but they should be double the dimensions of the original icons. For example, if the original icon is 22×22 then the HiDPI icon should be 44×44.

All of this is demonstrated in the project called SnapShot.sdk.xcodeproj included in the SDK. This sample also shows how to use a separate FR file for icon and cursor definitions, which is encouraged and especially useful for plug-ins with a large number of icon and cursor definitions.

Cursors and icons

PNGs instead of rsrc

Plug-ins must now use PNGs for icons and cursors and provide light and dark versions. We made this change since the Mac platform has deprecated the use of rsrc files, which used to be the primary source for cursors. Using PNGs provides a cross-platform method of cursor management.

Light and dark icons

To support theming, in which the application skin can be made light or dark, plug- ins with icons should now provide two icons, one light and one dark.

EVE dialogs

EVE (Adobe Express View Engine) has been recommended for defining dialog layout in previous releases but in CC we converted all of InDesign’s dialogs to use EVE. It is still possible to not use EVE, but we would strongly recommend that you use it for dialogs.

Using EVE gives the following benefits:

• In cases where text is different sizes on different operating systems, you no longer have to worry about calculating extra whitespace.
• English dialogs can be smaller because you do not need to leave room for anticipated localized text being longer.
• EVE eliminates problems with widgets that don’t quite line up correctly or text being chopped off because EVE automatically resizes static text, buttons, check boxes, radio buttons, and drop-down lists.

All SDK samples with dialogs have been updated to use EVE and there is a new PDF inside the plug-in SDK (Using EVE for Dialogs) documenting how to use it, and also how to convert existing dialogs to use EVE using a tool included in the SDK to get you started.

64bit Mac

InDesign CC is 64bit only on Mac OS. A large chunk of work for us in this release of InDesign was to decarbonize InDesign, that is to say, remove the use of Carbon APIs and make InDesign a Cocoa based application.

All SDK samples have 64bit Mac OS support and the plug-in project generator ‘dolly’ can be used for creating new plug-in projects with 64bit Mac support.

System requirements

The operating system requirements for InDesign are Windows 7 or later for Windows, and Mac OS 10.6 or later for Mac OS. Unlike the CS6 plug-in SDK, it is not possible to use Windows XP for developing InDesign plug-ins. This is due to InDesign CC being dependent on APIs found only in Windows 7 or later.

Regarding IDEs, as in CS6, we require Visual Studio 2010 on Windows. Unlike CS6, on Mac OS we require Xcode 4.5.2 rather than Xcode 3.2.5.

A new feature in InDesign CC is the ability to create and place QR codes. Here, I show how to do this using JavaScript.

The following APIs are available:

• createHyperlinkQRCode: for creating a QR code for a hyperlink).
• createEmailQRCode: for creating a QR code for an email address.
• createPlainTextQRCode: for creating a QR code for arbritary text.
• createTextMsgQRCode: for creating a QR code for an SMS message.
• createVCardQRCode: for creating a QR code for a vcard.

Here’s a nice easy sample:

1
2
3
4

var myPage = app.activeDocument.pages.item(0);
var myPageItem = myPage.rectangles.add();
myPageItem.geometricBounds = [5, 5, 15, 15];
myPageItem.createHyperlinkQRCode("http://www.adobe.com", "Magenta");

Result:

If a mobile app was used to scan this QR code it would take the user straight to www.adobe.com (although app behaviour does differ).

For more examples, see AddQRCodes.jsx in the Scripting SDK.

Another new feature in InDesign CC is the Dark UI. You can now adjust UI brightness and other UI properties using scripting.

• matchPreviewBackgroundToThemeColor: If set to true the Preview Background color will be set to match the Theme Color
• pasteboardColorPreference: Lets you set Pasteboard Color preference. Use 0 to set pasteboard color preference to Default White, and 1 to set preference to Match with Theme Color.
• uiBrightnessPreference: Lets you specify the Application User Interface brightness preference (from 0.0 to 1.0). To use color theme brightness preset values, specify 0.0 for Dark, 0.33 for Medium Dark, 0.67 for Medium Bright, and 1.0 for Bright. Any value between 0.0 and 1.0 can also be used.

Here is an example in JavaScript:

1
2
3
4
5
6
7
8
9
10
11
12

//adjust UI brightness
app.generalPreferences.uiBrightnessPreference = 0.45
 
//set pasteboard to white
app.generalPreferences.pasteboardColorPreference = 0;
 
with(app.activeDocument.pasteboardPreferences){
//set preview background to blue
previewBackgroundColor = UIColors.blue;
//set preview background to match theme
matchPreviewBackgroundToThemeColor(true);
}

The InDesign update you received in August 2013 (InDesign 9.1) included the enabling of HTML5 extensions.

As you may already know, starting in the middle of 2014 Adobe will begin removing Flash-based extension support in Creative Cloud products, starting with Photoshop CC.

If you have any hybrid or regular Flash extensions for InDesign you need to begin migrating them to HTML5 as soon as possible.

I just create plug-ins, why should I care?

HTML5 extensions are a great opportunity to create compelling user-interfaces for native plug-ins. But that’s not all. Creating hybrid extensions (where you have a native plug-in and a UI extension) also forces you to properly separate model and UI in your overall architecture.

I’m not saying you should slap an HTML UI on every-one of your plug-ins. For example, if your plug-in only has dialogs I wouldn’t bother. But if the plug-in had its own panel, then I would certainly consider using HTML.

Where do I start?

Adobe Extension Builder has been updated for HTML5 development. If you are not a fan of eclipse, just create your project in Extension Builder then use a text editor from that point on.

To get the latest Extension Builder and other tools visit the Extension Builder 3 site at Adobe Labs: http://labs.adobe.com/technologies/extensionbuilder3/.

How do I connect the HTML extension to the native plug-in?

There are two methods for enabling two-way communication between an HTML extension and a native plug-in:

1. You can add a scripting interface to your plug-in with some methods and properties, and have the HTML/JS extension use evalScript calls to run ExtendScript which calls these methods/properties.
2. You can send CSXS events back and forth between the native plug-in and HTML/JS extension.

The easiest method is the latter: using CSXS events. The attached sample, which includes an HTML extension and native plug-in, uses this method. It does also demonstrate how to add a scripting interface to a plug-in, should you wish to go down that route. If you wanted to call this scripting API from an HTML extension, you would need to use the evalScript function provided by CSInterface. For example:

new CSInterface().evalScript("app.speak");

Sending/receiving a CSXS event from a native plug-in

Here’s how to construct and send a CSXS event in InDesign CC onwards:

#include "ICSXSPlugPlugEventHandler.h"
#include "adobe/unicode.hpp" // for adobe::to_utf8
#include "FileTypeRegistry.h"

InterfacePtr plugPlug(GetExecutionContextSession(), UseDefaultIID());

PMString csxsEventStr;
csxsEventStr.SetCString("Hello from CPP!");
PMString eventData(csxsEventStr);
std::string csxsEventUtf8;
adobe::to_utf8(csxsEventStr.begin(), csxsEventStr.end(), 
                                     std::back_inserter(csxsEventUtf8));

ICSXSPlugPlugEventHandler::CSXSEvent responseEvent;
responseEvent.type = "com.adobe.indesign.scriptingcomms.html";
responseEvent.scope = ICSXSPlugPlugEventHandler::kEventScope_Application;
responseEvent.extensionId = nil;
responseEvent.data = csxsEventUtf8.c_str();

if (LocaleSetting::GetLocale().IsProductFS(kInDesignProductFS))
{
    // as defined in ICSXSPlugPlugEventHandler.h
    responseEvent.appId = kIDEnigmaCode; 
}
else
{
    // as defined in ICSXSPlugPlugEventHandler.h
    responseEvent.appId = kICEnigmaCode; 
}

plugPlug->DispatchPlugPlugEvent(&responseEvent);

Here is how to add an event listener for CSXS events:

InterfacePtr plugPlug(GetExecutionContextSession(), UseDefaultIID());
plugPlug->AddPlugPlugEventListener("com.adobe.indesign.scriptingcomms.cpp", 
                                    &MessageEventListener, nil);

The sample attached to this post has the following message handler, which nicely demonstrates how to handle a received message, do something with its data (in this case, show it in an alert dialog), and send a message back. Here is the code:

MessageEventListener(const ICSXSPlugPlugEventHandler::CSXSEvent* const csxsEvent, 
                     void* const context)
{
    // Display received data in alert dialog..
    PMString receivedData = PMString("Message received: ");
    receivedData.Append(csxsEvent->data);
    receivedData.SetTranslatable(kFalse);
    CAlert::InformationAlert(receivedData);

    // Send a message back to the HTML extension..
    InterfacePtr<ICSXSPlugPlugEventHandler> plugPlug(GetExecutionContextSession(), 
                                            UseDefaultIID());
    
    PMString csxsEventStr;
    csxsEventStr.SetCString("Hello from CPP!");
    PMString eventData(csxsEventStr);
    std::string csxsEventUtf8;
    adobe::to_utf8(csxsEventStr.begin(), csxsEventStr.end(), 
                   std::back_inserter(csxsEventUtf8));
    
    ICSXSPlugPlugEventHandler::CSXSEvent responseEvent;
    responseEvent.type = "com.adobe.indesign.scriptingcomms.html";
    responseEvent.scope = ICSXSPlugPlugEventHandler::kEventScope_Application;
    responseEvent.extensionId = nil;
    responseEvent.data = csxsEventUtf8.c_str();
    
    if (LocaleSetting::GetLocale().IsProductFS(kInDesignProductFS))
    {
        responseEvent.appId = kIDEnigmaCode; 
    }
    else
    {
        responseEvent.appId = kICEnigmaCode; 
    }
    
    plugPlug->DispatchPlugPlugEvent(&responseEvent);
}

A good place to create such a message listener is in a startup/shutdown service – so the message listener gets created on InDesign startup.

Sending/receiving a CSXS event from a HTML extension

Sending a message to the above native message listener is done as follows:

// Send a CSXS event to the native plug-in
var evt = new CSEvent("com.adobe.indesign.scriptingcomms.cpp", "APPLICATION", 
                      "IDSN", "com.adobe.indesign.scriptingcomms.html");
evt.data = "Hello from HTML!";
new CSInterface().dispatchEvent(evt);

Adding a message listener is also straightforward:

// Add an event listener so we can receive messages from this samples CPP plugin
csInterface.addEventListener("com.adobe.indesign.scriptingcomms.html", function(event) 
{
    alert("Message received: " + event.data);
});

Download source

Download the sample here: ScriptingComms

You will need the InDesign SDK in order to build the native plug-in part of this sample. Download the SDK here: http://www.adobe.com/devnet/indesign.html

The InDesign CC 2014 SDK will be available on the InDesign Family SDK Access Program from June 20.

If you are new to InDesign development, the best place to get started is ‘Getting Started with InDesign Development’, which is a guide included in the SDK.

As for this latest release, the following are the most significant changes in the SDK.

• Xcode updated to Xcode 5.0.2.
• Visual Studio updated to Visual Studio 2012 SP4.
• PMString::GrabCString removed.
• Windows HiDPI support added.
• Boost version updated to 1.54.
• IPMStream updated to support files larger than 4GB.
• CSXS events with global scope are replaced with VulcanMessage.

The porting guide, included in the SDK, contains more in-depth information on each of these changes, but I’ve given summaries below.

System Requirements

• For Windows development, Windows 7 SP1 or Windows 8 are minimum requirements.
• For Mac development, Mac OS 10.8.4 or later is now required (Xcode 5.0.2 requires this).

IDE Requirements

Visual Studio version is now Visual Studio 2012 SP4

To update a Visual Studio project, the simplest method is to open the project in Visual Studio 2012 and use the prompt to update the project.

Alternatively you can modify the project file in a text editor by changing the PlatformToolset version to v110. Details are given in the porting guide.

Xcode version is now Xcode 5.0.2

Updating Xcode projects

When building your projects with Xcode 5, one issue you will quickly run into is PluginPList.plc giving compilation issues:

Unable to run command 'CopyPlistFile Info.plist' this target might include its own product.

In case you don’t know, PluginPList.plc is the template for generating plugin plist files.

To fix this, move the plc file from the Sources group section into the Resources group in the Xcode project. You can do this in the Xcode IDE by dragging PluginPList.plc from Sources to Resources. The effect of this change is that the .plc file is included in the “Copy Bundle Resources Phase” instead of the “Compile Sources Phase”.

Boost version change

InDesign now uses Boost 1.54, with some modifications. One side effect of this change is that you may need to update your plug-in projects to link against boost_system.

Removal of GrabCString from PMString

PMString::GrabCString has been removed. You should use GetCString or GetPlatformString().c_str() instead.

Windows HiDPI support

InDesign now supports HiDPI on Windows. If you added support for HiDPI on Mac in the 9.0 release of InDesign, you will now need to make similar changes for Windows.

If you use widgets with custom drawing, you should test how they look on Windows at 2x and 1.5x to see if changes are required. In most cases, the drawing that you are doing for 1x should work on 1.5x and 2x. You might sometimes need to do some one pixel adjustments specific to 1.5x or 2x. Standard widgets work fine without any changes.

InDesign supports the following scaling factors:

• System Scaling < 1.24 => InDesign Scaling = 1x
• System Scaling >= 1.25 and <= 1.74 => InDesign Scaling = 1.5x
• System Scaling >= 1.75 => InDesign Scaling = 2x

CSXS events with global scope are no longer supported

In InDesign 9.0 we added an API for dispatching CSXS events. This API included the ability to dispatch events with global scope so they could be sent between applications.

In InDesign 10.0, CSXS events with global scope are no longer supported and Vulcan Messages should be used instead. A new API has been added to send/receive VulcanMessages. The API exists at: /source/public/interfaces/ui/ICSXSVulcanMessageHandler.h.

InDesign CC 2014.1 (InDesign version 10.1) and its corresponding plug-in SDK (x070 and x071) contains a new include which will be of particular interest to anyone developing hybrid extensions.

In case you don’t know, a hybrid extension is an extension which consists of one or more native plug-ins and one or more HTML (or Flash) extensions.

The new APIs, found in the SDK at /source/public/interfaces/ui/ICSXSPlugPlugExtensions.h, enable workflows where a native plug-in needs to open or close an extension.

Whilst there is no need to port or recompile your plug-ins from 10.0 to be compatible with 10.1, if you want to use this API you will need to use the latest SDK to pick up the new header and you will then have to recompile.

The two APIs are LoadExtension and UnloadExtension, each taking the bundle ID of the extension you wish to open or close.

Here’s a quick example to get you going:

#include "ICSXSPlugPlugExtensions.h"

InterfacePtr plugPlug(GetExecutionContextSession(), UseDefaultIID());
        
// open an extension
plugPlug->LoadExtension(PMString("com.mycompany.myextension"));
        
// close an open extension
plugPlug->UnloadExtension(PMString("com.mycompany.myextension"));

Enjoy!