InDesign scripting (censhare Client)

Set up a script in the censhare Metadata dialog for automated workflows with the help of JavaScript, AppleScript (OS X) or VBScript (Windows).

Introduction

The scripting support allows for add-on features created with JavaScript, AppleScript (OS X) and VBScript (Windows). The implemented scripting support can use all three of InDesign's scripting languages. To make it executable on both operating systems, JavaScript is the only language of choice. If you sooner or later decide to run a script in a mixed environment, you have to keep that in mind before you start coding.

Censhare stores a script as an asset of type ressource. Afterwards it can be launched either from your local censhare Client or directly on the server. With the help of XPath, you can specify on which domains and asset types the script is applicable. The execution of a script can be initiated manually in censhare's Tools palette from within InDesign. Operation is also possible with the censhare Layout Editor. One or more scripts are executed as soon as a rendering action is executed by InDesign server.

Example

Imagine a working environment, that requires you to remove all unused swatches from the document starting with a particular workflow step or late production phase. This ensures that in the production process during final adjustments and usually lots of color swatches, a similar hue is not accidentally chosen, provided that at this point the art department has already finalized the layout.

In the corporate sector, a script can ensure that with every re-rendering the layout editor of censhare checks whether all placed image boxes are also filled with pictures. If at least one placeholder box is found with no picture, the script can colorize it red or show a dialog with a notice.

In a document with picture frames which are all of the same size, a script can take over the task of exchanging the positions of two selected images. In a further stage of the script also grouped layout elements (i.e. images with their captions) could be quickly repositioned with this method.

Configuration

censhare stores a script as an asset of type ressource. The asset type is correctly identified, but it is not yet configured that it is a script for InDesign. For this reason, the asset must receive the type Module/Script/Adobe InDesign-Script. Only then it is also identified properly. In addition, an optional target asset filter can specified via XPath.

Example:

XML

:starts-with(asset/@keywords, 'customized, wordcounter')  and starts-with(asset/@type, 'layout.') and days-from-duration
 (current-dateTime() cast as xs:date - asset[1]/@creation_date cast as xs:date) lt 28

Scripting parameters

The following parameters are available in scripts. Access is performed via the ScriptArgs map.

censhareTargetDocument: ID of the document. The ID of a document never changes. Not even when the document is closed and then reopened. The ID is therefore the preferred way for addressing a document. However, this parameter is only available for CS5 and newer. If a script must be also compatible with older versions of InDesign then the document index can be used.

Example:

XML

var myDocument = app.documents.itemByID( parseInt( app.scriptArgs.getValue( "censhareTargetDocument" )))

censhareTargetDocumentIndex: Index of document.

Example:

XML

var myDocument = app.documents[app.scriptArgs.getValue( "censhareTargetDocumentIndex" ) ]

In the "Edit metadata"-dialogue of the script ressource asset the check-box for "Box selection" has to be set.

If the script is invoked manually in InDesign or the Layout Editor, at least one frame has to be selected.

If the script is run automatically by an event, this must be an event that is triggered by single box frames. Those are: placement, content update and changing the box frame (the latter only in the layout editor).

Example:

XML

var boxUids = app.scriptArgs.getValue( "censhareTargetBoxes" ).split(",");
  for (var i in boxUids) {
      var boxUid = parseInt(boxUids[i]);
      var box = myDocument.rectangles.itemByID(boxUid);
      ...
  }

Using the parameter censhareResult a string can be passed on by a script as a return parameter. If the script is run manually in InDesign or in the layout editor, the result is displayed using a modal dialogue. With automatically running scripts (event-based) the return value plays no further role. If a script still returns a value, it is ignored.

Example:

XML

censhareTargetApplication.scriptArgs.setValue(censhareResult, "The result");

Automatic / event-based execution of scripts:

Scripts can be executed both in InDesign as well as in the Layout Editor, not only manually, but also automatically after certain events. The same applies to all server operations and asset-automation commands that run on the renderer.
The associated script resource asset events are assigned through the Metadata dialogue:

The following events are available:

After opening: The script are applied immediately after opening a document. This affects the local opening of an asset in InDesign or in the layout editor during the checkout process. But it also affects all automatic server commands and server actions, which go through the renderer for example, "PDF export" or "update asset.".

Before saving: The script is executed just before the check-in or before saving a version. This affects check-in or version saving in InDesign or in the layout editor. But it also applies to all automatic server commands and server actions, which run on InDesign Server via the Render-Client, if they create a new version of the master file. The latter for example is not the case when only a PDF is created.

After placing:The script is applied after placing an asset or a collection. Here, the list of the boxes in which something is placed, is passed as a parameter (censhareTargetBoxes). The script is not only executed after a manual placement via drag and drop in InDesign or the Layout Editor application, but also for all automatic actions such as Geometry updates or automated collection placement.
In the Layout Editor, the script is not applied immediately after placing, but only when the Render Client is called for the next time (for example by clicking on "Preview").

After a content update: The script is executed after a content update. Here the script receives the list of boxes whose content has been updated as a parameter (censhareTargetBoxes). This affects a content update from within InDesign or an update in the Layout Editor, but also all automatic server commands and server actions, which are executed by the Render Client.

Preview (Layout Editor): A script that is provided with this type of event is executed immediately after the Layout Editor requests a preview calculation. This can be triggered by clicking the Preview button (eye) or other events, e.g. geometry updates or content updates.

Box changes: This event is only available in the Layout Editor. The script is executed by the Render Client immediately after boxes have changed. The script receives the list of all modified boxes as a parameter (censhareTargetBoxes). The script will not run if something is placed in a box or only the content has been updated, because separate events exist for that purpose.

These are the changes:

- remove placements
- box geometry change (moving or size change)
- image transformation or image crop adjustments

Prior to PDF creation: The script is executed immediately before creating a PDF file. This does not apply to local PDF export from InDesign, but to all PDF export actions that run through the renderer, for example PDF creation in the layout editor or automatic server commands or server actions.

Visual Basic can not provide feedback on the result of the script execution (DoScript), as it is possible with both AppleScript and JavaScript. Therefore the lowest common denominator is the use of ScriptArgs for all three scripting languages.