Templator is a PowerScript to automatically open document templates, specifically for creating proof and approvals for customers.

Templator will

  • Open or Place a template file into a new or existing document
  • Create a new artboard
  • Move the template to a new locked layer
  • Copy the selected artwork in the current document and place it on the template, and rasterize it.
  • Ask the user for custom information, such as job number, clients name, job title
  • (NEW) Run Javascript to fetch additional data
  • Automatically replace text in the document such as date, name and any other text you want
  • Connect to a URL to get information from a website or database, for example, enter in a job number and return the job name and customer details
  • Create a folder and subfolders based on the information entered
  • Save the AI file
  • Export a PDF file
  • Export an Image (Jpg) of the template

Typical uses

  • Create a job folder with sub-folders and save a blank working file.
  • Copy the selected artwork and create an approval from on a new artboard

Quick Create Tab

This tab lists the previously saved settings, double-click to load the template settings and create a template.

Template Options Tab

Template

  • Template File Select the template file

Placement

  • Document Choose how to open the template file
    • Open as new document Open's the template as normal. Note: the template will retain its filename so be careful not to save and overwrite your template. For this reason, we recommend making your templates read-only.
    • Copy contents to blank document This will open your template then copy the first artboard layer by layer to a new document, The advantage of this method is that the filename is untitled.ai and there is no chance of overwriting your template. Note layer locking is preserved, so any layers locked in your template will also be locked in the new document.
    • Copy contents to existing document This will copy your template then copy the first artboard layer by layer to the current document. Note layer locking is preserved, so any layers locked in your template will also be locked in the new document.
    • Place into existing document Places the template as a linked file into the document. Note Placed file cannot be edited and so Find and Replace will not work with placed files.
    • Embed into existing document Embeds the template into the document. Note Layers will be lost in this method.
  • Artboard When using an existing document choose which artboard to use or create a new artboard the size of the imported template
  • Align to Artboard (When placing on existing artboards) Choose where the template is placed on the artboard, with this feature its possible to create just a thin footer which is placed at the bottom of the document.
  • New Position (When creating new artboard) Choose the position where the new artboard will be placed, Left, Right, Above or Below the current artboard.
  • Layers (For Copied Templates) Choose how the layers are to copied to the new or current document:
    • Preserve Layers - place at bottom Preserve the layers and place new layers at the bottom of the layer stack - behind other artwork.
    • Preserve Layers - place at top Preserve the layers and place new layers at the top of the layer stack - in front of other artwork.
    • Merge to current layer Ignores the template layers and places all artwork on the currently selected layer or default layer for new documents. Note layer locking is not preserved
  • Merge with existing layers with the same name (For Copied Templates) If the template and destination document has the same Layer names, place the template artwork on the existing layer. Use this when importing multiple templates into the same document to stop duplication of layers. We strongly recommend that your template have unique layer names which are not found in other documents, to avoid conflicts or your layers may end up in the wrong order.
  • Layer (For Placed and Embed Templates) Choose where to place the template, Current Layer, Topmost layer, Bottom most layer or create a new layer.
  • New Layer Name The name of the new layer when creating a new layer

Find and Replace

