Smart Connection Scripting and Events Guide for Adobe CC · 2019-01-15 · Scripting and Events...

Scripting and Events Guide

Last Modification: January 16, 2015 /45

© 2000-2015 WoodWing Software bv. All Rights Reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of WoodWing Software.

The information in this book is furnished for informational use only and is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of the agreement.

Smart Layout, Smart Styles, Smart XML, Smart Catalog, Smart Hyphen, Smart Speller, Smart Connection and Smart Connection Enterprise are trademarks of WoodWing Software. All other company and product names used herein may be the trademarks or registered trademarks of their respective companies.

Adobe, InDesign and InCopy are trademarks of Adobe Systems Incorporated. Apple, Mac, Macintosh and Power Macintosh are trademarks of Apple Computer, Inc. registered in the U.S. and other countries. Microsoft, Windows NT, Windows XP, and Windows 2000 are trademarks of Microsoft Corporation registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners.

Smart ConnectionScripting and Events Guide

for Adobe CC

January 16, 2015

IntroductionMany aspects of the Smart Connection client application are scriptable using JavaScript. This guide contains examples sharing how to script the Smart Connection specific part of the scripting object model. It should be used as a companion to InDesign’s Scripting Guide and the scripting model presented by the Adobe ExtendScript Toolkit.

This guide can be used with the following versions of Smart Connection:

• Smart Connection 9

• Smart Connection for Adobe CC

Revision history

Rev Date Remarks

v1.8.2 01/03/2014 Added information about Selective Folio Creation as introduced with v8.3.3

v1.9 01/20/2014 Revised for Smart Connection 9.2

v1.10 07/25/2014 Some tweaks for Multi -place Gun in ”Overrule placement of Articles and Dossiers”

v1.11 07/11/2014 Added beforeImportImage event.

v1.12 16/01/2015 Changed document name.



Contents1. JavaScript Reference �� 3

1.1 Application �� 31.1.1 Properties �� 31.1.2 Methods �� 3

1.2 Document �� 51.2.1 Properties �� 5

1.3 Dossier�� 51.3.1 Properties �� 51.3.2 Methods �� 51.3.3 Example �� 6

1.4 Dossiers �� 71.4.1 Methods �� 7

1.5 EntDmPreferences �� 71.5.1 Properties (Group) �� 71.5.2 Properties (Layer) �� 9

1.6 EntDmWorkflow �� 91.6.1 Methods for EntDMWorkflow (Document) �� 91.6.2 Methods for EntDMWorkflow (Page) �� 101.6.3 Methods for EntDMWorkflow (Group) �� 101.6.4 Examples �� 11

1.7 EntIssue �� 191.7.1 Properties �� 19

1.8 EntMetaData �� 191.8.1 Keys �� 191.8.2 Properties �� 191.8.3 Methods �� 201.8.4 Example �� 21

1.9 EntPublication �� 211.9.1 Properties �� 21

1.10 EntSection �� 211.10.1 Properties �� 21

1.11 Group �� 211.11.1 Properties �� 21

1.12 Layer �� 221.12.1 Properties �� 22

1.13 ManagedAdvert �� 221.13.1 Properties �� 22

1.14 ManagedAdverts �� 221.14.1 Methods �� 22

1.15 ManagedArticle �� 221.15.1 Properties �� 221.15.2 Methods �� 221.15.3 Example �� 24

1.16 ManagedArticles �� 241.16.1 Methods �� 24

1.17 ManagedImage �� 251.17.1 Properties �� 251.17.2 Methods �� 25

1.18 ManagedImages �� 251.18.1 Methods �� 25

1.19 ManagedLayoutModule �� 251.19.1 Properties �� 25

1.20 ManagedLayoutModules �� 251.20.1 Methods �� 25

1.21 Page �� 261.21.1 Properties �� 26

1.22 PageItem �� 261.22.1 Properties �� 261.22.2 Methods �� 26

1.23 Session �� 261.23.1 Properties �� 26

1.24 Story �� 281.24.1 Properties �� 28

1.25 Workflow �� 281.25.1 Properties �� 281.25.2 Methods �� 29

2. Scripting Events �� 312.1 Setup �� 31

2.1.1 ScriptsFolderPath element �� 312.1.2 Script element �� 31

2.2 Events �� 322.2.1 afterOpenLayout �� 322.2.2 afterOpenArticle �� 322.2.3 beforeSaveLayout �� 322.2.4 afterSaveLayout �� 332.2.5 beforeSaveArticle �� 332.2.6 afterSaveArticle �� 342.2.7 beforeExportArticle �� 342.2.8 afterExportArticle �� 342.2.9 beforeExportArticleTemplate �� 352.2.10 afterExportArticleTemplate �� 352.2.11 beforeCreateLayout �� 352.2.12 afterCreateLayout �� 352.2.13 beforeCreateLayoutTemplate �� 362.2.14 afterCreateLayoutTemplate �� 362.2.15 beforeCreateArticle�� 362.2.16 afterCreateArticle �� 362.2.17 beforeCreateArticleTemplate �� 372.2.18 afterCreateArticleTemplate �� 372.2.19 afterPlace �� 372.2.20 beforeDetachArticle �� 372.2.21 afterDetachArticle �� 382.2.22 afterCreateJump �� 382.2.23 afterCreateContinuationElement �� 392.2.24 afterRefreshArticle �� 392.2.25 beforeImportImage �� 39

2.3 Troubleshooting �� 413. Smart Connection Custom Menu Items �� 424. Overrule placement of Articles and Dossiers �� 44



1. JavaScript ReferenceThis chapter lists new objects and extensions to existing InDesign objects. The objects are listed in alphabetical order, and each object has a description of the added properties and methods. A property or event can have an indication that it’s not available in all applications — InCopy, InDesign, and InDesign Server — but in a subset of them. If nothing is mentioned, the property or event is available in all applications.

1.1 ApplicationThe InDesign application.

1.1.1 Properties

Table 1.1.1 Application propertiesProperty Type Access DescriptionentSession Session read Access to the Enterprise session.

1.1.2 Methods

Table 1.1.2 Application methodsMethod Returns Descriptionlogin nothing DEPRECATED, Use Session::login

Performs login to Enterprise system. Throws an exception in case of an error.

Parameter Type Descriptionusername string The user name.password string The password.server string Name of the location to log in to. This is the name of the

entry in the server list of the WWSettings.xml file.

logout nothing DEPRECATED, Use Session::logout.

Performs a logout from the Enterprise system. Throws an exception in case of an error.

reLogIn nothing DEPRECATED, Use Session::reLogin

Performs a re-login to the Enterprise system. Throws an exception in case of an error.

Useful when changes were made to the configuration, workflow, etc on the server and those values are returned during login.

queryObjects string Performs a user query based on passed criteria. Returns a query result as a string.

Parameter Type Descriptioncriteria Array of

stringThe criteria in the form, array of <key, value> pairs. That means: criteria[0] = "Brand, WW News"; criteria[1] = "Issue, 2nd Issue"; etc.

sendObjectToNext nothing Sends file to the next status. Throws an exception in case of an error.

Parameter Type Descriptionid string The object id.

offlineQuery string Generates the result for the offline query event.(Continues on next page)



Table 1.1.2 Application methods (continued)Method Returns DescriptionstoredUserQuery string Generates the result for the Stored user query event.

Parameter Type DescriptionqueryName string The stored query name.

browseQuery string Generates the result for the Browse query event.

Parameter Type Descriptionpublication string The Brand name.issue string The Issue name.section string The Category name.status string The Status name.

namedQuery string Performs the named query. It can be used for the Inbox, Templates, and NameSearch queries.

Parameter Type DescriptionqueryName string The name of the query.[filename] string The object Name.[fileType] string The object type.

updatePanels ID

IC

nothing Refreshes the contents of all Enterprise query panels. Throws an exception in case of an error.

openObject Document Opens the document from the Enterprise system. Throws an exception in case of an error.

Parameter Type DescriptionobjectID string The object ID.[checkout] boolean Pass false to open the document as read-only.

For template files pass false to open an instance instead of the original. Default is true.

[withWindow] boolean Pass false to open the document without opening a win-dow. Default is true.

[type] string Object type. Default is an empty string.[dossier] string The id of the default parent Dossier. Default is an empty

string. The passed Dossier will be used as the default selected Dossier in the Save As dialog or when creating an Article or Image from the Layout (if the document is a layout).

getDossiersForItem Array of string

Performs a query to retrieve all Dossier ids that the object is part of.

Parameter Type Descriptionid string The object id.



1.2 DocumentA document in InDesign, InDesign Server (layout), or InCopy (article).

1.2.1 Properties

Table 1.2.1 Document PropertiesProperty Type Access DescriptionactiveEdition string read/write The active Edition. The metadata of the document con-

tains all possible Editions that can be set.defaultEditions Array of string read/write The list of Editions that new page items will be assigned

to when creating those items.managedArticles ManagedArticles read All managed articles.managedImages ManagedImages read All managed images.managedAdverts ManagedAdverts read All managed adverts.managedLayoutModules ManagedLayoutModules read All managed Layout Modules.entMetaData EntMetaData read Enterprise metadata associated with the document.entDmWorkflow EntDmWorkflow read Access to digital publishing related actions.entWorkflow Workflow read Access to Enterprise workflow actions.

