Adobe CEP extension for InDesign to use the Bookalope cloud services.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
extensions/Bookalope
LICENSE.md
README.md

README.md

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 Add-On 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.

Requirements

The extension requires and supports Adobe InDesign versions 11–13. However, the extension may run on older versions that provide CEP support, but that hasn’t been tested.

Coding

Read a general introduction to writing an Adobe CEP extension here. 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.8.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.8 and add a key named PlayerDebugMode of type String and value 1.

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 → Extensions menu.

Debugging

Debugging the ExtendScript side of the extension doesn’t really work. However, I found it helpful to use the ExtendScript Toolkit, connect it to a running InDesign instance, and prototype the code there before using it for the Bookalope extension.

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 Window → Extensions menu.

Running

Once installed, open the extension panel:

Bookalope InDesign: Upload 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:

Bookalope InDesign: Update panel

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 is here;
  • The ExtendScript documentation is here;
  • Davide Barranca’s blog contains useful tips;
  • Adobe CEP extensions’s UI should be styled using CEP Spectrum Boilerplate or Topcoat.

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