Once the template is opened or embedded you can find and replace text in the template. Note: This will not work on placed documents as they are not editable

  • Find Column The text to find in the template, we recommend that the text to replace be placed between curly brackets to its easy to see what text will be changed. such as “{date}” “{name}” “{title}”
  • Type Column
    • Text Replace with text in the Default Text/Format column
    • Date Replace with the current Date, See bottom of document for date formatting options

    • Document.name Replace with document name
    • Document.folder Replace with document folder
    • Document.filename Replace with document filename
    • Document.artboardCount Replace with number of artboards in the document (excluding newly created template artboard)
    • Document.colorSpace Replace with 'RGB' or 'CMYK'

    • Artboard.width See Size formatting below
    • Artboard.heightSee Size formatting below
    • Artboard.number the number of the artboard selected prior to creating the template

    • Selection.width See Size formatting below
    • Selection.height See Size formatting below
    • Selection.count the number of selected items

    • User Text Input Prompts the user for text
      • Default Text/Format column contains the default text
      • Validation column contains rules for validating the input - see Validation below
      • User Input Label column contains the label for the form
      • The text to find will ways be wrapped with {} brackets, so if your find text is “name” your document needs to contain “{name}”

    • User Number Input Prompts the user for text
      • Default Text/Format column contains the default text
      • Validation column contains rules for validating the input - see Validation below
      • User Input Label column contains the label for the form
      • The text to find will ways be wrapped with {} brackets, so if your find text is “num” your document needs to contain “{num}”

    • User Dropdown Input Prompts the user for text
      • Default Text/Format column contains the default selected option, it must match an option in the input validation
      • Validation column contains the list, with separate options by a vertical bar character. For example “one|two|three|four”. If you require different return values prefix the name and separate with a tilde '~' symbol. For example “BS~Bob Smith|JD~John Doe|RB~Ruth Baker” will return 'BS','JD' or 'RB' not the full names
      • User Input Label column contains the label for the form
      • The text to find will ways be wrapped with {} brackets, so if your find text is “name” your document needs to contain “{name}”

  • Default Text/Format Column
    • The default value for the form
    • For Date types this is for date format such as 'dd mmm yyyy'
  • Input Validation Column See the User Input Validation Rules at the bottom of this page
  • User Input Label Column The label to show on the form if empty the find text will be used as a label

Size formatting

You can format the height, width and scale in the Default Text/Format column.

The formatting is “units,decimals,scale”

  • units Such as 'mm' 'in' 'pt', the full set of units are supported
  • decimals (Optional, default=2) The number of decimal points to display
  • scale (Optional, default=1) The size is multiplied by the scale, so 1 is no change, 0.5 reduces the number by half, 20 makes the number twenty times larger.

Examples

  • “inch,0” will be in inches with no decimal places
  • “mm,2” will be millimetres with 2 decimal places
  • “mm,0,10” will be millimetres with no decimal places and ten times larger

Javascript

You can run Extendscript or Javascript to modify the document and return additional text changes to Templator. Your code will be wrapped in a function, so ensure that you include a return statement with the required data structure.

Your code must return the standard object indicating success and any error messages/text changes, see the next section.

Warning: Make sure your code is self-contained and does not pollute the global scope

ExtendScript in Illustrator
  • Runs the code in Extendscript in Illustrator allowing you to modify and get information from the document.
  • Note that ExtendScript and not modern ES6 Javascript and does not support the latest features of Javascript. seeAdobe scripting reference for details.
Extendscript Example

var d = new Date;
var success = false;

data.textChanges.push({find: "{filename}", type: "activeDocument.name"});
data.textChanges.push({find: "*year*", type: "text", value: d.getFullYear()});

if(success){
    return {
        success: true,
        data: data
    };
}

return {
    success: true,
    errorMessage: 'No custom code setup'
};

Javascript in CEP/NodeJS
  • Runs the code in the CEP Panel of PowerScripts, this is modern Javascript running on NodeJS, see https://github.com/Adobe-CEP/CEP-Resources.
  • Note that the following libraries are already loaded CSInterface, JQuery, Lodash, Moment.js, Numeral-js.
  • You can run ExtendScript code using CSInterface.evalScript.
  • To asynchronously get data, return a Function, This function will be called with the first argument data and the second a callback
Javascript/Node Async Example

return function getWebsite(data, callback){
     $.get("https://www.google.com",function(html){
         data.textChanges.push({find: "{html}", type: "text", value: html });
         callback({ success: true, data: data });
     });
}


External Data

This gives you the option of retrieving data from an external source, such as a custom webpage linked to a database to Find and Replace text.

  • URL contains the URL address, Note that this can contain find and replace characters, so, for example, you can use http://webserver/database.php?jobid={id} where {id} is from Javascript or user input. This allows you to ask users for things like a job number, then use that in your URL.

