Creating new plug-ins with the Dolly command line tool

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. The user interface version of Dolly has a limited number of settings that you can adjust, so using the command line has its advantages.

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.
Screen Shot 2013-02-20 at 11.53.18
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:

Mac:

You should be able to see the UI for Dolly:

Screen Shot 2013-02-20 at 12.47.14

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:

Mac:

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:

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

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.

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.

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.

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.

Generating MyPlugin

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

Windows:

Mac:

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

Screen Shot 2013-02-21 at 13.05.36

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.

Screen Shot 2013-02-21 at 13.05.00

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

Comments are closed.