1.3 Dossier

1.3.1 Properties

Table 1.3.1 Dossier propertiesProperty Type Access DescriptionentMetaData EntMetaData read Enterprise metadata associated with the Dossier.items Array of string read The ids of the items in the Dossier.

1.3.2 Methods

Table 1.3.2 Dossier methodsMethod Returns DescriptionaddItem nothing Adds an item to the Dossier. Adds the item to the corresponding Dossier in Enterprise as

well.

Parameter Type Descriptionid string The id of the item to add to the Dossier.

removeItem nothing Removes an item from the Dossier. Removes the item from the corresponding Dossier in Enterprise as well.

Parameter Type Descriptionid string The id of the item to remove from the Dossier.

create nothing Creates a new Dossier object. The Dossier is created in Enterprise as well.remove nothing Removes the Dossier object. The corresponding Dossier is removed from Enterprise as

well.save nothing Saves the Dossier object. The Dossier is saved in Enterprise as well.refresh nothing Refreshes the Dossier object.



1.3.3 ExampleSample that creates a new Enterprise Dossier object:

Code Fragment 1.3.1 Creating a new Enterprise Dossier objecttry{

var dossier = app.dossiers.add();

// Access the Dossier metadatavar md = dossier.entMetaData;

// Set the metadatamd.set('Core_Name', 'dossier');md.set('Core_Publication', 'WW News');md.set('Core_Issue', '1st Issue');md.set('Core_Section', 'News');md.set('Core_Basket', 'Dossiers');

// Create the Dossierdossier.create();

}catch( e){

desc = e.description;num = e.number;alert( 'error ' + num + ': ' + desc );

}

Two samples that create a new Enterprise Dossier object containing two pre-existing articles. Both samples have the same end results, but the first sample is more efficient: it requires less interaction with Enterprise because it adds the articles before creating the Dossier.

Code Fragment 1.3.2 Adding objects to a new Enterprise Dossier objecttry{




dossier.addItem( “314” ); // add article with id 314 to the Dossierdossier.addItem( “315” ); // add article with id 315 to the Dossier


}catch( e){


}

(Continues on next page)



Code Fragment 1.3.3 Adding objects to a new Enterprise Dossier object (continued)try{





md.addItem( “314” ); // add article with id 314 to the Dossiermd.addItem( “315” ); // add article with id 315 to the Dossier

}catch( e){


}

1.4 Dossiers

1.4.1 Methods

Table 1.4.1 Dossiers methodsMethod Returns Descriptioncount number Returns the number of Dossiers.add Dossier Creates a new Dossier scripting object that can serve as the basis for creating a new

Dossier in Enterprise. Does not actually create the Dossier in Enterprise.retrieve Dossier Retrieves a Dossier from the Enterprise system and adds it to the Dossiers collection.

Parameter Type Descriptionid string The id of the Dossier to retrieve from the Enterprise

system.

1.5 EntDmPreferencesProvides access to the digital publishing related data. The EntDmPreferences objects can be accessed through the Group object representing the digital publishing asset and the Layer object representing the hotspot or scrollable area.

1.5.1 Properties (Group)

Table 1.5.1 Story propertiesProperty Type Access Descriptiontype string read The type of the digital publishing component.

Possible values: “Audio”, “DossierLink”, “Hotspot”, “ScrollableArea”, “SlideShow”, “Video”, “WebElement”, “CloseButton”, “SelectedHotspot”, “Widget”.



Table 1.5.1 Story propertiesProperty Type Access Descriptionsettings Array of key/

value pairs read/write List of settings of the current component. Both keys and values are strings.

Not available for “SelectedHotspot” which does not have properties

Component Type Key ValueAudio Video WebElement

“URL” string containing a url pointing to the asset that will be loaded. Can point to an external location, or to a location inside the publishing using the bundle:// notation.

WebElement components with an empty “URL” will become custom objects during export.

Audio Video

“DossierAsset” string containing the object id of the asset used in the packaged publishing.

Audio Video

“AutoPlay” string indicating whether the component should start automatically. Possible values are “true” and “false”.

Audio “PlayInBackground” string indicating whether audio should con-tinue playing when reader browses to another page or article. Possible values are “true” and “false”. Default value is “false”.

Video “HideAfterPlaying” string indicating whether inline video should stop at the last frame or not. Possible values are “true” and “false”. Default value is “true”; in that case the video will not stop at the last frame.

Video “AllowPause” string indicating if inline video may be paused or not. Possible values are “true” and “false”. Default value is “true”.

Video “ShowControls” string indicating if video play/pause controls are shown when video is tapped. Possible values are “true” and “false”. Default value is “true”.

Video “FullScreen” string indicating whether play in full screen is allowed or not. Possible values are “true” and “false”. Default value is “false“.

WebElement “ShowIn” string containing the target of the WebElement. Possible values are “inBrowser”, “inReader” and “embedded”.

DossierLink “DossierID” string containing the object id of the dossier that link points to.

DossierLink “PageNumber” string containing the page number within the article that the link points to.

Hotspot ScrollableArea

“LayerName” string containing the name of the layer that contains the content of the hotspot or scrol-lable area.

Hotspot ScrollableArea

“ExportAsBitmap” string indicating to export the hotspot or scrol-lable area as bitmap or not. Possible values are “true” and “false”. Default value is “false”.

Hotspot “AutoPopup” string indicating whether the hotspot should be shown automatically. Possible values are “true” and “false”.

CloseButton “CloseAll” string indicating whether this is a close all button. Possible values are “true” and “false”. Default is “false“.

SlideShow “Order” array of strings containing the object id’s of the images used in a slideshow. The order in the array defines the order in the slideshow.

Widget “WidgetID” string containing the database id of the widget.Widget “Parameters” string containing the manifest of the widget.



1.5.2 Properties (Layer)

Table 1.5.2 Story propertiesProperty Type Access Descriptiontype string read The type of the digital publishing component.

Possible values: “HotspotLayer”, “ScrollableAreaLayer” or “”.

settings Array of key/value pairs

read/write List of settings of the current asset. Keys are strings, values are Group or PageItem objects

Component Type Key ValueHotspotLayer “Hotspot” points to an array of hotspot Group

objects to which this layer belongs and which activate the hotspots.

HotspotLayer “CloseButton” points to Group object on the hot-spot layer representing the hotspot close button.

HotspotLayer “SelectedHotspot” points to Group object on the hot-spot layer representing the selected hotspot.

HotspotLayer “HotspotPopup” points to an array of all PageItem objects on the hotspot layer exclud-ing the items for CloseButton and SelectedHotspot.

ScrollableAreaLayer “ScrollableArea” points to the Group object to which this layer belongs.

ScrollableAreaLayer “ScrollableContent” points to an array of all PageItem objects on the scrollable area layer.

1.6 EntDmWorkflowEntDmWorkflow is the entry point for digital publishing related operations and can be accessed through the Document, Page and Group object.

1.6.1 Methods for EntDMWorkflow (Document)

Table 1.6.1 EntDmWorkflow methods (Document)Method Returns Descriptionadd Array of

Group, Layer

Creates a new digital publishing component or sub-component.

Returns an array of a Group and optionally a Layer. The latter is returned when the type of the created component is “Hotspot” or “ScrollableArea”.

For components of type “SlideShow” additional steps are required to create and manage the image inside the slideshow. See the example below.

Parameter Type Descriptionobject PageItem

or GroupThe object on the layout that serves as the basis for the new digital publishing component.

type string The type of component that needs to be created. Possible values are: “Audio”, “DossierLink”, “Hotspot”, “ScrollableArea”, “SlideShow”, “Video”, “WebElement”, “Widget”, “CloseButton” or “SelectedHotspot”.



remove nothing Removes a digital publishing component or subcomponent from the layout.

Parameter Type Descriptionobject Group The group item that represents the digital publishing

component.[removeLayer] boolean Indicates whether the layer associated with a hotspot or

scrollable area needs to be removed as well.

Default is false.

createDmArtboards layer Create the artboards for all devices on this document. Returns the layer containing the artboards.

1.6.2 Methods for EntDMWorkflow (Page)

Table 1.6.2 EntDmWorkflow methods (Page)Method Returns DescriptioncreateDmArtboards layer Create the artboards for all devices on this page. Returns the layer containing the artboards.

1.6.3 Methods for EntDMWorkflow (Group)

Table 1.6.3 EntDmWorkflow methods (Group)Method Returns DescriptionaddItem nothing Adds an existing pageitem to a group object. Used for adding placed images to a slideshow.

After adding the images to the group, the “Order” key of the settings needs to be updated to define the ordering of the images in the slideshow. See the example under EntDmWorkflow for details.

Parameter Type Descriptionobject PageItem The placed image object that needs to be added to the

group.[position] int The position of the image in the group.

Default is at the end.

removeItem nothing Removes an existing pageitem from a group object. Used for removing an image from a slideshow.

Parameter Type Descriptionobject PageItem The pageitem that needs to be removed from the group.

linkLayer nothing Links the digital publishing object (group) to a layer.

