Scripting Support For Links

ecLink Class

From 2022, an ecLink class has been added to the scripting module to enhance the scriptability in the creation, inspection and modification of links. This represents an EasyCatalog link, either text or frame based. An ecLinks collection exists on most InDesign layout objects.

Basic Properties

A link is described using 3 basic properties:

• ecDatasource – The name of a data source.
• ecFieldName  – The name of a field.
• ecKey – Record key field value.

Additional Properties

Additional properties control the behaviour of the link and store internal data:

• ecComputedCommand – The Computed Field command.
• ecParentField – The parent Field object if available, or null.
• ecLinkType – Type of link:

• ecContentType – Content type of the link:

• ecLinkStatus – Status of the link:

• ecParentField – The parent Field object if available, or null.

Methods

• add – Add a new Link to a Collection.
• find  – Find links matching the given properties.
• findRecords  – Find records belonging to links matching the given properties.

ecLink Collections

The collection is added to most InDesign basic types. The example below illustrates use of ecLinks within a document and selection, but this can equally applies to spreads, pages, pageItems:

// Update all links in the selection
      for (item = 0; item < app.selection.length; ++item) {
         myLinks = app.selection[item].ecLinks.everyItem().update();
     }
      // Update links for a specific datasource
      linkArray = app.activeDocument.ecLinks.everyItem().getElements();
      for (i = 0; i < linkArray.length; ++i) {
          myLink = linkArray[i];
            if (myLink.ecDatasource == "XXX" && myLink.ecLinkType == LinkType.FIELD && (myLink.ecLinkstatus == LinkStatus.OK || myLink.ecLinkstatus == LinkStatus.OUT_OF_DATE)) {
                myLink.update();
            }
          }
      }

Optimizing Access

When using collections, InDesign rebuilds the collection each time a member of the collection is accessed. Using a static array is almost always faster than using collections. So rather than:

myLinks = app.activeDocument.ecLinks
for (i = 0; i < myLinks.count(); ++i) {
   myLink = myLinks.item(i);
}

Use the more efficient form, which scans the document once:

linkArray = app.activeDocument.ecLinks.everyItem().getElements();
for (i = 0; i < linkArray.length; ++i) {
   myLink = linkArray[i];
}

Examples

The Scripts Panel menu has an option called “Install EasyCatalog Sample Scripts”, which copies some useful example scripts into your Scripts Folder.

Creating A link

// Tag the selected text or frame
     newLink = app.selection[0].ecLinks.add( {
         ecKey:"key",
         ecDatasource:"datasource",
         ecFieldName:"field" }
     )
     // Tag an entire story
     app.activeDocument.stories.item(0).ecLinks.add({
         ecKey:"key",
         ecDatasource:"datasource",
         ecFieldName:"field"}
     )

Removing all links of the first page

app.activeDocument.pages[0].ecLinks.everyItem().remove();

Removing all instances of the seleted field

// Gets the first selected link and removes all field of that name in the document
myLinks = app.selection[0].ecLinks
x = myLinks.item(0);

linkArray = app.activeDocument.ecLinks.find( {
    ecLinkType: LinkType.FIELD,
    ecField : x.ecField
} );

for (i = 0; i < linkArray.length; ++i) {
    linkArray[i].remove();
}

Replacing Fields

doc = app.activeDocument;

// Search for a all fields in the document of the given name and replace with another name.
searchFor = ""
replaceWith = ""

// Function to perform the replace
function doReplaceFields() 
{
    linkArray = doc.ecLinks.find( { ecLinkType: LinkType.FIELD, ecField : searchFor });
    numReplaced = 0;

    for (i = 0; i < linkArray.length; ++i) {
        theLink = linkArray[i];
        theLink.ecField = replaceWith;
        theLink.update();
        numReplaced = numReplaced + 1;
    }
    alert("Replaced " + numReplaced + " instances of " + searchFor + " replaced with " + replaceWith + "")    
}

// Create an array of unique field names
linkArray = doc.ecLinks.find( { ecLinkType: LinkType.FIELD });
uniqueFields = Array()

for (i = 0 ; i < linkArray.length; ++i) {
    found = false;
    theLink = linkArray[i];
    for (j = 0; j < uniqueFields.length; ++j) {
        if (uniqueFields[j] == theLink.ecField) {
            found = true;
        }
    }
    if (found == false) {
        uniqueFields.push(theLink.ecField);
    }
}
if (uniqueFields.length == 0) {
    alert("No fields found");
    exit();
}

if (uniqueFields.length == 1) {
    alert("Only one field found");
    exit();
}
// Present the replace dialog
var w = new Window ("dialog", "Replace Fields", undefined, {closeButton: false});
w.alignChildren = "right"; 

var main = w.add ("group");
main.add ("statictext", undefined, "Replace Field: ");
var group = main.add ("group {alignChildren: 'left', orientation: ’stack'}");
var list = group.add ("dropdownlist", undefined, uniqueFields);
list.preferredSize.width = 220; list.preferredSize.height = 20;
list.selection = 0;

var main2 = w.add ("group");
main2.add ("statictext", undefined, "With Field: ");
var group2 = main2.add ("group {alignChildren: 'left', orientation: ’stack'}");
var list2 = group2.add ("dropdownlist", undefined, uniqueFields);
list2.preferredSize.width = 220; list2.preferredSize.height = 20;
list2.selection = 0;

var buttons = w.add ("group")
buttons.add ("button", undefined, "Cancel"); buttons.add ("button", undefined, "OK");

if (w.show () != 1) { 
    exit();
}
searchFor = list.selection.text;
replaceWith = list2.selection.text;

// Call the replace function as one undo step
app.doScript(doReplaceFields, ScriptLanguage.JAVASCRIPT, undefined, UndoModes.FAST_ENTIRE_SCRIPT, "Replace Fields")

The post Scripting Support For Links appeared first on 65bit Software.