Bookalope-CEP

Introduction

Adobe CEP, or Common Extensibility Platform, provides a framework to extend Adobe applications like InDesign with custom user interfaces and functionality. There is a wealth of useful extensions available on Adobe’s Extension Marketplace.

This repository contains the complete source code for Bookalope’s InDesign extension. The extension uses the Bookalope REST API and its Javascript wrapper to integrate the Bookalope toolset into InDesign. For more information on Bookalope and its services, please refer to the Bookalope website.

You can also download and install this extension directly from the Adobe Exchange.

Requirements

The extension requires and supports Adobe InDesign versions 13–17, which relates to CC 2018-22. However, while the extension may run on older versions that hasn’t been tested in depth.

Coding

Read a general introduction to writing an Adobe CEP extension here, and a more in-depth documentation provides the CEP Extension Cookbook. For more information on the Bookalope API please refer to its documentation on Github.

InDesign does not load an extension unless the extension has been cryptographically signed. Therefore, in order to run the Bookalope extension from source, you need to switch InDesign to PlayerDebugMode:

• On Mac, open the file ~/Library/Preferences/com.adobe.CSXS.9.plist and add a row with key PlayerDebugMode of type String and value 1. You can edit .plist files using Xcode, PList Edit or other applications suited to edit Property Lists.
• On Windows, using its registry editor open the registry key HKEY_CURRENT_USER/Software/Adobe/CSXS.9 and add a key named PlayerDebugMode of type String and value 1. Alternatively, reg add HKEY_CURRENT_USER\SOFTWARE\Adobe\CSXS.9 /t REG_SZ /v PlayerDebugMode /d 1 /f should work from the command line prompt.

If you have multiple CSXS versions installed, add the PlayerDebugMode to all of them.

For InDesign to find and load the Bookalope extension, copy the entire extensions/Bookalope folder to:

• On Mac: ~/Library/Application Support/Adobe/CEP/extensions
• On Windows: %APPDATA%\Adobe\CEP\extensions

Then start InDesign, and the extension should be available from the Window menu.

Debugging

First of all, make sure that the extension’s CSXS/manifest.xml contains valid XML; follow the instructions here. Note that the order of elements in <Geometry> actually seems to matter!

Debugging the ExtendScript side of the extension doesn’t really work in an integrated environment. The ExtendScript Toolkit has been retired, and in its stead you can use the ExtendScript Debugger for VisualStudio Code. I found it helpful to connect it to a running InDesign instance, and prototype the code there before using it for the Bookalope extension itself.

Debugging the Javascript side is easier. The file extensions/Bookalope/.debug configures a remote debugger which can connect to a running InDesign instance. Once the extension panel is open, navigate the Chrome web browser (or alternatively, the Adobe cef-client) to localhost:8001 and enjoy…

Building

To build the extension and generate an Adobe Zip Format Extension Package (.zxp) use Adobe’s ZXPSignCmd tool. You also need a valid PKCS 12 certificate. If you don’t have one yet, you may generate one using e.g. OpenSSL or the ZXPSignCmd itself:

> # ZXPSignCmd -selfSignedCert <countryCode> <stateOrProvince> <organization> <commonName> <password> <outputPath.p12> [options]
> ZXPSignCmd -selfSignedCert AU QL Bookalope Bookalope MyPa55w0rd bookalope-cep-cert.p12

Once you’ve created the certificate, package and sign the extension itself:

> # ZXPSignCmd -sign <inputDirectory> <outputZxp> <p12> <p12Password> [options]
> ZXPSignCmd -sign ./extensions/Bookalope com.bookalope.zxp bookalope-cep-cert.p12 MyPa55w0rd -tsa https://timestamp.geotrust.com/tsa

Finding a Trusted Timestamping Authority (TSA) that works for ZXPSignCmd seems to be challenging at times, so take a look at this list of possible options.

Installing

The easy way to install the packaged and signed extension is by using Anastasiy’s Extension Manager. The nerdy way is to use Adobe’s ExManCmd tool:

> ExManCmd --list all  # List all installed extensions
> ExManCmd --install ./com.bookalope.zxp  # Install the Bookalope extension

Then start InDesign, and the extension should be available from the panel list under the Window menu.

Running

Once installed, open the extension panel:

To use the Bookalope web services, you need a Bookalope API key: you can find the key in the user profile of your Bookalope account. Then select a book manuscript in Word format (or any other of the supported document formats), fill in Name and Author of the book, and then click the Upload and convert button.

The extension uploads the document to the Bookalope server for analysis and conversion. This can take a little while. Once finished, the extension downloads the converted file, creates a new InDesign document, and places the downloaded content into the new InDesign document. The extension’s panel changes now to this:

From here, you can open the document on the Bookalope website to revisit and adjust the entire analysis and conversion flow (watch the video tutorials on Youtube). You can also download the converted document in EPUB, MOBI, or print-ready PDF formats.

Further Documentation

Writing an Adobe CEP extension requires documentation which is not always readily available. However, some useful resources are:

• The Adobe CEP resources on Github are here, and more ExtendScript resources are here, including a Wiki;
• The Adobe CEP extensions’s UI is styled using Adobe’s Spectrum CSS;
• The ExtendScript documentation is here;
• Davide Barranca’s blog contains useful tips, and here is a great collection of additional resources.

In addition to the above, the InDesign Scripting Forum might be useful, or the #cep channel on Slack is a playground for many experienced developers.