Parameter Type DescriptionlayerName string The layer name to link to the object.



1.6.4 ExamplesThis section contains samples explaining the creation and use of all digital publishing components.

Code Fragment 1.6.1 Working with dossier link objects//// Create a dossier link component//

var myDoc = app.activeDocument;var myPage = myDoc.pages.item(0);var myPageItem = myPage.rectangles.add({geometricBounds:["36pt", "36pt", "136pt", "136pt"]});

// Add a DossierLink componentvar myDossierLink = myDoc.entDmWorkflow.add(myPageItem, "DossierLink");

// (check) Get the DossierLink settings = [["DossierID", ""], ["PageNumber", "1"]]var dossierLinkSettings = myDossierLink.entDmPreferences.settings;alert( dossierLinkSettings );

// (check) Get the type = DossierLinkvar myType = myDossierLink.entDmPreferences.type;alert( myType );

// Change the DossierLink settings, make it point to a specific page in another // article (dossier)myDossierLink.entDmPreferences.settings = [["DossierID","638"], ["PageNumber", "2"]];

// (check) Get the DossierLink settings = [["DossierID","638"], ["PageNumber", "2"]]dossierLinkSettings = myDossierLink.entDmPreferences.settings;alert( dossierLinkSettings );

// Remove the DossierLink componentmyDoc.entDmWorkflow.remove(myDossierLink);

Code Fragment 1.6.2 Working with audio objects//// Create a digital publishing audio component//


// Add an audio componentvar myAudio = myDoc.entDmWorkflow.add(myPageItem, "Audio" );

// (check) Get audio settings = ["AutoPlay", "false"]var audioSettings = myAudio.entDmPreferences.settings;alert( audioSettings );

// (check) Get type = Audiovar myType = myAudio.entDmPreferences.type;alert( myType );

// Change audio settings, assign an audio file from and set the component// to play automaticallymyAudio.entDmPreferences.settings = [["DossierAsset","661"], ["AutoPlay", "true"]];

// (check) Get audio settings = [["DossierAsset","661"], ["AutoPlay", "true"]]audioSettings = myAudio.entDmPreferences.settings;alert( audioSettings );

// Remove audio componentmyDoc.entDmWorkflow.remove(myAudio);



Code Fragment 1.6.3 Working with video objects//// Create a digital publishing video component//


// Add a video represented by a dossier assetvar myVideo = myDoc.entDmWorkflow.add(myPageItem, "Video");

// (check) Get the type = "Video"var myType = myVideo.entDmPreferences.type;alert( "Component type: " + myType );

// (check) Get video settings = [["FullScreen","false"], ["AutoPlay", "false"]]var videoSettings = myVideo.entDmPreferences.settings; alert( "Component settings: " + videoSettings );

// Change the video data and full screen, autoplaymyVideo.entDmPreferences.settings = [["DossierAsset","662"], ["FullScreen","true"], ["AutoPlay", "true"]];

// (check) Get the video settings = [["DossierAsset","662"], ["FullScreen","true"], ["AutoPlay", "true"]]videoSettings = myVideo.entDmPreferences.settings; alert( "Component settings: " + videoSettings );

// Remove the video componentmyDoc.entDmWorkflow.remove(myVideo);

Code Fragment 1.6.4 Working with web element objects//// Create a digital publishing Web Element component//


// Add a web element componentvar myWeb = myDoc.entDmWorkflow.add(myPageItem, "WebElement");

// (check) Get the type = "WebElement"var myType = myWeb.entDmPreferences.type;alert( "Component type: " + myType );

// (check) Get the web element settings = ["ShowIn", "embedded"]var webSettings = myWeb.entDmPreferences.settings;alert( "Component settings: " + webSettings );

// Change the web element datamyWeb.entDmPreferences.settings = [["URL","http://www.woodwing.com"],["ShowIn", "inReader"]];

// (check) Get the web element settings = ["URL","http://www.woodwing.com"], ["ShowIn", "inReader"]webSettings = myWeb.entDmPreferences.settings;alert( "Component settings: " + webSettings );

// Remove web elementmyDoc.entDmWorkflow.remove(myWeb);



Code Fragment 1.6.5 Working with slideshow objects////create a Digital Publishing SlideShow//

var myDoc = app.activeDocument;var myPage = myDoc.pages.item(0);

// Place 2 database imagesvar myPageItem1 = myPage.rectangles.add({geometricBounds:["36pt", "36pt", "78pt", "90.48pt"]});myPageItem1.placeObject("667");var myPageItem2 = myPage.rectangles.add({geometricBounds:["36pt", "36pt", "78pt", "90.48pt"]});myPageItem2.placeObject("668");

// Add the items to an array for grouping.var myArray = new Array;myArray.push(myPageItem1);myArray.push(myPageItem2);

// Group the items in the arrayvar myGroup = myPage.groups.add(myArray);

// Create a slide show on the groupvar mySlideShow = myDoc.entDmWorkflow.add(myGroup, "SlideShow");

// (check) Get the type = SlideShowvar myType = mySlideShow.entDmPreferences.type;alert( "Component type: " + myType );

// (check) Get the slideshow settings = ["Order", ["668", "667"]]var ssSettings = mySlideShow.entDmPreferences.settings;alert( "Component settings: " + ssSettings );

// Add another image to slideshowvar myPageItem3 = myPage.rectangles.add({geometricBounds:["36pt", "36pt", "78pt", "90.48pt"]});myPageItem3.placeObject("669");

// Add placed image to slideshow, at z-order position 1mySlideShow.entDmWorkflow.addItem(myPageItem3);

// After addItem, need to save the new order to slideshow settings.// The slideshow order can be different than the z-ordervar newOrder = getValue( mySlideShow.entDmPreferences.settings, "Order" );newOrder.push( "669" );mySlideShow.entDmPreferences.settings = setValue( mySlideShow.entDmPreferences.settings, "Order", newOrder );

// (check) Get the slideshow settings = ["Order", ["668","667","669"]]ssSettings = mySlideShow.entDmPreferences.settings;alert( "Component settings: " + ssSettings );

// Remove image 2mySlideShow.entDmWorkflow.removeItem( myPageItem2 );

// (check) Get the slideshow settings = ["Order", ["667","669"]]ssSettings = mySlideShow.entDmPreferences.settings;alert( "Component settings: " + ssSettings );

// Remove the SlideShowmyDoc.entDmWorkflow.remove(mySlideShow);

(continues on next page)



Code Fragment 1.6.5 Working with slideshow objects (continued)/**/function getValue( arr, key ){ var val = null; if( key == undefined || key == "" ) return val; for( var i = 0; i < arr.length; ++i ) { if( arr[i][0] == key ) { val = arr[i][1]; break; } } return val;}

/**/function setValue( arr, key, val ){ if( key == undefined || key == "" ) return arr; var bFound = false; for( var i = 0; i < arr.length && !bFound; ++i ) { if( arr[i][0] == key ) { arr[i][1] = val; bFound = true; } } if( !bFound ) arr.push( [key, value] ); return arr;}



Code Fragment 1.6.6 Working with hotspot objects//// create a digital publishing hotspot, a close button and a selected hotspot//


// Create a hotspotvar myHotspot = myDoc.entDmWorkflow.add(myPageItem, "Hotspot");

// Get the hotspot group objectvar myGroup = myHotspot[0];// Get the hotspot layer objectvar myLayer = myHotspot[1];

// Add a close button to the hotspot layervar myClosePageItem = myPage.rectangles.add(myLayer, {geometricBounds:["46pt", "464pt", "82pt", "500pt"]}); var myCloseGroup = myDoc.entDmWorkflow.add(myClosePageItem, "CloseButton");

// Add a selected hotspot to the hotspot layervar mySelectedPageItem = myPage.rectangles.add(myLayer, {geometricBounds:["36pt", "136pt", "136pt", "236pt"]}); var mySelectedHotspot = myDoc.entDmWorkflow.add(mySelectedPageItem, "SelectedHotspot");

// (check) Get layer type = "HotspotLayer"var layerType = myLayer.entDmPreferences.type;alert( "Layer type: " + layerType );

// (check) Get the layer settings = ["Hotspot", groupObject], ["CloseButton", groupObject], // ["SelectedHotspot", groupObject]var layerSettings = myLayer.entDmPreferences.settings; alert( "Layer settings: " + layerSettings );

// Get the hotspot object from the layervar hotspot = getValue( layerSettings, "Hotspot" );

// (check) Get type = "Hotspot"var myType = hotspot.entDmPreferences.type;alert( "Component type: " + myType );

// (check) Get hotspot settings = ["LayerName","Layer 2"], ["AutoPopup", "false"]var hotspotSettings = hotspot.entDmPreferences.settings; alert( "Component settings: " + hotspotSettings );

// Get the closeButton objectvar closeButton = getValue( layerSettings, "CloseButton" );

// Get the selectedHotspot objectvar selectedHotspot = getValue( layerSettings, "SelectedHotspot" );

// Change the hotspot layer name and set auto popupmyGroup.entDmPreferences.settings = [["LayerName", "LayerH1"],["AutoPopup", "true"]];

