Table of Contents

From PowerScripts version 3.6.0 you will be able to send commands to PowerScripts to run and execute individual scripts within PowerScripts

Boot Loader

First and most importantly, Illustrator runs multiple instances of its ExtendScript engine, In order to access powerscripts your will need to add the following to the beginning of your script.

This will

//
   
// If  _powerScriptCommand is undefined then send message  
// to PowerScripts to run this script and exit.

if(typeof _powerScriptCommand === 'undefined'){
	// get this filename
	var thisFilename = $.fileName;

	// escape shashes and '
	thisFilename = thisFilename.replace(/\\/g, '\\\\').replace(/\'/g, '\\\'')

	// Send JSON string with command "evalFile"
	var lib = new ExternalObject( "lib:PlugPlugExternalObject");
	var eventObj = new CSXSEvent();
	eventObj.type = "nz.co.o2creative.events.lwAction";	
	eventObj.data = '{"action": "evalFile", "data": {"filename": "' + thisFilename + '"}}';
	eventObj.dispatch(); 

	// exit
	return; 
}

//

Once your script is loaded in the same instance as PowerScripts, you can then run commands using the functions below, All actions are asynchronous

Functions

These built-in functions allow you to send commands and actions to powerScripts


_powerScriptActions(scriptID, actions, savedSetting, callback)

Runs a set of one or more actions on a PowerSciprts,

Parameters

Description Actions are predefined in each PowerScript. To get a list of actions see [getActions] below

Callback return value

{object}

_powerScriptCommand(scriptID, command, data, callback)

Send an indivudual command to PowerScripts .

Parameters

Callback return value

{object}

_powerScriptCommands(commands, callback, stopOnFail)

Run multiple commands.

Parameters

Callback return value

    // Success
     {
        success: true,
        results: []   // an array of results - see default command list below for return values for each command
     }
     
     // on Failure
     {
            success: false,
            step: index,  // index where the command fialed
            error: 'Failed at command 2",   // Error message
            failedCommand: {},  // the failed command object
            results: []   // an array of results - see default command list below for return values for each command
     }

JSON

Support for the standardJSON.parse and JSON.stringify are included


Debugging

Because your script will run in a different instance, you will not be able to run a debugging session to step through errors. Here are some functions to help with debugging.

_alert(message, title, isError, asDialogue)

Display an alert box and gives you a detailed output of the message, If the message is an object or an array it will show its member and properties.

Parameters

Description

Object and arrays will be correctly displayed


_console

To display a console in a new dialogue while your code is running use _console.log(object). You do not need to call console.show() first as calling console,log() will automatically display the console.

For a compact view use JSON.stringify, i.e. console.log( JSON.stringify(var) );


Default Command List

Below is a list of default commands, which are denoted by the square brackets.

Individual PowerScripts can extend these and have more commands, so check the documentation for each PowerScript to see if additional commands are available.

When the (not required) call _powerScriptCommand with an empty string or null

[getPowerScripts]

Gets a list of enabled and installed PowerScripts

Parameters

Callback Return value

   object {
         success: true,
         data: [  
            {
                name: "",  
                uuid:"",
                group: ""
            },
            ......
          ] 
         }

[load]

Loads the script specified in scriptID

Parameters

Callback Return value

  object {success: true/false}

[getValues]

Gets the values of the controls in the current PowerScript panel

Parameters

Callback Return value

  object {
      uuid: "",  // string containing the UUID of the loaded PowerScript
      values: [   // array of values 
             name: "",  // string containing the name of the control
             type: "" ,    // string containing the control type
             value: ??   // Value of the control, will varry depending on the type of control
         ]
      }

[setValues]

Sets the values of the controls in the current PowerScript panel

Set values should be in the same format as you retrieve from getValues, it is therefore recommended to call the command [getValues] and copy the format . Note that is the control does not exist it will be ignored

Data can be in a supplied range of formats where obj = {name: “”, type: “”, value: ?}