The server must return data in the following JSON object, see below


External URL and Javascript Return Data Format

The Javascript Extendscript must return the following, and the external webpage must return this in JSON.

{
    success: true|false,
    errorMessage: string,
    data: {
         textChanges: [
              {find: "{{animal}}": type: "text", value: "Cat" }
         ]
    }

  • success is required. Boolean true or false
  • errorMessage is optional. When success=false this message will be displayed.
  • data.textChanges is an array of objects, {find: “textToFind”, type: “text”, value: “newText”}, Changes are made in reverse order so you can bypass an existing replacement by pushing one oneto the end of the array.
  • Replacement types:
    • 'text' - Replace find text with value (if type is not included in the object text is assumed)
    • 'date' - Replace find text with today's date using the format defined in value
    • 'template.name'
    • 'document.folder'
    • 'document.name'
    • 'document.filename'
    • 'document.rulerunits'
    • 'document.colorspace'
    • 'document.artboardcount'
    • 'template.width': - value contains the units to use
    • 'template.height': - value contains the units to use
    • 'artboard.width': - value contains the units to use
    • 'artboard.height' - value contains the units to use
    • 'artboard.number'

Artwork

This option allows you to copy the currently selected artwork to the template and resize it. This has been designed for creating approval forms.

  • Select to copy the artwork to the new template
  • Fit to Width / Fit to Height Resize the selected artwork to fit within this size
  • Enlarge artwork if smaller than fit size Give you the option of enlarging smaller artwork.
  • Align To Artboard Determines where the copied artwork will be aligned to
  • Move X/Move Y Allows you to move the artwork to an exact position on the artboard.

Folders

  • Create Folder Enter the folder name to create, you can include find and replace variables in there too, such as [ C:\work\{client name}\Job J{jobNumber} ]. Leave blank to not create any folders
  • Sub Folders Create multiple subfolders by separating folder names with a comma
  • Open folder Tick to open in OSX Finder or Windows Explorer after being created

Save

Saves the document as an Illustrator file

  • Save to
    • Do not save the document - Do not save
    • Documents Folder Save to your documents folder
    • Fixed Location Save to a fixed location
    • Newly created folder Save to the newly created folder selected in the Folder option above
    • Working Folder Save to the same folder as the original document. Note: this will not work is the document is not saved.
    • Sub-Folder Save to a subfolder same folder as the original document. Note: this will not work is the document is not saved.
  • Filename Enter the filename to save as, you can include find and replace variables in there too, such as “J{id} {clientName} {jobTitle} V1.ai”
  • Prompt for Filename If unticked then the PowerScript will save without asking to confirm the filename

Export PDF

Exports the document as an Illustrator file

  • Export to
    • Do not export the document - Do not export a PDF file
    • Documents Folder Save to your documents folder
    • Fixed Location Save to a fixed location
    • Newly created folder Save to the newly created folder selected in the Folder option above
    • Working Folder Save to the same folder as the original document. Note: this will not work is the document is not saved.
    • Sub-Folder Save to a subfolder same folder as the original document. Note: this will not work is the document is not saved.
  • Filename Enter the filename to save as, you can include find and replace variables in there too, such as “PROOF of J{id} {jobTitle}.pdf”
  • Export Range
    • Newly created artboard - the artboard of the template only
    • Current artboard - The currently selected artboard
    • All artboards
  • Prompt for Filename If unticked then the PowerScript will save without asking to confirm the filename
  • Preview PDF after creation If ticked open the PDF in the default PDF reader.

Export Image

Exports the Template Artboard as an Image

  • Export to
    • Do not export the document - Do not export a PDF file
    • Documents Folder Save to your documents folder
    • Fixed Location Save to a fixed location
    • Newly created folder Save to the newly created folder selected in the Folder option above
    • Working Folder Save to the same folder as the original document. Note: this will not work is the document is not saved.
    • Sub-Folder Save to a subfolder same folder as the original document. Note: this will not work is the document is not saved.
  • Filename Enter the filename to save as, you can include find and replace variables in there too, such as “PROOF of J{id} {jobTitle}.{ext}“
    {ext} is the default extension
  • Type Select from PNG, JPEG, TIFF and PSD (Photoshop)
  • Resolution From 72dpi to 2400dpi
  • Jpeg Quality From 10% to 100%
  • Prompt for Filename If unticked then the PowerScript will save without asking to confirm the filename
  • Transparent PNG/PSD Enable transparency in PNG and PSD files

Date Formats

Mask Description
d Day of the month as digits; no leading zero for single-digit days.
dd Day of the month as digits; leading zero for single-digit days.
ddd Day of the week as a three-letter abbreviation.
dddd Day of the week as its full name.
m Month as digits; no leading zero for single-digit months.
mm Month as digits; leading zero for single-digit months.
mmm Month as a three-letter abbreviation.
mmmm Month as its full name.
yy Year as last two digits; leading zero for years less than 10.
yyyy Year represented by four digits.
h Hours; no leading zero for single-digit hours (12-hour clock).
hh Hours; leading zero for single-digit hours (12-hour clock).
H Hours; no leading zero for single-digit hours (24-hour clock).
HH Hours; leading zero for single-digit hours (24-hour clock).
M Minutes; no leading zero for single-digit minutes.
MM Minutes; leading zero for single-digit minutes.
N ISO 8601 numeric representation of the day of the week.
o GMT/UTC timezone offset, e.g. -0500 or +0230.
s Seconds; no leading zero for single-digit seconds.
ss Seconds; leading zero for single-digit seconds.
S The date's ordinal suffix (st, nd, rd, or th). Works well with d.
l Milliseconds; gives 3 digits.
L Milliseconds; gives 2 digits.
t Lowercase, single-character time marker string: a or p.
tt Lowercase, two-character time marker string: am or pm.
T Uppercase, single-character time marker string: A or P.
TT Uppercase, two-character time marker string: AM or PM.
W ISO 8601 week number of the year, e.g. 42
Z US timezone abbreviation, e.g. EST or MDT. With non-US timezones or in the
'…', ”…” Literal character sequence. Surrounding quotes are removed.
UTC: Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The “UTC:” prefix is removed.

Unit Formats

Abbreviation Singular Plural note
ft foot feet
yd yard yards
mi mile miles
mm millimeter millimeters
cm centimeter centimeters
m meter meters
km kilometer kilometers
pt point points inches / 72
pc pica picas points * 12
tpt traditional point traditional points inches / 72.27
tpc traditional pica traditional picas 12 tpt
ci cicero ciceros 12.7872 pt

User Text Input Validation

For User Text inputs you can validate the form using the following rules. Rules are separated by commas. for example “required,min:0,max:100,type:number”

  • required - This input is required
  • min - The minimum number accepted, eg “maxlength:30”
  • max - The maximum number accepted, eg “maxlength:30”
  • maxlength - maximum number of characters, eg “maxlength:30”
  • type - The HTML input type, such as
    • datetime-local
    • email
    • number
    • range
    • password
    • tel
    • text (default)
    • url

Release Notes

Version 2.0.0

  • Added preview images and abibility to generate previews
  • Added in more data types, selection.width, selection.height,selection.count
  • Added in Scale for measurements
  • Added in Javascript and Extendscript support

Version 1.3.0

  • Added: Support for PNG, TIFF and PSD (Photoshop) image exports
  • Added: Support for transparent image export
  • Added: Ability to choose “Do not import any templates” so you can use this PowerScript to only Replace Text/Save/Export PDF/Export Image. Ideal for a 3 step process: i.e Step 1 create a template, Step 2 Edit template then Step 3 Save/Export PDF/Export Image
  • Added: Checkbox for find and Replace to turn this feature off
  • Minor Fixes