// (check) Get hotspot settings = ["LayerName"," LayerH1"], ["AutoPopup", "true"]hotspotSettings = myGroup.entDmPreferences.settings;alert( "Component settings: " + hotspotSettings );

// Remove the closeButton. Alternatively remove the entire group to remove the page items// as well { myCloseGroup.remove() }.myDoc.entDmWorkflow.remove(myCloseGroup);

// (check) Get layer settings = ["Hotspot", groupObject], ["SelectedHotspot", groupObject], // ["HotspotPopup", rectangleObject]// The "HotspotPopup" contains the item that previously was the CloseButtonlayerSettings = myLayer.entDmPreferences.settings; alert( "Layer settings: " + layerSettings );




Code Fragment 1.6.6 Working with hotspot objects (continued)// remove the hotspot and the layermyDoc.entDmWorkflow.remove(myGroup, true);

/**/function getValue( arr, key ){ var val = null; if( key == undefined || key == "" ) return val; for( var i = 0; i < arr.length; ++i ) { if( arr[i][0] == key ) { val = arr[i][1]; break; } } return val;}



Code Fragment 1.6.7 Working with scrollable area objects//// Create a digital publishing scrollable area//


// Add a scrollable area, with automatically generated layer namevar myResult= myDoc.entDmWorkflow.add(myPageItem, "ScrollableArea");

// Get the scrollable area group objecyvar myScrollableArea = myResult[0];// Get the scrollable area layer objectvar myLayer = myResult[1];

// Add the scrollable area content page items on the layervar myRect2 = myPage.rectangles.add(myLayer, {geometricBounds:["36pt", "36pt", "136pt", "436pt"], fillColor:myDoc.swatches.item(7)});

// (check) Get layer settings = ["ScrollableArea", groupObject],["ScrollableContent", rectangleObject]var layerSettings = myLayer.entDmPreferences.settings;alert( "Layer settings: " + layerSettings );

// Get the scrollable area group objectvar scrollArea = getValue( layerSettings, "ScrollableArea" );

// (check) Get scrollable area properties = ["LayerName", "layer 2"]var scrollSettings = scrollArea.entDmPreferences.settings;alert( "Component settings: " + scrollSettings );

// (check) Get type = "ScrollableArea"var myType = myScrollableArea.entDmPreferences.type;alert( "Component type: " + myType );

// Change the layer namescrollArea.entDmPreferences.settings = [["LayerName","ScrollLayer1"]];

// (check) Get scrollable area properties = ["LayerName","ScrollLayer1"]scrollSettings = myScrollableArea.entDmPreferences.settings;alert( "Component settings: " + scrollSettings );

// Remove scrollable area component and remove the layermyDoc.entDmWorkflow.remove(myScrollableArea, true);

/**/function getValue( arr, key ){ var val = null; if( key == undefined || key == "" ) return val; for( var i = 0; i < arr.length; ++i ) { if( arr[i][0] == key ) { val = arr[i][1]; break; } } return val;}



Code Fragment 1.6.8 Working with widget objects//// Create a digital publishing Widget component//


// Add a widget componentvar myWidget = myDoc.entDmWorkflow.add(myPageItem, "Widget");

// (check) Get the type = "Widget"var myType = myWidget.entDmPreferences.type;alert( "Component type: " + myType );

// (check) Get the widget settings = ["WidgetID", ""] ["Parameters",""]var widgetSettings = myWidget.entDmPreferences.settings;alert( "Component settings: " + widgetSettings );

// Change the widget datamyWidget.entDmPreferences.settings = [["WidgetID","6268"]];

// (check) Get the widget settings = ["WidgetID","6268"] ["Parameters","<manifest-xml>"]widgetSettings = myWidget.entDmPreferences.settings;alert( "Component settings: " + widgetSettings );

// Remove widgetmyDoc.entDmWorkflow.remove(myWidget);



1.7 EntIssue

1.7.1 Properties

Table 1.7.1 Issue propertiesProperty Type Access Descriptionid string read The Issue id.name string read The Issue name.

1.8 EntMetaDataEntMetaData is a scripting object that manages a collection of properties in the form of key value pairs. EntMetaData objects are proxy objects: changes to the EntMetaData scripting object are not applied directly to the underlying InDesign object. Instead, the changed metadata is kept in memory and used in actions towards the Enterprise system initiated from scripting. These actions do change the underlying InDesign objects and afterwards the EntMetaData object is updated.

1.8.1 KeysThe keys used for the properties in the EntMetaData are the same as the field name properties. For a complete overview, see the Action property list appendix in the Enterprise Admin Guide. Custom properties are identified by their name prefixed with ‘C�’.

Below is a list with common properties, exceptions and sample values.

Table 1.8.1 Common Properties, exceptions and sample valuesKey Type Description Sample ValueCore_ID string Object ID “123”Core_Name string Name “32_Intro”Core_Publication string Brand “WW News”Core_Issue string Issue “2nd Issue”Core_Section string Category “News”Core_Basket string Status “Ready”Type string Object Type “Article”

“Image”LockedBy string In use by “woodwing”RouteTo string Routed to “woodwing”Comment string Comment “This image needs retouching”Format string Object Format “application/indesign”Editions Array of string Editions [ “North, “South” ]Deadline string Deadline “2007-11-05T18:00:00CopyrightMarked string Copyright Marked “false”C_ACUSTOMPROP string Custom property ‘A custom prop’ “A value”

1.8.2 Properties

Table 1.8.2 EntMetadata PropertiesProperty Type Access Descriptionlength number read The number of properties present in the metadata collection object



1.8.3 Methods

Table 1.8.3 EntMetadata MethodsMethod Returns Descriptionset number Add or change the property

Parameter Type Descriptionkey string The property key.value string, Array of string,

number, Array of num-ber, boolean, Array of boolean

The property value.

get string, Array of string, boolean, Array of boolean, number, Array of number

Get the property value for the given key. If the key does not exist, an error will be thrown.

Parameter Type Descriptionkey string The property key.

has boolean Does the property with the given key exist?


remove nothing Remove the property with the given key from the collection.


refresh nothing Refreshes the metadata in this scripting object with the metadata stored in the document. The refresh does not interact with the Enterprise system to retrieve the latest data, but relies on the data delivered to the application through the messag-ing subsystem.

count number Get the metadata value for the given key.item string, Array of string,

boolean, Array of boolean, number, Array of number

Get the property value for the given index or key name. If the key does not exist, an error will be thrown.

Parameter Type Descriptionindex any The index (number) or name (string)



1.8.4 ExampleThe sample iterates over the properties stored in the metadata object.

Code Fragment 1.8.1 Iterating metadata propertiestry{

var doc = app.documents.item(0);

// Access the document’s metadatavar md = doc.entMetaData;

// Get the number of metadata itemsvar n = md.count();

// Iterate the metadata keys and valuesfor( var i = 0; i < md.length; ++i ){

var keyValue = md.item( i );$.writeln( "Key: [" + keyValue[0] + "], Value: [" + keyValue[1] +"]");

}

// Access the value of a specific keyvar mdName = md.get("Core_Name" );$.writeln( "Name: [" + mdName + "]" );var mdID = md.item("Core_ID");$.writeln( "ID: [" + mdID + "]" );

}catch( e){

desc = e.description;num = e.number;alert( "error " + num + ": " + desc );

}

1.9 EntPublication

1.9.1 Properties

Table 1.9.1 Publications propertiesProperty Type Access Descriptionid string read The Brand id.name string read The Brand name.

1.10 EntSection

1.10.1 Properties

Table 1.10.1 Section propertiesProperty Type Access Descriptionid string read The Category id.name string read The Category name.

1.11 Group

1.11.1 Properties

Table 1.11.1 Group propertiesProperty Type Access DescriptionentDmPreferences EntDmPreferences read Access to the digital publishing related properties of the digital pub-

lishing component.entDmWorkflow EntDmWorkflow read Access to digital publishing related actions.



1.12 Layer

1.12.1 Properties

Table 1.12.1 Layer propertiesProperty Type Access DescriptionentDmPreferences EntDmPreferences read Access to the digital publishing related properties of the hotspot or

scrollable area component.

1.13 ManagedAdvert

1.13.1 Properties

Table 1.13.1 ManagedAdvert propertiesProperty Type Access DescriptionentMetaData EntMetaData read Enterprise metadata associated with the advert.pageItem PageItem read Access to the associated InDesign pageitem object.

1.14 ManagedAdverts

1.14.1 Methods

Table 1.14.1 ManagedAdverts methodsMethod Returns Descriptioncount number Returns the number of managed adverts.

1.15 ManagedArticle

1.15.1 Properties

Table 1.15.1 ManagedArticle propertiesProperty Type Access DescriptionentMetaData EntMetaData read Enterprise metadata associated with the article.components Array of PageItem,

Storyread Access to the InDesign page items and stories that are the com-

ponents of this article.

1.15.2 Methods

Table 1.15.2 ManagedArticle MethodsMethod Returns Description

create ID IDS nothing Creates a placed article from the given page items. Depending on the system configura-tion, the given page items can contain images that become part of the article.

Parameter Type DescriptionpageItems Array of

PageItemPage items that will form the article.

[stationery] boolean If true, an article template will be created instead of an article. Default is false.