* Some controls are preset to not automatically update their values when using setValues, such as tables that automatically load and save data from the hard drive. You can use forceUpdate to change these controls, but be aware that this might also permanently save the new table data to the hard drive. Use forceUpdate with caution.

Parameters

Callback Return value

   object {success: true/false}

[getSavedSettings]

Returns a list of saved settings for the currently loaded PowerScirpt. see using saved settings

Parameters

Callback Return value

   object {
         success: true,
         data: ["name", "name", "name" ] // array of saved setting names
         }

[loadSavedSetting]

Loads a user saved setting by name. see using saved settings

Parameters

Callback Return value

   object {success: true/false}  //Retruns false if the name is not found

[resetSettings]

LoReloads the default settings for the loaded PowerScript (As if it was first loaded)

Parameters

Callback Return value

   object {
         success: bool,      // false: no script loaded 
         ready:  bool,    // script loaded and ready to run commands
         alreadyLoaded:  // true if script was already loaded (will always return false as its was reloaded) 
     }

[getActions]

Actions are specific to each individual PowerScripts. They are like commands but can also be used for Hot Keys and Quick Keys. So using actions can achieve the same functionality as Hot Keys and Quick Keys. Use the _powerScriptActions function to run an action.

Parameters

Callback Return value

   object {
         success: true,
         data: [  // array of action 
            {
                id: "",  // String containing the ID for the action - you will need this
                scriptid:"", // String contains a special scriptID, used internally
                type: "",  // the type of action which is "run" , "event" , "click",
                placeholder:"", // Used for HotKeys/Quick Keys inputs, describes the data that is expected
                label: "" // Used for HotKeys/Quick Keys, a label/description for the preset
            },
            ......
          ] 
         }

[run]

Run the current PowerScript. Check the documentation for each PowerScript to see what run arguments are required.

Parameters

Callback Return value

  
   object {
         success: true,  // Always true as the command ran, but see data as script may fail
         data: ????  // Will vary depending on the script
    }

Examples

//

// Dimensions Script
var scriptID = '2765bf7d-9500-4eb4-8e10-36f12e42eeac'; 

_powerScriptCommands(
	[
		{
			scriptID:scriptID,	
			action: '[load]',
			data: {}
		},
		{
			scriptID:scriptID,
			action: '[loadSavedSetting]',
			data: {name: '10 percent'}
		},
		{
			scriptID:scriptID,
			action: '[run]',
			data: {args:{'create': 'top', _alwaysrun:true}}
		},
		{
			scriptID:scriptID,
			action: '[run]',
			data: {args:{'createxxx': 'left', _alwaysrun:true}}
		},
		{
			scriptID:'08939b67-ff69-4d8d-b340-fed9227e2d07',
			action: '[load]'
		},
	],
	function onCompleted(result){
		if(result.success){
			alert('Successful');
		} else {
			_console.log(result);
			alert(result.error);
		}
	},
	true // stop on failure
);

//


//

_powerScriptCommand('', '[getSavedSettings]',{}, function onCompleted(result){
	_console.log(result);
});

//

Result

{
   success: true (bool),
   data: ["100 percent inch+mm", "floorplans", "100% red lines", "10 percent"] (Array:4),
} (object)

//

_powerScriptCommand('', '[getValues]',{}, function onCompleted(result){
	_console.log(result);
});

//

Result

{
   success: true (bool),
   data: {
      uuid: "8024ee3e-6bf0-495d-a04c-0d7236405e70" (String:36),
      values: [
         {
            name: "_accordions" (String:11),
            type: "accordions" (String:10),
            value: {} (object EMPTY),
         } (object),
         {
            name: "markStyle" (String:9),
            type: "select" (String:6),
            value: "0" (String:1),
         } (object),
         {
            name: "length" (String:6),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         {
            name: "offset" (String:6),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         {
            name: "bleed" (String:5),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         ....