Table 1.15.2 ManagedArticle MethodsMethod Returns Description

checkIn ID IDS nothing Checks the placed article in the Enterprise system.

Parameter Type Description[pageItems] Array of

PageItemPage items that need to be added as components to the article.

checkOut ID IDS nothing Checks out the placed article.

abortCheckOut ID

IDS

nothing Cancels the checkout of the placed article.

refresh ID IDS nothing Updates the content of the placed article.

detach ID IDS nothing Detaches the article from the layout.

detachComponent nothing Removes a component from a multi-component article. The last component of the article cannot be detached using this method.

Parameter Type DescriptionpageItem PageItem,

StoryPage item that needs to be removed from the multi-component article.

unplacedCompo-nents

Array of string

Returns a list of GUIDs of the components that are not placed in the current layout.

detachFrame ID

IDS

nothing Detach frame from the multi-component article.

Parameter Type DescriptionpageItem PageItem,

StoryPage item or story that will be detached if it is a mul-tiple placed article component.

If the passed page item is not a multiple placed article component Error Code “The object cannot be detached.” will be returned.



1.15.3 ExampleThe sample creates a new managed article based on the selected text frames. It uses the layout’s Brand, Issue, Category and Editions as a basis.

Code Fragment 1.15.1 Creating a new article objecttry{

var doc = app.documents.item(0);

// Access the document’s metadatavar mdDoc = doc.entMetaData;

// Access the document’s articlesvar mas = doc.managedArticles;

// Add a new managed article scripting objectvar maNew = mas.add();var mdNew = maNew.entMetaData;

// Put the article in the layout’s last Editionif( mdDoc.has( "Editions" ) && mdDoc.get( "Editions" ).length > 0 )

mdNew.set( "Editions", mdDoc.get( "Editions" )[mdDoc.get( "Editions" ).length-1] );

// Ask the user for the new namemdNew.set( "Core_Name", prompt( "Name", mdDoc.get("Core_Name") + "-S"+Math.round(Math.random()*10000).toString(10), "Provide a new article (template) name" ) );

// Copy the Brand, Issue and Category from the layoutmdNew.set( "Core_Publication", mdDoc.get( "Core_Publication" ) );mdNew.set( "Core_Issue", mdDoc.get( "Core_Issue" ) );mdNew.set( "Core_Section", mdDoc.get( "Core_Section" ) );

// Pick a statusmdNew.set( "Core_Basket", "Draft text" );

// Set some other metadatamdNew.set( "CopyrightMarked", "true" );mdNew.set( "C_ABOOLEAN", "true" );

// Pick up the selected page itemsvar pgItems = doc.selection;

// You can pass pgItems directly to maNew.create, but in this sample// the items are copied to an array. This can be used to filter pageitemsBuild an array of pageitems from the selection. var inputItems = new Array;for( var i = 0; i < pgItems.length; i++ ){

inputItems.push(pgItems[i]);}

// Turn the scripting object into a real articlemaNew.create( inputItems, false );

}catch( e){

desc = e.description;num = e.number;alert( "error " + num + ": " + desc );

}

1.16 ManagedArticles

1.16.1 Methods

Table 1.16.1 ManagedArticles methodsMethod Returns Descriptioncount number Returns the managed articles.add ManagedArticle Creates a new ManagedArticle scripting object that can serve as the basis for creating a

new article in the Enterprise system.



1.17 ManagedImage

1.17.1 Properties

Table 1.17.1 ManagedImage propertiesProperty Type Access DescriptionentMetaData EntMetaData read Enterprise metadata associated with the image.pageItem PageItem read Access to the associated InDesign page item object.

1.17.2 Methods

Table 1.17.2 ManagedImage methodsMethod Returns Description

create ID IDS nothing Creates an image from the given page item in the Enterprise system.

Parameter Type DescriptionpageItem PageItem Page items that need to be added to the

article.

1.18 ManagedImages

1.18.1 Methods

Table 1.18.1 ManagedImages methodsMethod Returns Descriptioncount number Returns the number of managed images.add nothing Creates a new ManagedImage scripting object that can serve as the basis for creating a new

image in the Enterprise system.

1.19 ManagedLayoutModule

1.19.1 Properties

Table 1.19.1 ManagedLayoutModule propertiesProperty Type Access DescriptionentMetaData EntMetaData read Enterprise metadata associated with the Layout Module.pageItem PageItem read Access to the associated InDesign page item object.

1.20 ManagedLayoutModules

1.20.1 Methods

Table 1.20.1 ManagedLayoutModules methodsMethod Returns Descriptioncount number Returns the number managed adverts.



1.21 Page

1.21.1 Properties

Table 1.21.1 Page propertiesProperty Type Access DescriptionentDmWorkflow EntDmWorkflow read Access to digital publishing related actions.

1.22 PageItem

1.22.1 Properties

Table 1.21.1 PageItem propertiesProperty Type Access Descriptioneditions Array of string read/write The Editions assigned to the page item. When assigning to a text

frame, all linked text frames will get the same set of Editions assigned.

elementLabel string read/write The Element Label assigned to the page item. When assigning to a text frame, all threaded text frames will get the same Element Label.

managedArticle ManagedArticle read Access to the associated ManagedArticle scripting object. Returns nothing if there is no object associated.

managedImage ManagedImage read Access to the associated ManagedImage scripting object. Returns nothing if there is no object associated.

managedAdvert ManagedAdvert read Access to the associated ManagedAdvert scripting object. Returns nothing if there is no object associated.

managedLayout-Module

ManagedLayoutModule read Access to the associated ManagedLayoutModule scripting object. Returns nothing if there is no object associated.

1.22.2 Methods

Table 1.21.2 PageItem propertiesMethod Returns DescriptionplaceObject void Places an Enterprise object in the target object. The contentType of the target object

must match the source object’s. For images, ads, layout modules and image article components the contentType must be ContentType.GRAPHIC_TYPE. For text article components the contentType must be ContentType.TEXT_TYPE.

When placing articles, either the component id must be given of the article compo-nent, or the article must be a single component article; else the place will fail.

Parameter Type Descriptionid string The object’s id.[componentId] string The component’s id.

1.23 Session

1.23.1 Properties

Table 1.22.1 ManagedLayoutModule propertiesProperty Type Access DescriptionactiveServer string read The display name of the server used for the current session. Empty

when not logged in.activeTicket string read The ticket of the current session [6.1.5+].



Table 1.22.1 ManagedLayoutModule propertiesProperty Type Access DescriptionactiveUrl string read The URL of the server used for the current session. Empty when not

logged in.activeUser string read The user name (short name) of the user currently logged in.

Methods

Table 1.22.2 Session propertiesMethod Returns DescriptiongetServers Array of Array

of stringRetrieves a list of servers from the WWSettings.xml file that can be used to login to. The dynamically retrieved server list is currently not supported by this scripting call.

The returned array contains arrays of two strings: the display name and the URL of the server.

login nothing Performs a login to Enterprise system. Throws an exception in case of an error.

Parameter Type Descriptionusername string The user name.password string The password.server string Name of the location to log in to. This is the name of the


logout nothing Performs a logout from the Enterprise system. Throws an exception in case of an error.reLogin nothing Performs a re-login to the Enterprise system. Throws an exception in case of an error.

Useful when changes were made to the configuration, workflow, etc on the server and those value are returned during the login.

forkLogin nothing Performs a login to the Enterprise system based on an existing login. Throws an exception in case of an error.

Parameter Type Descriptionusername string The user name.ticket string The ticket of the existing login.server string Name of the location to log in to. This is the name of the


getTerm string Retrieves the display value of several terms used in the system. Can be used for creating custom UI. For further information on changing terminology including a list of supported terms, see the Admin Guide.

Parameter Type Descriptionterm string The UI term.

getUserGroups Array of string Retrieves a list of user group names. getUsers Array of Array

of stringRetrieves a list of users. The returned array contains arrays of two strings: the user’s short name and the user’s full name.

getPublications Array of Publication

Retrieves a list of all Brands of the current server.

getPublication Publication Retrieves the Brand with the provided name. Throws an exception if the Brand does not exist.

Parameter Type Descriptionpublication string The name of the Brand.




Table 1.22.2 Session properties (continued)Method Returns DescriptiongetIssues Array of Issue Retrieves a list of all Issues of the provided Brand.

Parameter Type Descriptionpublication string The name of the Brand.

getIssue Issue Retrieves the Issue with the provided name from the provided Brand. Throws an exception if the Issue does not exist.

Parameter Type Descriptionissue string The name of the Issue.publication string The name of the Brand.

getSections Array of Section

Retrieves a list of all Categories of the provided Brand and Issue.

Parameter Type Descriptionpublication string The name of the Brand.[issue] string The name of the overruled Issue.

getSection Section Retrieves the Category with the provided name. Throws an exception if the Category does not exist.

Parameter Type Descriptionsection string The name of the Category.publication string The name of the Brand.[issue] string The name of the overruled Issue.

1.24 Story

1.24.1 Properties

Table 1.23.1 Story propertiesProperty Type Access DescriptionmanagedArticle ManagedArticle read Access to the associated ManagedArticle scripting object. Returns

nothing if there is no object associated.

1.25 WorkflowProvides access to workflow actions for a document

1.25.1 Properties

Table 1.24.1 Workflow propertiesProperty Type Access DescriptiondefaultDossier String read/write Name of the Dossier used as the default Dossier in the create work-

flow dialog.



1.25.2 Methods

Table 1.24.2 Workflow MethodsMethod Returns DescriptioncheckIn nothing Checks-in the document to the Enterprise system. Throws an exception in case of an

error.

Use the “Type” key in the EntMetaData to indicate what kind of object should be cre-ated. Possible values are: “Layout”, “Layout Template”, “Layout Module” or “Layout Module Template”.

Parameter Type Description[createFolio] boolean Indicates if a folio file should be exported from the lay-

out (in case it is set to true) or that a dummy folio file should be used (in case it is set to false). Only valid for Layouts that are stored in a DPS Publication Channel. If this parameter is not passed, the code will fall back to the default behavior that is similar to the default selection in the user interface.

abortCheckOut nothing Aborts the check out of the opened document. Throws an exception in case of an error.saveAs Document Stores the document as a new object in the Enterprise system. Throws an exception in

case of an error. Change the metadata before calling saveAs.

Use the “Type” key in the EntMetaData to indicate what kind of object should be cre-ated. Possible values are: “Layout”, “Layout Template”, “Layout Module” or “Layout Module Template”.



saveVersion Document Silently saves a new version of the document to the Enterprise system. Metadata of the document that has been changed by the calling script will not be picked up and sent to the Enterprise system, instead the existing metadata will be sent.

Throws an exception in case of an error.



updateAllCon-tent ID IDS

nothing Updates the contents of all articles and images in the document to match the latest ver-sion. Throws an exception in case of an error.

sendDesignUp-date ID IDS

nothing Sends the layout geometry to all articles placed on the layout. Throws an exception in case of an error.




Table 1.24.2 Workflow Methods (continued)Method Returns Description

placeObject ID

IDS

Array of PageItem

Places an article with template information on the active layer of the layout. The place action will fail when the object is not an article or does not contain template information.

Parameter Type Descriptionid string The object’s id.where Page or

SpreadThe page or spread to place the article on.

position Array of 2 Units

The left top starting point used for placing the article’s template, in the form (top, left). The origin of the place is the top left corner of the page or spread object given.

2. Scripting EventsScripting events allow the integrator to perform scripts on a number of events occurring in the InDesign and InCopy application. Currently scripts can be executed around saving, opening and placing.

2.1 SetupBy default Smart Connection looks for scripts named exactly the same as the event with a ‘.jsx’ extension in the application’s scripts folder. For example the script for the afterPlace event will be afterPlace.jsx. The default locations are listed in the table 2.1.

Table 2.1 Default script locationsWindows C:\Documents and Settings\<username>\Application Data\Adobe\InDesign\Version <x>\Scripts\Scripts Panel

Macintosh ~/Library/Preferences/Adobe InDesign/Version <x>/Scripts/Scripts Panel Should you require a different location for the scripts or different names, then these can be modified by adding a ScriptingEvents element to wwsettings.xml:

Code Fragment 2.1 ScriptingEvents element in WWSettings.xml<SCEnt:ScriptingEvents>

<SCEnt:ScriptsFolderPath target="InCopy">C:\IDScripts</SCEnt:ScriptsFolderPath>

<SCEnt:Script event="afterOpenLayout">bla.jsx</SCEnt:Script><SCEnt:Script event="beforeSaveLayout">bla.jsx</SCEnt:Script>

</SCEnt:ScriptingEvents>

<SCEnt:ScriptingEvents>

<SCEnt:ScriptsFolderPath target="InCopy">Macintosh HD:IDScripts</SCEnt:ScriptsFolderPath><SCEnt:Script event="afterOpenLayout">bla.jsx</SCEnt:Script><SCEnt:Script event="beforeSaveLayout">bla.jsx</SCEnt:Script>

</SCEnt:ScriptingEvents>

2.1.1 ScriptsFolderPath elementThe ScriptsFolderPath element points to the location where scripts are located. Use HFS path names for Mac OS X. It can occur zero or more times.

The optional target attribute indicates in which application the path should be used. Accepted values are InCopy and InDesign. All other values are ignored and have the same result as omitting the attribute. If the element omits this attribute, the path will be used for all applications. An element with a target attribute takes precedence over an element without one.

2.1.2 Script elementDefines per named event which script needs to be run. Event names are equal to the list in the Events section. For events not defined in the WWsettings.xml file, the default name will be used.



2.2 EventsThe following table gives information about an event (and for some events, an example of its use).

Table 2.2 Event descriptionWhen Describes at what moment the event occurs.

Where Describes in what applications the event occurs.

Arguments in Table describing key value pairs set in app.scriptArgs for the event.Arguments out Table describing key value pairs that a script can set in app.scriptArgs for the event.Notes Event related notes.

2.2.1 afterOpenLayout

Table 2.2.1 afterOpenLayout detailsWhen After opening a layout

Where InDesign, InDesign ServerArguments in n/aArguments out n/aNotes

2.2.2 afterOpenArticle

Table 2.2.2 afterOpenArticle detailsWhen After opening an article

Where InCopyArguments in n/aArguments out n/aNotes

2.2.3 beforeSaveLayout

Table 2.2.3 beforeSaveLayout detailsWhen Before sending a layout to the Enterprise system.

Where InDesign, InDesign ServerArguments in Key Description

Core_ID The object id of the layout being saved.Core_Name New name.Core_Publication New Brand.Core_Issue New Issue.Core_Section New Section.Editions New Edition(s)Core_Basket New StatusRouteTo New routing




Table 2.2.3 beforeSaveLayout detailsArguments out Key Description

errorId Sets the error id to a non-zero value to abort the save.errorMessage The message to be shown to the user. Requires the errorId to be set.

Notes The script can change the document. Changes will be saved and sent to the server.

Code Fragment 2.2.3 Using beforeSaveLayoutvar msg = 'ID: ' + app.scriptArgs.get( 'Core_ID' ) + '\n';msg += 'Name: ' + app.scriptArgs.get( 'Core_Name' ) + '\n';msg += 'Publication: ' + app.scriptArgs.get( 'Core_Publication' ) + '\n';msg += 'Issue: ' + app.scriptArgs.get( 'Core_Issue' ) + '\n';msg += 'Section: ' + app.scriptArgs.get( 'Core_Section' ) + '\n';msg += 'Editions: ' + app.scriptArgs.get( 'Editions' ) + '\n';msg += 'Status: ' + app.scriptArgs.get( 'Core_Basket' ) + '\n';msg += 'RouteTo: ' + app.scriptArgs.get( 'RouteTo' ) + '\n';alert( msg );// Preferred way is to set the error id and messageapp.scriptArgs.set( 'errorId', '12366' );app.scriptArgs.set( 'errorMessage', 'Cannot save now.' );// An exception that is not caught results in an errorthrow Error('This is an unexpected error');

2.2.4 afterSaveLayout

Table 2.2.4 afterSaveLayout detailsWhen After sending a layout to the Enterprise system.

Where InDesign, InDesign ServerArguments in Key Description

Core_ID The object id of the layout that was saved.

Arguments out n/aNotes

2.2.5 beforeSaveArticle

Table 2.2.5 beforeSaveArticle detailsWhen Before sending an article to the Enterprise system.

Where InDesign, InCopy, InDesign ServerArguments in Key Description

Core_ID The object id of the article being saved.Core_Name New name.Core_Publication New Brand.Core_Issue New Issue.Core_Section New Section.Editions New Edition(s).Core_Basket New Status.RouteTo New routing.




Table 2.2.5 beforeSaveArticle detailsArguments out Key Description

errorId Set the error id to a non-zero value to abort the save.errorMessage The message to be shown to the user. Requires the errorId to be set.

Notes Don’t change the text of the article at this stage. Changes are not sent to the server. Use beforeExportAr-ticle instead.

Code Fragment 2.2.5 Using beforeSaveArticlevar msg = 'ID: ' + app.scriptArgs.get( 'Core_ID' ) + '\n';msg += 'Name: ' + app.scriptArgs.get( 'Core_Name' ) + '\n';msg += 'Publication: ' + app.scriptArgs.get( 'Core_Publication' ) + '\n';msg += 'Issue: ' + app.scriptArgs.get( 'Core_Issue' ) + '\n';msg += 'Section: ' + app.scriptArgs.get( 'Core_Section' ) + '\n';msg += 'Editions: ' + app.scriptArgs.get( 'Editions' ) + '\n';msg += 'Status: ' + app.scriptArgs.get( 'Core_Basket' ) + '\n';msg += 'RouteTo: ' + app.scriptArgs.get( 'RouteTo' ) + '\n';alert( msg );// Preferred way is to set the error id and messageapp.scriptArgs.set( 'errorId', '12366' );app.scriptArgs.set( 'errorMessage', 'Cannot save now.' );// An exception that is not caught results in an errorthrow Error('This is an unexpected error');

2.2.6 afterSaveArticle

Table 2.2.6 afterSaveArticle detailsWhen After sending an article to the Enterprise system.

Where InDesign, InCopy, InDesign ServerArguments in Key Description

Core_ID The object id of the article that was saved.


2.2.7 beforeExportArticle

Table 2.2.7 beforeExportArticle detailsWhen Before creating the XML representation of an article on disk.

Where InDesign, InCopy, InDesign Server.Arguments in n/aArguments out n/aNotes Changes made to the text will be part of the export.

2.2.8 afterExportArticle

Table 2.2.8 afterExportArticle detailsWhen After creating the XML representation of an article on disk.

Where InDesign, InCopy, InDesign Server.(Continues on next page)



Table 2.2.8 afterExportArticle details (continued)Arguments in Key Description

Core_ID The object id of the article that was exported.


2.2.9 beforeExportArticleTemplate

Table 2.2.9 beforeExportArticleTemplate detailsWhen Before creating the XML representation of an article template on disk.

Where InDesign, InCopy, InDesign Server.Arguments in n/aArguments out n/aNotes Changes made to the text will be part of the export, as well as changes made to the layout in InDesign

(Server) that will be part of the template information.

2.2.10 afterExportArticleTemplate

Table 2.2.10 afterExportArticleTemplate detailsWhen After creating the XML representation of an article template on disk.

Where InDesign, InCopy, InDesign Server.Arguments in Key Description

Core_ID The object id of the article that was exported.


2.2.11 beforeCreateLayout

Table 2.2.11 beforeCreateLayout detailsWhen Before creating a new layout in the Enterprise system. This includes Save As.

Where InDesign, InDesign Server.Arguments in n/aArguments out n/aNotes Changes can be made to the document, these will be saved and sent to the Enterprise system.

2.2.12 afterCreateLayout

Table 2.2.12 afterCreateLayout detailsWhen After creating a new layout in the Enterprise system. This includes Save As.Where InDesign, InDesign Server.




Table 2.2.12 afterCreateLayout details (continued)Arguments in Key Description

Core_ID The object id of the layout that was created.

Arguments out n/aNotes Changes can be made to the document, these will be saved and sent to the Enterprise system.

2.2.13 beforeCreateLayoutTemplate

Table 2.2.13 beforeCreateLayoutTemplate detailsWhen Before creating a new layout template in the Enterprise system. This includes Save As.

Where InDesign, InDesign Server.Arguments in n/aArguments out n/aNotes Changes can be made to the document, these will be saved and sent to the Enterprise system.

2.2.14 afterCreateLayoutTemplate

Table 2.2.14 afterCreateLayoutTemplate detailsWhen After creating a new layout template in the Enterprise system. This includes Save As.Where InDesign, InDesign Server.Arguments in Key Description

Core_ID The object id of the layout template that was created.

Arguments out n/aNotes Changes can be made to the document, these will be saved and sent to the Enterprise system.

2.2.15 beforeCreateArticle

Table 2.2.15 beforeCreateArticle detailsWhen Before sending a new article to the Enterprise system.Where InDesign, InCopy, InDesign Server.Arguments in n/aArguments out n/aNotes Don’t change the text of the article at this stage. Changes will not be sent to the server. Use beforeExport

Article instead.

2.2.16 afterCreateArticle

Table 2.2.16 afterCreateArticle detailsWhen After sending a new article to the Enterprise system.Where InDesign, InCopy, InDesign Server.Arguments in Key Description

Core_ID The object id of the article that was created.

Arguments out n/a



Table 2.2.16 afterCreateArticle detailsNotes

2.2.17 beforeCreateArticleTemplate

Table 2.2.17 beforeCreateArticle detailsWhen Before sending a new article template to the Enterprise system.Where InDesign, InCopy, InDesign Server.Arguments in n/aArguments out n/aNotes Don’t change the text of the article template at this stage. Changes will not be sent to the server. Use

beforeExportArticle instead.

2.2.18 afterCreateArticleTemplate

Table 2.2.18 afterCreateArticleTemplate detailsWhen After sending a new article template to the Enterprise system.Where InDesign, InCopy, InDesign Server.Arguments in Key Description

Core_ID The object id of the article template that was created.


2.2.19 afterPlace

Table 2.2.19 afterCreateArticleTemplate detailsWhen After placing an object.Where InDesign, InDesign Server.Arguments in Key Description

pageitem The id of the frame the object was placed into.

Arguments outNotes

2.2.20 beforeDetachArticle

Table 2.2.20 beforeDetachArticle detailsWhen Before detaching an article from a layout. A template of placed components of the article was generated

for scripter to use before detaching the article component.Where InDesign, InDesign Server.



Table 2.2.20 beforeDetachArticle details (continued)Arguments in Key Description

Core_ID The object ID of the article that will be detached.templateGeoFilePath The template file path.

Arguments out n/aNotes A template with all placed components of the article will be generated in the file path: templateGeoFile-

Path, and will be deleted after the event.

2.2.21 afterDetachArticle

Table 2.2.21 afterDetachArticle detailsWhen After detaching an article from a layout.Where InDesign, InDesign Server.Arguments in Key Description

Core_ID The object id of the article template that was created.

Arguments out n/aNotes This event is only broadcasted when using the Detach Article action, not when detaching by deleting the

article from the layout.

2.2.22 afterCreateJump

Table 2.2.22 afterCreateJump detailsWhen After creating a Smart Jump article.

Where InDesign.Arguments in Key Description

sourceDocument The object id of the layout from where the Smart Jump starts.sourceStory The story id of the first component of the Smart Jump story.sourceContinuationStory The story id of the continuation element belonging to the first

component of the Smart Jump.[destinationDocument] The object id of the layout where the Smart Jump lands.[destinationStory] The story id of the second component of the Smart Jump story.[destinationContinuationStory] The story id of the continuation element belonging to the second

component of the Smart Jump.

Arguments out n/aNotes destinationDocument, destinationStory and destinationContinuationStory are optional when for

example using the “Create Jump From Here” command.

Code Fragment 2.2.22 Using afterCreateJumpvar msg="Source ID: " + app.scriptArgs.get("sourceDocument") + "\n";msg+="Source Story: " + app.scriptArgs.get("sourceStory") + "\n";msg+="Source Continuation: "+app.scriptArgs.get("sourceContinuationStory") + "\n";if( app.scriptArgs.isDefined( "destinationDocument" ) ){ msg+="Destination ID: " + app.scriptArgs.get("destinationDocument") + "\n"; msg+="Destination Story: " + app.scriptArgs.get("destinationStory") + "\n"; msg+="Dest. Continuation:"+app.scriptArgs.get("destinationContinuationStory")+"\n";}alert( msg );



2.2.23 afterCreateContinuationElement

Table 2.2.23 afterCreateContinuationElement detailsWhen After creating a continuation element for a Smart Jump article.

Where InDesign.Arguments in Key Description

document The object id of the layout from where the element is created on.parentStory The story id of the component of the Smart Jump story the element

belongs to.[continuationFromStory] The story id of the continuation from element belonging to the compo-

nent of the Smart Jump story.[continuationOnStory] The story id of the continuation on element belonging to the component

of the Smart Jump story.

Arguments out n/aNotes The event is not sent when creating a Smart Jump. In that case the afterCreateJump event is sent.

Code Fragment 2.2.23 Using afterCreateContinuationElementvar msg="Document: " + app.scriptArgs.get( "document" ) + "\n";msg+="Parent Story: " + app.scriptArgs.get( "parentStory" ) + "\n";if( app.scriptArgs.isDefined( "continuationToStory" ) ) msg+="Continuation To Story: "+app.scriptArgs.get("continuationToStory")+"\n";if( app.scriptArgs.isDefined( "continuationFromStory" ) ) msg+="Continuation From Story: "+app.scriptArgs.get("continuationFromStory")+"\n";alert( msg );

2.2.24 afterRefreshArticle

Table 2.2.24 afterRefreshArticle detailsWhen After refreshing the XML representation of an article from disk.

Where InCopy.Arguments in Key Description

Core_ID The object id of the article that was refreshed.


2.2.25 beforeImportImage

Table 2.2.25 beforeImportImage detailsWhen Before importing (planned) image type files when synchronizing planned layouts and adverts.

Where InDesign.Arguments in n/aArguments out n/aNotes This event is not called when importing image type files from Smart Connection panels.



Code Fragment 2.2.25 Using beforeImportImagevar msg="ID: " + app.scriptArgs.get( "Core_ID" ) + "\n";msg+="Name: " + app.scriptArgs.get( "Core_Name" ) + "\n";msg+="Brand: " + app.scriptArgs.get( "Core_Publication" ) + "\n";msg+="Issue: " + app.scriptArgs.get( "Core_Issue" ) + "\n";msg+="Section: " + app.scriptArgs.get( "Core_Section" ) + "\n";msg+="Editions: " + app.scriptArgs.get( "Editions" ) + "\n";msg+="Status: " + app.scriptArgs.get( "Core_Basket" ) + "\n";msg+="RouteTo: " + app.scriptArgs.get( "RouteTo" ) + "\n";msg+="File type: " + app.scriptArgs.get( "Type" ) + "\n";msg+="File format: " + app.scriptArgs.get( "Format" ) + "\n";msg+="Frame ID: " + app.scriptArgs.get( "pageitem" ) + "\n";alert( msg );



2.3 TroubleshootingIt is possible to debug scripts on a per event basis when an event occurs. To debug the afterOpenLayout event:

<SCEnt:ScriptingEvents> <SCEnt:Script debug="true" event="afterOpenLayout">bla.js</SCEnt:Script> <SCEnt:Script event="beforeSaveLayout">bla.jsx</SCEnt:Script></SCEnt:ScriptingEvents>

The events mechanism has its own logging which can be enabled through the WWsettings.xml file. This will show which script will be run and whether running is successful:

<Logging level="0" allareas="0"> <Area name="ScriptingEvents"/></Logging>



3. Smart Connection Custom Menu ItemsThe context menu of the Documents pane in the Smart Connection panel can be extended with custom menu items. These custom menu items are provided with information by Smart Connection about the selected items, giving the custom menu items the ability to control the enabling of the items. The information passed by Smart Connection is all data from the query result for the selected itema. Custom menu items work in both list and thumbnail view, althought the information passed to the script in thumbnail view is limited.

Custom menu items are added and controlled through a script. The script is placed in the Startup Scripts folder in either the application’s scripts folder or in the user’s scripts folder. The script locations are listed in the table 3.

Table 3. Script locationsWindows C:\Documents and Settings\<username>\Application Data\Adobe\InDesign\Version x\<language>\Scripts\

Startup ScriptsC:\Program Files\Adobe\Adobe InDesign CC\Scripts\Startup Scripts

Macintosh ~/Library/Preferences/Adobe InDesign/Version x/<language>/Scripts/Startup Scripts/Applications/Adobe InDesign CC/Scripts/Startup Scripts

Below is an annotated sample script that adds 3 custom menu items with custom enabling. Important notes:• Smart Connection expects the naming of the functions in the ScriptMenu object and of the ScriptMenu instance

as shown in the script.• There can only be one instance of the ScriptMenu object, meaning that if you have several customizations adding

custom menu items, you have to think out a framework for adding custom menu items from these customiza-tions.

• The targetengine must be “scriptmenu”.• The name of the script file does not matter.• Any errors occuring need to handled by the script as Smart Connection will simply ignore any errors occuring dur-

ing the execution of the script functions.

Code Fragment 3.1.1 Sample custom menu items script#targetengine "scriptmenu"

function ScriptMenu(){

// initialize the member function references // for the class prototype if (typeof(_ScriptMenu_prototype_called) == 'undefined') { _ScriptMenu_prototype_called = true; ScriptMenu.prototype.getDebugConfig = getDebugConfig; ScriptMenu.prototype.getActions = getActions; ScriptMenu.prototype.updateState = updateState; ScriptMenu.prototype.run = run; }

/** * Tells Smart Connection whether the calls need to be debugged * * @return array of bool * ----------------------------------------- * debug update? debug run? show error alerts * ----------------------------------------- * [ false, false false ] */ function getDebugConfig() { return [ false, false, false ]; }




Code Fragment 3.1.1 Sample custom menu items script (continued) /** * Provides a list of actions this script supports to the caller * * @return array of arrays of string * ----------------------------------------- * unique id name * ----------------------------------------- * [ [ "action1", "initialName" ], * [ "action2", "initialName" ], * [ "action3", "initialName" ] ] */ function getActions() { var r = [ [ "1", "Item 1" ], [ "2", "Item 2" ], [ "3", "Item 3" ] ]; return r; }

/** * update the state of the actions * * @return array of arrays * -------------------------------------------------------------- * unique id name enabled checked * -------------------------------------------------------------- * [ [ "action1", "name", true, false ], * [ "action2", "name", false, false ], * [ "action3", "name", true, true ] ] */ function updateState( selectedItemsJson ) { var selectedItems = eval( selectedItemsJson ); // selectedItems is an array of objects, each representing a selected item for( var i = 0; i < selectedItems.length; ++i ) { var selItem = selectedItems[i]; // The type of item that is selected. Either 'normal' or 'component'. // The available properties (see below) depend on this type. var itemType = selItem.itemType; // Each item has key/value pairs representing the fields // shown in the query result. These are added as properties // to the object var id = selItem.values.ID; var t = selItem.values.Type;

// Check a certain field exists var f = ""; if( selItem.values.hasOwnProperty( "Format" ) ) f = selItem.values.Format;

// Iterate over all properties var vals = selItem.values; for( var k in vals ) { var v = vals[k]; } } // Build a return value, normally based on the selected items. var r = [ [ "1", "Item 1", true, false ], [ "2", "Item 2", false, false ], [ "3", "Item 3", true, true ] ]; return r; }

(continues on next page)Code Fragment 3.1.1 Sample custom menu items script (continued)



/** * execute the given action. actionId is as defined by getActions * Script is responsible for handling all errors. */ function run( selectedItemsJson, actionId ) { // Do something alert( actionId ); }

}

var scriptMenu = new ScriptMenu;

4. Overrule placement of Articles and DossiersThe scripting possibilities of this chapter are introduced in Smart Connection v8.3.

With scripting code it is possible to overrule the placement of whole articles and it is possible to implement the placement of Dossiers. It is currently not possible to overrule the placement of images and article components.

The script in which this can be implemented should be placed into the Startup Scripts folder in either the application’s scripts folder or in the user’s scripts folder. The script locations are listed in the table below.

Table 3. Script locationsWindows C:\Documents and Settings\<username>\Application Data\Adobe\InDesign\Version x\<language>\Scripts\

Startup ScriptsC:\Program Files\Adobe\Adobe InDesign CC\Scripts\Startup Scripts

Macintosh ~/Library/Preferences/Adobe InDesign/Version x/<language>/Scripts/Startup Scripts/Applications/Adobe InDesign CC/Scripts/Startup Scripts

The script should have the following properties:

• The target engine must be “placeoverride” (#targetengine “placeoverride”)• The name of the object must be “PlaceOverride” (function PlaceOverride) • There may only be one object of the PlaceOverride class and this needs to have the name “placeOverride” (var pla-

ceOverride = new PlaceOverride).• The PlaceOverride class needs to have the following functions:

The following script shows the parameters to the user that are passed to the placeItems call.

At the end we tell Smart Connection that we handled the placement, but since nothing is placed the place gun will not be unloaded.

Code Fragment 4.1 Sample Overrule placement of Articles and Dossiers



#targetengine "placeoverride"

function PlaceOverride(){ // initialize the member function references // for the class prototype if (typeof(_PlaceOverride_prototype_called) == 'undefined') { _PlaceOverride_prototype_called = true; PlaceOverride.prototype.getDebugConfig = getDebugConfig; PlaceOverride.prototype.placeItems = placeItems; PlaceOverride.prototype.canPlaceItems = canPlaceItems; }

// - getDebugConfig - function getDebugConfig() { // Tell Smart Connection not to debug, but to show alerts. return [ false, false, true ]; }

// - canPlaceItems - function canPlaceItems( itemsToPlaceJson, targetLayoutJson, targetItem ) { // Tell Smart Connection that we are able to place the passed item. return true; }

// - placeItems - function placeItems( itemsToPlaceJson, targetItem, targetPage, targetPointJson ) { // Collect information about the passed parameters and show it to the user // itemToPlaceJson contains about the item to be placed. var message = "Json input itemToPlaceJson : \n" + itemsToPlaceJson +"\n\nInterpreted items from Json: \n";

// Interpret the Json var itemsToPlace = eval( itemsToPlaceJson ); for( var i=0 ; i < itemsToPlace.length ; i++ ) { message = message + "Item " + i + ":\n"; message = message + " itemID = " + itemsToPlace[i].itemID + "\n"; message = message + " type = " + itemsToPlace[i].type + "\n"; message = message + " format = " + itemsToPlace[i].format + "\n"; message = message + " guid = " + itemsToPlace[i].guid + "\n\n"; }

// Show the collected information about the items to be placed to the user. alert( message );

// Show the id of the target item to the user. This is passed as string with the targetItem parameter. alert( "targetItem : \n " + targetItem );

// Show the number of the target page to the user. This is passed as string with the targetPage parameter. alert( "targetPage : \n " + targetPage );

// targetPointJson contains about the target position. var pos_message = "Json input targetPointJson :\n" + targetPointJson +"\n\nInterpreted points from Json:\n";

// Interpret the Json var targetPos = eval( targetPointJson ); for( var i=0 ; i < targetPos.length ; i++ ) { pos_message = pos_message + "Point " + i + ":\n"; pos_message = pos_message + " x = " + targetPos[i].x + "pt\n"; pos_message = pos_message + " y = " + targetPos[i].y + "pt\n\n"; }

// Show the collected information about the target position. alert( pos_message );

// Tell Smart Connection that we handled the placement, but we did not place anything. // So the placegun is not unloaded. var arr = new Array(); return [ true, arr ]; }}

var placeOverride = new PlaceOverride;

Smart Connection Scripting and Events Guide for Adobe CC · 2019-01-15 · Scripting and Events...

Documents

Transcript of Smart Connection Scripting and Events Guide for Adobe CC · 2019-01-15 · Scripting and Events...