EasyCatalog2p
Welcome to our EasyCatalog support site.
We help creative designers excel and automate with data driven content.
— Brian Cowell
contact@cunka.com

Education & Development

Coming Soon !!

EasyCatalog Development Template

You can download all of our inhouse development tools for free.
EasyCatalog Training Template Download

About Us

Brian Cowell creates brochures, catalogues (1500+ pages with full indexes), manuals, and user documentation using InDesign with EasyCatalog.

He has worked with creative designers for over 10 years transforming data sets to both print and interactive content. Has recently honed his skills in finding manual and automatic (Javascript/LUA) pagination solutions with EasyCatalog. Provides feedback & suggestions to 65bit.com to help the product grow.

EasyCatalog plugin modules used
  • Pagination module

  • Scripting module

  • XML Data Provider module

EasyCatalog skills
  • Javascript (Adobe InDesign / EasyCatalog)

  • LUA (EasyCatalog)

  • XML data with XSLT transformations (Using Saxonica / with EasyCatalog)

  • EXCEL / CSV data (EasyCatalog)

Experienced user of Perfion PIMs.

You can contact Brian at contact@cunka.com

Working with Images

Images In Frames

The following examples look at how the Pagination Rules setting of Fitting affects the field specific Picture Content settings of Scaling & Alignment.

This table represents the original image and the 2 InDesign graphic frames it will be applied too.

Original Image

Frame 1

Frame 2

xOriginal Image
xFramesize1
xFramesize2

"Fitting" : None

  • Scaling : None

  • Alignment : Centre

The graphic frames and image do not change size.

Looks at the “Alignment” setting and applies an image to the frame. This may result in whitespace or cropping of the image dependent on the shape of the graphics frame.

Original Image

Frame 1

Frame 2

xOriginal Image
xFramesize1 none none
xFramesize2 none none

"Fitting" : Frame To Content

  • Scaling : None

  • Alignment : Centre

The graphic frame changes size to that of the image.

If the “Scaling” in the Picture Content is set to “None”, the graphic frame will always resize to the image size.

However, the use of the Fill Frame “Scaling” setting will not change the frame size at all, while settings like Proportionally Fit will.

With “Scaling” set to Proportionally Fit, the frame will resize by the longest length.
e.g. If the height is longer than the width, the height will be resized.

Original Image

Frame 1

Frame 2

xOriginal Image
xFramesize1 frametocontent none
xFramesize2 frametocontent none

"Fitting" : Content To Frame

  • Scaling : None

  • Alignment : Centre

The graphic frame never changes size.

The image is always placed according to the setting of “Scaling”.

If the “Scaling” is set to none, the original image is placed in. This may result in cropping of the image if the frame is smaller then the original image size, or whitespace around an image that is smaller then frame its applied to.

We usually like the “Scaling” setting of Proportionally Fit with Content To Frame.

xOriginal Image
xFramesize1 contenttoframe none
xFramesize2 contenttoframe none

"Fitting" : Frame Height To Content Height

  • Scaling : None

  • Alignment : Centre

The graphic frame height size will change, the width size however will not.

The “Fitting” setting in the Pagination Rule Frame Height To Content Height is handy when you are constrained with frame widths, but not frame depths. Situations where you have columns on a document are one example for usage.

The frame will always resize the height to the image content if the “Scaling” is set to “None”.

xOriginal Image
xFramesize1 frameheighttocontentheight none
xFramesize2 frameheighttocontentheight none

"Fitting" : Frame Height To Content Height And Width

  • Scaling : None

  • Alignment : Centre

The graphic frame changes size.

The image is always placed by the setting of the “Scaling”. If the “Scaling” is set to None, the original image is placed in. This may result in the image been cropped if the frame is smaller then the original image, or whitespace around an image that is smaller then frame its applied to.

A “Scaling” setting of Proportionally Fit with Frame To Content (Height & Width) is different than the Pagination Rule Frame To Content. The frame does not change size, but simply proportionally fits the image into the frame.

xOriginal Image
xFramesize1 frametocontentheightwidth none
xFramesize2 frametocontentheightwidth none

"Scaling" : Proportionally Fit

  • Fitting : None

  • Alignment : Centre

The graphic frame size does not change.

Depending on the frame size compared to the actual image size, the image will be resized proportionally to fit into the frame. Also dependant on what is set in the “Alignment”, there may be whitespace around the image.

xOriginal Image
xFramesize1 none proportionallyfit
xFramesize2 none proportionallyfit

"Scaling" : Fill Frame

  • Fitting : None

  • Alignment : Centre

The graphic frame size does not change.

The frame will always be filled to its extents with the applied image. If the image size is vastly different to the frame size, the result may be distorted. This may be however what you are seeking to do.

xOriginal Image
xFramesize1 none fillframe
xFramesize2 none fillframe

"Scaling" : Fill Proportionally

  • Fitting : None

  • Alignment : Centre

The graphic frame size does not change.

The frame will always be filled in proportionally to its extents with the applied image. Depending on the frame size compared to the image size, and the “Alignment” setting, not all of the image may appear in the frame.

The second image in the table has a "zoom" type effect going on as it tries to fit all of the image into the frame.

xOriginal Image
xFramesize1 fillproportionally
xFramesize2 none fillproportionally

"Scaling" : Fixed Scale

  • Scale : 50%

  • Fitting : None

  • Alignment : Centre

The graphic frame size does not change.

With “Scaling” set to Fixed Scale, the image is resized to the “Scale” % value first. The result is then applied to the frame depending on the “Alignment” setting. The image may or may not fit into the frame.

xOriginal Image
xFramesize1 none fixedscale50
xFramesize2 none fixedscale50

"Scaling" : Field Specified

  • Field 1 set to 100

  • Field 2 set to 50

  • Fitting : None

  • Alignment : Centre

The graphic frame size does not change.

With “Scaling” set to Field Specified, the image is looking for two EasyCatalog fields that contain both the height & width to apply.

xOriginal Image
xFramesize1 none fieldspecified10050
xFramesize2 none fieldspecified10050

"Scaling" : Frame Specified

  • Fitting : None

  • Alignment : Centre

You can also use InDesigns own "Frame Fitting Options" that can be applied to a frame. When "Scaling" is set to Frame Specified , the settings in "Frame Fitting Options" will be used.

xFrameSize Frame Specified InDesign
xOriginal Image
xFramesize1 none frameSpecified
xFramesize2 none frameSpecified

Panel

Panel Shortcuts

The Data Source panel shortcuts using a combination of keys and mouse clicks.

MAC users should note the screenshots shown are from a PC. The magnifying glass icon on a PC will appear as a binocular icon your computer.
panel1
Number Short cut function

1

Ctrl+Alt + left mouse button
(on icon)

Opens every branch in the panel.

Repeating the process closes every branch in the panel.

2

Ctrl+Shift + left mouse button
(on icon)

Opens every branch in the selected branch of the panel.

Repeating the process closes every branch in the selected branch of the panel.

3

Shift+Alt + left mouse button
(on field header)

Hides the field.

4

Triple clicking the left mouse button
(on any panel branch)

Selects everything in the panel.

5

Ctrl+Alt (on Magnifing glass / Binoculars icon)

Removes any applied subsets.

6

Double clicking the left mouse button
(on panel head)

Panel is compressed to a tab only.

7

Double clicking the left mouse button
(on column seperator)

Auto sizes the column width to fit the largest content.

Panel Preferences

The Data Source panel display can be configured to change its appearance from the Panel Preferences menu.

Right click anywhere in the Data Source panel to display a menu to select Panel Preferences.

panel2

The Panel Preferences allow you to control how the tool tips behave, as well as the preview size. There is also a checkbox to allow the configuration files to be displayed in the panel.

Tool Tips
  • None

  • Text Only

  • Text and Image Previews

Preview Size
  • Small

  • Medium

  • Large

panel3
Fig 1. Panel Preferences with "Show Configurations" selected

Here is an an example where the "Show Configurations" has been selected in the Panel Preferences. The configurations files are shown above the fields row

panel4
Fig 2. Panel Preferences shown with configuration files

Panel Subset

The Data Source panel view can be configured to filter data to meet a certain criteria. This is called a "Subset".

You can create and save as many "Subsets" as you need. They can be saved within your configuration file.

From an automation point of view, "Subsets" are very handy as it allows you control when and how the subset will be paginated.

The example below shows the subset built where it says only show if the class field contains the term Data Source

panel5

Example of what the panel looks like with the subset applied.

panel6

By selecting More Choices its possible to filter down on many more fields.

To quickly remove any applied subsets, simply hold the Alt key and left mouse click on the magnifying icon. (Binocular icon on a MAC)

panel7
Example 1 - Find "YES" in the field AAA

In this simple example, a panel is made up of various fields that contain the values "YES" and "NO".

The objective is to find all the fields with the value "YES" in the field AAA.

SubSet1

Clicking on the Magifying Glass (Binocular icon on a MAC) will bring up the Subset menu. In the Parameter box we select the AAA field. Next the selection "Contains" is entered following the value of "YES".

So our subset formula says only show records if the field AAA contains the word YES

SubSet2

The number in the corner of the panel indicates how many records are shown from the total amount of records. In this example we are shown 5 out of 11 records.

SubSet3

Synchronize a new Data Source

If you are using a static data source like an XML/Excel/CSV file, there may be times when you need to update the data source.

PERMANENT DATA LOSS !
This process overwrites the existing data.

To update the data source , you must hold down the Shift key when selecting the Synchronize with Data Source option. This will allow you to select the new updated source.

panel8

Date/Time

By selecting the "Date/Time" as the Format for a field, you can set how the time should be formatted.

Specifiers for Date & Time

The format of the date/time stamps in the existing source data can be changed to anything you may need.

Any time and date can be broken down individually to what is known as a ‘specifier’. Each ‘specifier’ begins with a '%' sign followed by a letter that. E.g. a full year like 2019 is represented by %Y.

By combining a series of specifiers together, its possible to indicate the format of any date or time. In order to that we need to know the:

  • Input Format - original source data

  • Output Format - desired display

Date Time2
Example - 17 June 2019

In this example we want to change the original date stamp of 17-06-2019 to 17 June, 2019

The - character is important. In this example it is the seperator and is part of this particular date stamp format. Your date stamp could have a / or a : as a seperator. (Even a space character)

Input Format

  • %d = 17

  • %m = 06

  • *Y = 2019

%d-%m-%Y

Output Format
* %d = 17
* %B = June
* *Y = 2019

%d %m, %Y
The output uses the space & comma characters between the 'specifiers'.

List of Specifiers

Specifier Description Example

%d-%m-%y %H:%M:%S

Year represented by 2 digits.
day-month-year hours:minutes:seconds

17-06-19 09:11:47

%Y-%m-%d %H:%M:%S

Year shown in full.
year-month-day hours:minutes:seconds

2019-06-17 09:11:47

%y-%m-%d %H:%M:%S

Year represented by 2 digits.
year-month-day hours:minutes:seconds

19-06-17 09:11:47

%d/%m/%Y

day/month/year

17/06/2019

%m/%d/%Y

month/day/year

06/17/2019

%d/%A/%Y

day/abbreviated weekday name/year

06/Mon/2019

%Ec

Current date&time on your computer

6/17/2019 9:11:47AM

%a

Abbreviated weekday name

Thu

%A

Full weekday name

Thursday

%b

Abbreviated month name

Aug

%B

Full month name

August

%c

Date and time representation

Thu Aug 23 14:55:02 2001

%C

Year divided by 100 and truncated to integer (00-99)

20

%d

Day of the month, zero-padded (01-31)

23

%D

Short MM/DD/YY date, equivalent to %m/%d/%y

08/23/01

%e

Day of the month, space-padded ( 1-31)

23

%F

Short YYYY-MM-DD date, equivalent to %Y-%m-%d

2001-08-23

%g

Week-based year, last two digits (00-99)

01

%G

Week-based year

2001

%h

Abbreviated month name (same as %b)

Aug

%H

Hour in 24h format (00-23)

14

%I

Hour in 12h format (01-12)

02

%j

Day of the year (001-366)

235

%m

Month as a decimal number (01-12)

08

%M

Minute (00-59)

55

%n

New-line character (‘\n’)

%p

AM or PM designation

PM

%r

12-hour clock time

02:55:02 pm

%R

24-hour HH:MM time, equivalent to %H:%M

14:55

%S

Second (00-61)

02

%t

Horizontal-tab character (‘\t’)

%T

ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S

14:55:02

%u

ISO 8601 weekday as number with Monday as 1 (1-7)

4

%U

Week number with the first Sunday as the first day of week one (00-53)

33

%V

ISO 8601 week number (00-53)

34

%w

Weekday as a decimal number with Sunday as 0 (0-6)

4

%W

Week number with the first Monday as the first day of week one (00-53)

34

%x

Date representation

08/23/01

%X

Time representation

14:55:02

%y

Year, last two digits (00-99)

01

%Y

Year

2001

%z

ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100)
If timezone cannot be determined, no characters

+100

%Z

Timezone name or abbreviation
If timezone cannot be determined, no characters

CDT

%%

A % sign

%

Prefix for other languages

Dates can now be prefixed for other spoken languages.

Month and weekday names can be localised when formatting dates. By default they will use the language specified by the InDesign user interface, but this can be changed by prefixing the format with the language required.

[fr_FR]
Example 1 - French language prefix [fr_FR]
[fr_FR]%d %B %Y
%d-%m-%Y [fr_FR]%d %B %Y

11-04-2019

11 avril 2019

23-01-2019

23 janvier 2019

05-03-2019

05 mars 2019

Date Time1
Example 2 - English prefix [en_US]
[en_US]%d %B %Y
%d-%m-%Y [en_US]%d %B %Y

11-04-2019

11 April 2019

23-01-2019

23 January 2019

05-03-2019

05 March 2019

Example 3 - German prefix [de_DE]
[de_DE]%d %B %Y
%d-%m-%Y [de_DE]%d %B %Y

11-04-2019

11 April 2019

23-01-2019

23 Januar 2019

05-03-2019

05 Marz 2019

Example 4 - Danish prefix [da_DK]
[da_DK]%d %B %Y
%d-%m-%Y [da_DK]%d %B %Y

11-04-2019

11 april 2019

23-01-2019

23 januar 2019

05-03-2019

05 marts 2019

Example 5 - Spanish prefix [es_ES]
[es_ES]%d %B %Y
%d-%m-%Y [es_ES]%d %B %Y

11-04-2019

11 abril 2019

23-01-2019

23 enero 2019

05-03-2019

05 marzo 2019

Cleansing

Applying Cleansing Options

The content of each field can be cleansed in a non-destructive way before it is used in the document. This allows content to be changed, formatted or removed.

The Cleansing Options action acts like a simple search-and-replace function.

{replace this} = {with this};

The Data Source Panel always displays the data cleansed.

Removing the applied Cleansing Options restores the original field content.

Since the "=" symbol is used for the actual cleasing, if any data contains an equals sign, you must use two of them together. eg. <table>=<table style=="CUNKA_GOLD">

Example 1 - Simple Cleansing

All # characters are replaced with a $
Cleansing functions end with and are seperated by a ;

#=$;
Before Cleansing After Cleansing

#3000

$3000

#20.10

$20.10

Example 2 - Multiple Cleansing

All # characters are replaced with a $
All _ characters are replaced with a .
Cleansing functions end with and are seperated by a ; character

#=$;_=.;
Before Cleansing After Cleansing

#3000_00

$3000.00

#20_10

$20.10

Example 3 - Removing Characters

All # characters are removed
Cleansing functions end with and are seperated by a ; character

Specify nothing on the right-hand side of the = cleansing option strips the character on the left.
#=;
Before Cleansing After Cleansing

#CUNKA

CUNKA

20#

20

Example 4 - Replacing strings

All CUNKA characters are removed
Cleansing functions end with and are seperated by a ; character

CUNKA=EasyCatalog;
Before Cleansing After Cleansing

Email us at CUNKA

Email us at EasyCatalog

Call the CUNKA hotline

Call the EasyCatalog hotline

CUNKA

EasyCatalog

Example 5 - Fixing HTML

All <table tags are inserted with style="cunkaFruity"
Cleansing functions end with and are seperated by a ; character

The == duplication of the equals sign must be used if the equal sign is needed in the cleansed result.
<table=<table style=="cunkaFruity";
Before Cleansing After Cleansing

<table>

<table style="cunkaFruity">


InDesign Metacharacters/Special Characters

InDesign metacharacters, such as those used in the Find/Change dialog, can also be used as part of the cleansing statement and within the prefix and suffix fields.

Metacharacters begin with a caret (^) and represent special characters in InDesign, such as a bullet point or a tab.

Example 1 - Asterisks Converted To InDesign Bullet Points

All asterisk characters * are converted to the InDesign bullet point metacharacter ^8
Cleansing functions end with and are seperated by a ; character.

*=^8;
Before Cleansing After Cleansing

*cunka.com

  • cunka.com

*cunka.com
*65bit.com
*unsplash.com

  • cunka.com

  • 65bit.com

  • unsplash.com

Example 2 - Removing Forced Line Breaks

All forced line breaks characters ^n are removed.
Cleansing functions end with and are seperated by a ; character.

^n=;
Before Cleansing After Cleansing


cunka.com

cunka.com


cunka.com

65bit.com

unsplash.com

cunka.com
65bit.com
unsplash.com

Metacharacters Table

Table 1. A full list of metacharacters supported by EasyCatalog.
Code Description Character

^#

Auto Page Numbering

^x

Section Marker

^8

Bullet

^^

Caret

^

^2

Copyright Symbol

©

^p

End of Paragraph

^n

Forced Line Break

^7

Paragraph Symbol

^r

Registered Trademark Symbol

®

^6

Section Symbol

§

^t

Tab

^\

End Nested Style

^y

Right Indent Tab

^i

Indent to Here

^_

Em Dash

^m

Em Space

^=

En Dash

^>

En Space

^f

Flush Space

^|

Hair Space

^s

Nonbreaking Space

^<

Thin Space

^-

Discretionary Hyphen

^~

Nonbreaking Hyphen

-

^{

Double Left Quotation Mark

^}

Double Right Quotation Mark

^[

Single Left Quotation Mark

^]

Single Right Quotation Mark

^k

Discretionary line break

Using Regular Expressions

A more advanced method of cleansing data through pattern matching can be applied using regular expressions.

Always use the updated and more advanced REGEXV2 over the older REGEX expression when cleansing.
The ^ character is interpreted as an InDesign meta-character, so ^^ should be used for the regular expression ^ character:
Example 1

Convert all the data in the field to be uppercase.

REGEXV2:(.)=\U\1;
  • ( ) creates a group. Connects result to \1.

  • . matches any character (except for line terminators)

  • \U uppercase transformation

  • \1 places the found group.

Field Text REGEXV2 result

cat-NZ0003E

CAT-NZ0003E

Cat-AU99e

CAT-AU99E

CAt-JP01ax

CAT-JP01AX

#1fC0d

#1FC0D

Example 2

Convert all the data in the field to be lowercase.

REGEXV2:(.)=\L\1;
  • ( ) creates a group. Connects result to \1.

  • . matches any character (except for line terminators)

  • \L lowercase transformation

  • \1 places the found group.

Field Text REGEXV2 result

cat-NZ0003E

cat-nz0003e

Cat-AU99e

cat-au99e

CAt-JP01ax

cat-jp01ax

#1FC0d

#1fc0d

Example 3

Convert all the data in the field to be title case.

REGEXV2:(\w)(\w*)=\U\1\L\2;
  • ( ) creates a group. Connects result to \1.

  • \w matches any word character

  • ( ) creates a group. Connects result to \2.

  • \w matches any word character

  • * matches as many times as possible

  • \U uppercase transformation

  • \1 places the found group.

  • \L lowercase transformation

  • \2 places the found group.

Field Text REGEXV2 result

indian red

Indian Red

light salmon

Light Salmon

dark golden rod

Dark Golden Rod

pale golden rod

Pale Golden Rod

Example 4

Append "CUNKA-" where the data begins with 3 numbers.

REGEXV2:^^(\d{3})=CUNKA-\1;
  • ^^ from the start of the line

  • ( ) creates a group. Connects result to \1.

  • \d matches a digit 0-9

  • {3} matches exactly 3 times

  • \1 places the found group.

Field Text REGEXV2 result

91234

CUNKA-91234

1a345

1a345

87878

CUNKA-87878

10.00

10.00

Example 5

From the end of the data, remove the last 3 numbers.

REGEXV2:\d{3}$=;
  • $ from the end of the line

  • \d matches a digit 0-9

  • {3} matches exactly 3 times

Field Text REGEXV2 result

91234

91

1a345

1a

87878

87

10.00

10.00

Example 6

If the 2nd last number is an 8, change it to a "z".

REGEXV2:(8)(.)$=z\2;
  • $ from the end of the line

  • (.) creates a group. Connects result to \2.

  • (8) matches the number 8

  • \2 places the found group.

Field Text REGEXV2 result

cat-NZ0008X

cat-NZ000zX

cat-NZ00008

cat-NZ00008

cat-JPAAAAA87

cat-JPAAAAAz7

cat-AU000800

cat-AU000800

Example 7

If the 2nd last number is an 8, append the color from the Field "myCOLOR".

REGEXV2:(8)(.)$=\1\2 (FIELDSTR(myCOLOR));
  • $ from the end of the line

  • (.) creates a group. Connects result to \2

  • (8) creates a group. Connects result to \1

  • \1 places the found group

  • \2 places the found group

  • FIELDSTR(myCOLOR) another filed called "myCOLOR" in the data source panel

FIELD "myCOLOR" Field Text REGEXV2 result

YELLOW

Cat-NZ0008X

Cat-NZ0008X (YELLOW)

GREEN

TTT-NZ00008

TTT-NZ00008

MAGENTA

CUNKA-JPAAAAA87

CUNKA-JPAAAAA87 (MAGENTA)

BLUE

65bit-AU000800

65bit-AU000800

Example 8

Lets look at an example where the field text is supplied to EasyCatalog with various manufacturers names. The requirement is to find/replace with your company name.

The field text could be 1 or many lines. There may also be mistakes where the manufacturers name has been entered in all lowercase or uppercase.

REGEXV2:(?i)\b(Panasonic|Samsung|Sony|LG|Akai)\b=CUNKA;
  • (?i) makes everything after it case insensitive

  • \b \b anything between is a word.

  • ( ) creates a group.

  • | acts like a boolean OR.

Field Text REGEXV2 result

Panasonic is a TV manufacturer.
Another manufacturer is akai.
sony also make TVs'.
So does Samsung.#
Do you know about LG?

CUNKA is a TV manufacturer.
Another manufacturer is CUNKA.
CUNKA also make TVs'.
So does CUNKA.
Do you know about CUNKA?

Example 9

The field text has come into EasyCatalog with no formatting applied. The objective is find certain words in the text and make them the color green.

(Assuming an InDesign Paragraph Style called GREEN exists)

In this instance we need to find certain words, and apply HTML style tags. The action will require the <GREEN> tag inserted before the found word, and the </GREEN> tag inserted after it.

REGEXV2:(?i)\b(Rain|Thunder|Lightning)\b=<GREEN>\1</GREEN>
  • (?i) makes everything after it case insensitive

  • \b \b anything between is a word.

  • ( ) creates a group. Connects result to \1.

  • | acts like a boolean OR.

  • \1 places the found group.

With ( ) in a REGEXV2 expression, it is known in regular expressions as a captured group. Each captured grouped are numbered as they are captured starting at 1.

To reuse the result of the captured group a back reference must be used. In this case the back reference \1.

Field Text REGEXV2 result

The secret word is thunder.
Lightning struck twice.
Then rain started falling.

The secret word is <GREEN>thunder</GREEN>.
<GREEN>Lightning</GREEN> struck twice.
Then <GREEN>rain</GREEN> started falling.

Unicode Character Replacement

REGEXV2 itself does not support the \uFFFF unicode syntax used with many online regex testers.
The supported unicode syntax in EasyCatalog is \x{FFFF}
Example 1

This example looks at removing a range of unicode characters between 25A0 to 25C6.

REGEXV2:[\x{25A0}-\x{25C6}]=;

The InDesign Glyphs panel is a handy tool to work out the numbers of unicode characters.

Regex unicode
Example 2

Replace a unicode character with another character.
This replaces the hexadecimal code point 2028 with a soft return.

REGEXV2:[\x{2028}]=^n;

Preview Cleansing Options

When designing and applying cleansing options, its possible to preview the results before applying them.

In the "General" tab of "Field Options", click on the to preview cleansing options.

Example
  • Remove $ and (includes GST) from data in the "myREGEX" field.

cleansing1
Fig 3. Cleansing Options for field "myREGEX"
cleansing2
Fig 4. Remove $ sign with " $=; " then click
cleansing3
Fig 5. Preview cleansing option results
cleansing4
Fig 6. Remove (includes GST) sign with " (includes GST)=; " then click
cleansing5
Fig 7. Preview cleansing option results

Document Decisions While Paginating

EasyCatalog allows you to make decisions on the document while paginating. This flexibility allows you clever dynamic control of your content on how and when things appear on a page.

You need to put instructions into the document in order to do this. The instructions appear in "[[…​…​…​]]" that are simply double square brackets that indicate where the intructions begin and end.

The instructions are created using a scripting language called LUA. Its easy to learn and you will find our uses here applicable to your projects.

Deciding on applying Column/Frame Breaks

There may occasions when a particular item appears in the document and you want to insert some form of break . Whether thats a page, column or frame break, you can control when that happens.

Example

In this example we have 2 images on the page. However, we want to have control over whether the 2nd image will have a column break applied, or a frame break. The decision is made from a field I’m using called 'ID'.

  • If the 'ID' equals 1 then its a column break.

  • Any other number in the field 'ID' its a frame break.

The LUA instruction for inserting page/column/frame is TEXT.insertbreak('…​').
eg. Inserting a column break is TEXT.insertbreak('column').

Here is the final LUA instructions we apply into the document.

[[ if(field('ID')=='1') then TEXT.insertbreak("column") else TEXT.insertbreak("frame") end;]]

This document is made up of a 2 page spread that has linked text frames that have 2 columns in them.

Here we have put the 1st image placed in the document.
After the 1st image I’ve inserted the LUA instruction code before the 2nd image. We have been careful to not leave any paragraph return markers in the document.

LUA text decisions1

This screen shot is the zoomed out view of the images and LUA code in the 2 page spread.

LUA text decisions2

When the field 'ID' equals 1 when paginating, a column break is inserted causing the 2nd image to appear in the next column.

LUA text decisions3

When the field 'ID' does not equal 1 when paginating, a page break is inserted causing the 2nd image to appear in the next column.

LUA text decisions4

Choosing Images On The Page

We can also choose whether we use one image over another depending on the field content.

Example

In this example we can choose 1 of 2 images that can be in the page depending on what the content of the field 'ID' contains.

  • If field 'ID' equals 1, use image 1.

  • Any other number in the field 'ID' use image 2.

To do this, we must insert our images into the LUA instructions.

[[ if(field('ID')=='1') then ]]
[[ else ]]
[[ end;]]
LUA text decisions5

When the field 'ID' equals 1 when paginating, the 1st image remains, and the 2nd image is removed.

LUA text decisions6

When the field 'ID' is any other number but 1, the 2nd image remains, and the 1st image is removed.

LUA text decisions7
We could have left the instructions in from the previous example and had many instructions at work.
LUA instructions are powerful tools for your use in EasyCatalog!

[[ if(field('ID')=='1') then TEXT.insertbreak("column") ]]
[[ else TEXT.insertbreak("frame") ]]
[[ end;]]

Workspace Folder

On installation of the EasyCatalog software, it creates an EasyCatalog Workspace folder.

By default, the EasyCatalog Workspace folder will be configured to be:

Macintosh

Documents:EasyCatalog Workspace

Windows

My Documents/EasyCatalog Workspace

The EasyCatalog Workspace folder contains a folder for each data source you create.

Within a created data source folder, EasyCatalog creates 6 default folders

  1. Assets
    Contains snippet files. (If full file paths are not supplied for the snippet file)

  2. Configurations
    Contains user created / saved configuration files. (eg. Grouping, cleansing options, custom fields…​)

  3. Data
    Contains the information files used by EasyCatalog for the data source. (eg Fields.xml)

  4. Image
    Contains image files. (If full file paths are not supplied for the image file)

  5. Scripts
    Contains any user created Javascript / LUA scripts. (eg. Event Scripts, CALLSCRIPT / GROUPSCRIPT custom field references…​. )

  6. XSLT
    Contains XSL / XSLT files used for XML transformations.

FolderStructure

HTML

Tags

<font>
The <font> tag is deprecated and not supported in HTML5.
  • tag accepts color values in addition to a swatch name. Enhanced HTML parser only.

<font color="c100m0y0k0"> Testing font color attribute in the 'font' tag</font>

<font color="Cunka_Yellow"> Testing font color attribute in the 'font' tag</font>
<b> or <i>
  • support for specifying which font face should be used when applying bold and italics:
    e.g. <b boldface = “SemiBold” plainface = “Regular”>

<p>
  • accepts the “class” attribute and maps the name to an InDesign paragraph style name.

  • accepts the “shade” (highlight) attribute. This takes a swatch name, a CMYK or RGB value. Enhanced HTML parser only.

    • Example 1 : Shade color set to use the "Cunka_Yellow" swatch.

      400
      Shade1
    • Example 2 : Shade color set to use the CMYK color "100,0,0,0".

      Shade3
<small>
  • applies small caps character attribute.

<img>
  • accepts the “style” attribute to apply an InDesign object style.
    eg. <IMG src = “xxxxx” width=”2cm” height = “3cm” style = “Object Style 1”/>

  • accepts width or height attributes. If either measurement is missing the other will be calculated based on the proportions of the image.

<table>
  • the ‘width’ property, which can be in any unit-of-measure supported by InDesign, or ‘auto’ to automatically horizontally resize the table to be the width of the column it is placed in, or a percentage of the containing text box’s width.

  • the ‘class’ and ‘style’ property, which can be used to apply an InDesign table style.

<th> and <td> tags and attributes

<th>

Rows are created as InDesign table header rows.

<td>

Rows are created as InDesign body table rows.

class/style

The name of an InDesign cell style

width

Width of the table column. Keywords can also be used to specify one of EasyCatalog’s column properties: FIXED, VARIABLE, FITTOTEXT

height

The height of the table row. The height can be specified using any of InDesign’s supported measurement units.

vmerge

Specifies an EasyCatalog vertical merging attribute. Can be one of CONTENTMATCH, POPULATEDCONTENTMATCH

hmerge

Specifies an EasyCatalog horizontal merging attribute. Can be one of CONTENTMATCH, POPULATEDCONTENTMATCH

delete

Specifies an EasyCatalog row deletion property, can be one of NEVER, IFEMPTY

colspan/
rowspan

Standard HTML row and column spans.

<br>
  • tag will insert a soft return rather than a hard return.

HTML entity
  • If a HTML entity cannot be found in the current font, alternative fonts will be searched for the glyph.

  • accepts soft return entity.

HTML tabular fields
  • support the "class" attribute.

InDesign Style group support
  • levels are separated by colon.

  • As spaces aren’t allowed in tag names, EasyCatalog replaces "-" with a space before searching for a style.
    e.g. < EasyCatalog :cunka-style> will search for a style called ‘cunka style’ in the ‘EasyCatalog‘ style folder.

Tables

Cells

Apply Cell Style

Through the Apply Cell Style feature in Cell Options, an InDesign cell style can be applied from an EasyCatalog field.

The Apply Cell style feature can alternatively override the Indesign cell style use in favor of using a swatch instead. To override the cell style, the value must be prefixed with "SWATCH:"

EXAMPLE : Table row has 2 columns.

The cell in the first column is using the field "myCell" to apply an InDesign cell style.

The cell in the second column is using a field called "mySwatch" to apply a Swatch to the cell.
cellswatch1
The field mySwatch has the Prefix of SWATCH:
cellswatch2

The Apply Cell Style for the first cell is set to "myCell". The second cell is set to "mySwatch".

cellswatch4

Final result.
The first column is made of cells that have an InDesign Cell Style applied.
The second column has cells with Swatches applied.

cellswatch3
Cell Rotation

Cells can be rotated by applying the rotation tag. eg. <td rotation="90">
Enhanced HTML parser only.

EXAMPLE : The field "myHTML" has a table made up of 4 cells. Cell2 is rotated 90 degrees, Cell4 is rotated 270 degrees.

<table>
<tbody>
<tr>
<td>Cell1</td>
<td rotation="90">Cell2</td>
</tr>
<tr>
<td>Cell3</td>
<td rotation="270">Cell4</td>
</tr>
</tbody>
</table>
rotation1
The field myHTML is set up to use the Enhanced parser.
rotation2

Final result.
After manually adjusting the heights of the cells, Cell2 is rotated 90 degrees, and Cell4 is rotated 270 degrees.

rotation3

Custom Field Reference

Custom Field Reference is from EasyCatalog 13.0.3.20190522(19102)

AND

Description

Takes two or more arguments and performs a logical 'AND' operation testing for true or false conditions.

  • Returns TRUE if all arguments are TRUE.

  • Returns FALSE if any argument is FALSE.

Parameters

AND(argument1, argument2,…​)

Example

The AND formula says "If Available is equal to yes, and InStock is greater then 10, then the Status field will be true. If Available is anything else but yes, then Status will be false. If InStock is 10 or less, then Status will be false".

AND(IF (FIELDSTR(Available), '=', Yes), IF (FIELDSTR(InStock), '>', 10))
AND

OR

Description

Takes two or more arguments and performs a logical 'OR' operation testing for true or false conditions.

  • Returns TRUE if any argument is TRUE.

  • Returns FALSE if all arguments are FALSE.

Parameters

OR(argument1, argument2,…​)

Example

With OR, we only need one of the two arguments to be true, and the result will be true.

OR(IF (FIELDSTR(Available), '=', Yes), IF (FIELDSTR(InStock), '>', 10))
OR

NOT

Description

Performs a logical 'NOT' operation on the given boolean argument.

  • TRUE will return FALSE.

  • FALSE will return TRUE.

Parameters

NOT(argument)

Example

The NOT command takes an existing TRUE/FALSE value and returns its opposite value. So if a value is TRUE, using NOT will return FALSE.

NOT(FIELDSTR(Status))
NOT

APPLYXSLT

Description

Apply an XSL transformation to the contents of a field containing XML.
The XSLT file is referenced from the data sources XSLT folder located in the EasyCatalog Workspace.

Requires the XML data provider module.

Parameters

APPLYXSLT(field name, xslt file name)

Example
APPLYXSLT(XML_stuff,'chips.xsl')

The XSL file called "chips.xsl" must be located in the XSLT folder of the Data Source you will be using. Your Data Source should be located in the "EasyCatalog Workspace" folder. In this example my Data Source is called "cunka.com".

ApplyXSLT4

You can see the contents of the field "XML_stuff". This is the XML data to be transformed.

ApplyXSLT1

You can see the contents of the field "myFixed". Which has taken the file "chips.xsl" and applied a transformation to the data in the field "XML_stuff". The result is stored in the field "myFixed".

ApplyXSLT2

Here is the final result and how it appears on the page.

ApplyXSLT3

The XML source data in the example field "XML_stuff".

<?xml version="1.0" encoding="UTF-8"?>
<products>
<item>
    <sku>3890</sku>
    <brand>Cunka</brand>
    <name>BBQ Potatoe Chips</name>
    <weight>120g</weight>
</item>
<item>
    <sku>2331</sku>
    <brand>Cunka</brand>
    <name>Classic Shapes</name>
    <weight>80g</weight>
</item>
<item>
    <sku>3765</sku>
    <brand>Cunka</brand>
    <name>Spicey Chicken</name>
    <weight>87g</weight>
</item>
<item>
    <sku>4501</sku>
    <brand>Cunka</brand>
    <name>Pizza Shapes</name>
    <weight>95g</weight>
</item>
<item>
    <sku>4222</sku>
    <brand>Cunka</brand>
    <name>Sea Salt Chips</name>
    <weight>81g</weight>
</item>
</products>

The "chips.xsl" transformation source code.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
  <table>
      <tr>
        <td>SKU</td>
        <td>Brand</td>
        <td>Item name</td>
        <td>Weight (g)</td>
      </tr>
    <xsl:for-each select="//item">
      <tr>
        <td><xsl:value-of select="sku"/></td>
        <td><xsl:value-of select="brand"/></td>
        <td><xsl:value-of select="name"/></td>
        <td><xsl:value-of select="weight"/></td>
      </tr>
    </xsl:for-each>
  </table>
</xsl:template>
</xsl:stylesheet>

AVG

Description

Returns the average of the arguments

Parameters

AVG(argument1, argument2, …​)

Example
AVG(FIELDSTR(Value1),FIELDSTR(Value2),FIELDSTR(Value3))

Take the average from fields.

AVG

BASE64DECODE

Description

Decodes the specified text from Base 64

Parameters

BASE64DECODE(text to decode)

Example
BASE64DECODE(FIELDSTR(TextBase64))

Take a string encoded with Base64 and decode it.

Text to decode

TWVsYm91cm5lLCBBVVNUUkFMSUEK

Decoded Base 64 text

Melbourne, AUSTRALIA

BASE64DECODE

BASE64ENCODE

Description

Encodes the specified text as Base 64

Parameters

BASE64ENCODE(text to encode)

Example
BASE64ENCODE(FIELDSTR(Uncoded_Text))

Take a string and encode it into Base64 text.

Text to encode

Melbourne, AUSTRALIA

Encoded Base 64 text

TWVsYm91cm5lLCBBVVNUUkFMSUEK

BASE64DECODE

CALLSCRIPT

Description

You can add additional processing power to EasyCatalog by calling InDesign ExtendScript scripts from the Data Source 'Scripts' folder.

CALLSCRIPT fields are not updated until another field is updated.
CALLSCRIPT1

Scripts are passed the records field data that can be easily referenced to by myRecord["YOUR FIELD NAME GOES HERE"]. The script can refer to record data as myRecord["fieldname"]. The result returned can be a new calculated value, or a mix of existing record data.

Parameters

CALLSCRIPT(file name)

Example
CALLSCRIPT(Layouts.jsx)
CALLSCRIPT2

The 'Layouts.jsx" Javascript source code. EasyCatalog passes a record to the script always called "myRecord". You can easily get the contents of a record by knowing its field name. This example simply takes the "ID" and "ColorScheme" fields and concatenates them together in the "ID+ColorScheme" field shown in the screen shot above.

/*
   Layouts.jsx
   Put this script into the "Scripts" folder of the datasource

   by Brian Cowell
   contact@cunka.com

*/

// field names from EasyCatalog are passed to the script
// via myRecord["YOUR FIELD NAME GOES HERE"]

myRecord["ID"]+" "+myRecord["ColorScheme"];

// the result is returned to the field that called the script
Example

This example is a more advanced use of "CALLSCRIPT" where we know the color scheme that will be used, but really need the hexadecimal color value.

The color names and hexidecimal values are held in the scripts array. EasyCatalog passes the records data and the script picks out the color scheme field, then compares that name to names that exist in the array.
It then returns the hexadecimal for the color.

CALLSCRIPT

The 'Layouts.jsx" Javascript source code.

/*
   Layouts.jsx

   Put this script into the "Scripts" folder of the datasource

   by Brian Cowell  contact@cunka.com

   Color list from : https://en.wikipedia.org/wiki/List_of_colors:_A%E2%80%93F
*/

// color schemes are stored in an array. Name and hexidecimal value
var colorSchemes = [
    {colorName:"Battleship grey",hexValue:"#848482"},
    {colorName:"Bitter lime",hexValue:"#BFFF00"},
    {colorName:"Barbie pink",hexValue:"#E94196"},
    {colorName:"Bubbles",hexValue:"#E7FEFF"},
    {colorName:"Blond",hexValue:"#FAF0BE"},
    {colorName:"Black bean",hexValue:"#3D0C02"}
];

// default color will be "Black bean" if the color is not found
var hexColor=colorSchemes[5].hexValue;

// loop through all the color schemes
for (i in colorSchemes) {
    // get the color name from the field "ColorScheme" and compare it
    if (myRecord["ColorScheme"]==colorSchemes[i].colorName){
        // store the hexidecimal value if the color name is found
        hexColor=colorSchemes[i].hexValue;
        }
}

//return the hexidecimal value back to the field that called the script
hexColor;

CASE

Description

Finds the given key in a list of key/value pairs and returns the matching value. If a value can not be found, the returned value is empty.

If the last pairing of a CASE command starts with * then this is used for any non-matches. In other words, it becomes the default value.

Software/hardware programmers will identify CASE functionality as that of "switch/case" command as used in languages like Javascript, Java, C++, PHP etc.

Parameters

CASE(text,key,value…​.,…​.)

Example 1
CASE(FIELDSTR(Code),99,Items are on HOLD,K,Available as a KIT only,A,Accessory item,I,Indent item,C,Call for information)

This example takes existing codes from the field "Code" and uses CASE to look them up (eg. K code is "Available as a KIT only") and returns the text into the field "Code Description".

CASE
Example 2
CASE(FIELDSTR(Code),99,Items are on HOLD,K,Available as a KIT only,A,Accessory item,I,Indent item,C,Call for information,*,Not what we expected)

Same as Example 1, except it includes a default value if it can not match to anything. By using "*" as the last condition, a value can be applied to cases that do no match.

CASE2

CHAR

Description

Converts a number to the corresponding character.

  • Decimal values.

  • Hexadecimal values can be specified but must be prefixed with %.

Parameters

CHAR(numeric value of character)

Example
CHAR(FIELDSTR(HexaDecimal))

The hexadecimal value is quite easy and more intuitive for InDesign users to work with. The InDesign Glyphs panel shows the "Unicode" (hexadecimal value) which allows you to see what exact character you would like to get. Simply put the % sign in front of the unicode number and use it in CHAR().

CHAR

CODE128

Description

Converts the given string to the glyphs required to output a Code 128 barcode using the Code128bWin or Code128bWinLarge font

Requires the font Code128bWin or Code128bWinLarge.

Parameters

CODE128(text)

Example
CODE128(FIELDSTR(Text))
CODDE128

COMPARESTR

Description

Compares the contents of a field with a value and returns a match result.

Parameters

COMPARESTR(field name, value, (optional) result if TRUE, (optional) result if FALSE)

Example 1
COMPARESTR(Availability,'Now','Now Available','Out Of Stock')
COMPARESTR
Example 2

If none of the optional COMPARESTR fields are used, the returned result will be either TRUE or FALSE.

COMPARESTR(Availability,'Now')
COMPARESTR2

CONCAT

Description

Concatenate the given parameters

Parameters

CONCAT(argument1, argument2, …​)

Example
CONCAT('SKU - ',FIELDSTR(CatalogueNo),' [ $',FIELDSTR(RRP),' ]')

The example takes the word 'SKU' and joins it with the contents of the fields CatalogueNo and RRP to display joined together.

CONCAT

CONTAINSALL

Description

Returns TRUE if the first parameter contains all of the subsequent parameters

Parameters

CONTAINSALL(string to check, string to look for, …​)

Example
CONTAINSALL(FIELDSTR(Available Colors),red,black)

Checks the "Available Colors" field if both "red" and "black" are listed. Returns TRUE if both are listed, returns FALSE otherwise.

CONTAINSALL

CONTAINSANY

Description

Returns TRUE if the first parameter contains any of the subsequent parameters

Parameters

CONTAINSANY(string to check, string to look for, …​ )

Example
CONTAINSANY(FIELDSTR(Available Colors),red,black)

Checks the "Available Colors" field if either "red" or "black" are listed. Returns TRUE if any (or both) are listed, returns FALSE otherwise.

CONTAINSANY

COUNTOF

Description

Counts the number of instances of one string inside of another.

Parameters

COUNTOF(string to check, string to look for, …​ )

Example
COUNTOF(FIELDSTR(CatalogueNo),'-')

Here we are counting the amount of times the "-" appears in the CatalogNo field.

COUNTOF

CREATERANGES

Description

Parse a delimited list, creating ranges of consecutive values.

Parameters

CREATERANGES(separator,valid values (in order),single sep, range sep, values)

Example
CREATERANGES(',','S,M,L,XL,XXL,XXXL',' / ',' -- ',FIELDSTR(SIZES))

Sometimes there are many values available for an item. In this example we are talking about sizes of jeans. Now we could list all the available sizes of the jeans (field "Size"), but rather then list them all, we can also take the sizes and break them down into a range.

You can see the ranges are now listed with the "--" seperator in the "Size Ranges" field. We have also dropped the use of the "," seperator in favour of the " / " seperator for non ranges.

CREATERANGES

DECTOFRAC

Description

Converts a decimal value to a fraction

Parameters

DECTOFRAC(decimal value, (optional)add html tags to format fractional part)

Example 1
DECTOFRAC(FIELDSTR(DecimalValue))

Takes a decimal value, and converts it into a fraction value.

DECTOFRAC1
Example 2
DECTOFRAC(FIELDSTR(DecimalValue),TRUE)

This takes Example 1 a step further by using the optional parameter TRUE. The result is HTML tags (SUP & SUB) are applied to the fraction.

DECTOFRAC2

DEPENDSON

Description

Creates an explict dependency on another field being up-to-date.

EasyCatalog internally creates a dependancy tree before executing any if its commands. There are very rare occasions where it may not return the value you were expecting as it executed the commands in the wrong order. This is where DEPENDSON helps. It will explicitly create a dependancy to control the order of execution.

For example, you may have a command that takes the value of a custom field and that fields runs an external Lua script that then goes on to reference other fields.

Parameters

DEPENDSON(field name)

Example
DEPENDSON('Snippet Depth')

DISTINCTLIST

Description

Creates a list of unique values

Parameters

DISTINCTLIST(separator, string, string)

Example
DISTINCTLIST(' / ', FIELDSTR(Manufacturer),FIELDSTR(Supplier),FIELDSTR(Store))

Using three fields, we take the contents and remove duplicates and display with our designated " / " seperator.

DISTINCTLIST

DIV

Description

Divide one number by another number

Parameters

DIV(number,number, (optional) precision defaults to 7 decimal places. Use -1 to round precision only when its needed.)

Example 1
DIV(FIELDSTR(Weight grams), 1000)

This is the standard 7 decimal place output if no precision is stated.

DIV3
Example 2
DIV(FIELDSTR(Weight grams), 1000,3)

The precision of 3 decimal places.

DIV
Example 3
DIV(FIELDSTR(Weight grams), 1000,-1)

The precision value "-1" drops any trailing 0’s.

DIV2

DOCUMENTIMPORTPAGE

Description

Sets the document page to import. Can be used in the picture import location to force a specific page to import

Parameters

DOCUMENTIMPORTPAGE(page number to import, starting from 1)

Example
DOCUMENTIMPORTPAGE(2)

DOESFIELDEXIST

Description

Returns TRUE if the specified field exists

Note: Its quite possible if you are visually looking at the data source panel and you can not see a field reported back as existing (TRUE), that the field will be actually hidden.

Parameters

DOESFIELDEXIST(field name)

Example
DOESFIELDEXIST('Stock Code')

Looking to see if the field 'Stock Code' exists. It doesn’t exist so the value shown is FALSE.

DOESFIELDEXIST

DOESIMAGEEXIST

Description

Returns TRUE if an image exists as defined by the given field

Parameters

DOESIMAGEEXIST(field name)

Example
DOESIMAGEEXIST('Image')
DOESIMAGEEXIST

DSSTATUS

Description

Returns the data source status of the given field
"unchanged","updated" or "inserted"

Parameters

DSSTATUS(field name)

Example
DSSTATUS(myField)
DSSTATUS

EAN13

Description

Returns an EAN13 barcode

European Article Numbering (EAN) is used for retail product marking and identifies the product and its producer.

Requires the eanbwrp36tt font

Parameters

EAN13(text)

Example 1
EAN13(EAN13Number)
EAN13
Example 2
EAN13(FIELDSTR(Code), GETBARCODEGLYPHS('EanT48L'))

EAN8

Description

Returns an EAN8 barcode

European Article Numbering (EAN) compressed code for products with limited label space.

Requires the eanbwrp36tt font

Parameters

EAN8(text)

Example
EAN8(EAN8Number)
EAN8

ENV

Returns environment information for the given string name.

Name Value

datasourcename

The name of the current data source

version

The version number of EasyCatalog

buildno

The build number of EasyCatalog

date

The current date. Has an optional second parameter to specify the ‘nth’ day from today. eg. ENV(date,1)

username

The name of the user logged in to the machine.

osversion

The version number of the operating system

platform

The platform being used (Macintosh/Windows)

decimalpt

The character being used as the decimal separator

thousandssep

The character being used as the thousands separator

applicationname

InDesign, InCopy or InDesign Server

applicationversion

applicationversion

workspacefolder

The location of the EasyCatalog workspace folder.

Parameters

ENV(Name)

Example
ENV('username')

Using environment values can be handy to document about the document itself. This could simply be text at the beginning or the end of the document detailing who created the document, what version of Easycatalog was used, what the name of the data source was.. etc.

ENV

EVALUATEXPATH

Evaluate an XPath expression on a fields content, which should contain an XML fragment.

Requires the XML data provider module.

Parameters

EVALUATEXPATH(field name, xpath, (optional)separator)

Example
EVALUATEXPATH(XML,'/products/item/name/text()',' / ')

The field name 'XML' contains a block of XML data. The field 'XML_Evaluated_XPATH' is been asked to go and extract all the 'name' fields out of the XML data, and concatenate them using the '/' as a seperator.

EVALUATEXPATH
<?xml version="1.0" encoding="UTF-8"?>
<products>
<item>
    <sku>3890</sku>
    <brand>Cunka</brand>
    <name>BBQ Potatoe Chips</name>
    <weight>120g</weight>
</item>
<item>
    <sku>2331</sku>
    <brand>Cunka</brand>
    <name>Classic Shapes</name>
    <weight>80g</weight>
</item>
<item>
    <sku>3765</sku>
    <brand>Cunka</brand>
    <name>Spicey Chicken</name>
    <weight>87g</weight>
</item>
<item>
    <sku>4501</sku>
    <brand>Cunka</brand>
    <name>Pizza Shapes</name>
    <weight>95g</weight>
</item>
<item>
    <sku>4222</sku>
    <brand>Cunka</brand>
    <name>Sea Salt Chips</name>
    <weight>81g</weight>
</item>
</products>

FIELDNAME

Returns the name of the field using this command

Parameters

FIELDNAME()

FIELDNAME()
FIELDNAME

FIELDSTR

Returns the contents of a field

Parameters

FIELDSTR(field name)

Example
FIELDSTR(ItemName)
FIELDSTR

FIELDVAL

Returns the numerical contents of a field. This function will only return a value for numeric fields

Parameters

FIELDVAL(field name)

Example
FIELDVAL(Prices_$)
FIELDVAL

FILESIZE

Returns the size (in bytes) of the specified file. If no file is found, it returns a value of -1.

Parameters

FILESIZE(file path)

Example
FILESIZE(FIELDSTR(File_Path))

Listing file sizes in bytes from the field "File Path". If no file is found you can see the result listed as "-1" in the "Get_FILESIZE" field.

FILESIZE

FILLDOWNSTR

Takes the contents of a given field and fills down empty values

Parameters

FILLDOWNSTR(field name, sorting)

Example
FILLDOWNSTR(Size,Sort)

In this example we have only one value listed in "Size". To apply it to the rest of the items displayed, we use FILLDOWNSTR in the field "Sizes_FillDown".

FILLDOWNSTR

FINDFIELDCONTAINING

Search all fields, returns the name of the first field that matches the given regular expression

FINDFIELDCONTAINING(regular expression)

Example
FINDFIELDCONTAINING('^Warning')

Search for the word "Warning" at the beginning of a string.

FINDFIELDCONTAINING

FOLDERDEEPSEARCH

Search a given path for a matching file, including sub folders. A number of regular expressions can be supplied. First match is returned.

Parameters

FOLDERDEEPSEARCH(folder path/empty string for the picture content location path, expression 1, expression 2, …​)

Example
FOLDERDEEPSEARCH('', FIELDSTR(Code).*.PNG|JPG)

This next example works under the assumption that the images follow a particular pattern, where an image name will be that of its code. So if you know the name of the code, then the image should be code.png or code.jpg.

(We could have quite easily made it PDF, EPS, AI, TXT or any other file type)

The first image below shows the field 'Images_FolderDeepSearch' is told the root location to search in is my C drive under a folder called "Cunka". I don’t need to tell it anything more even if it contains more folders, and sub folders of those folders!

FOLDERDEEPSEARCH3

This image shows the subfolders that exist under my "C:\Cunka" folder.

FOLDERDEEPSEARCH2

Here is the result, where EasyCatalog finds the folders, lists the paths and shows in this instance a preview image.

FOLDERDEEPSEARCH1

FOLDERSEARCH

Search a given path for a matching file. A number of regular expressions can be supplied. First match is returned.

Parameters

FOLDERSEARCH(folder path/empty string for the picture content location path, expression 1, expression 2, ..)

Example
FOLDERSEARCH('', FIELDSTR(Code).*.PNG|JPG)
FOLDERSEARCH3
FOLDERSEARCH2
FOLDERSEARCH1

FORMATASTABLE

Format a delimited value list as a HTML table

Parameters

FORMATASTABLE(input string, row delimiter, column delimiter, (optional)number of header rows, (optional)output column count, (optional)output column fill index )

Example
FORMATASTABLE(FIELDSTR(MelbourneSensors),'^n',',')

This example we are taking some comma seperated text (originally CSV) and creating a nice HTML table out of it.

You can see the contents of the field "MelbourneSensors".

FORMATASTABLE1

You can see the result in the field "table_FORMATASTABLE".

FORMATASTABLE2

Its important to set the field "table_FORMATASTABLE" to HTML.

FORMATASTABLE3

I’ve already design a nice table style with InDesign called "cunkaTable". To make sure the field "table_FORMATASTABLE" uses it, I’ve set it up in the fields "General" setting with "Prefix" & "Suffix"

FORMATASTABLE4

Here is the final result.

FORMATASTABLE5

Source comma seperated data used in the field "MelbourneSensors".

Sensor ID,Sensor Name,Sensor Description,Year Installed,Location Type,Latitude,Longitude
3,Swa295_T,Melbourne Central,2009,Outdoor,-37.81101523,144.9642949
13,Wil277_T,Flagstaff Station,2009,Outdoor,-37.81239679,144.9565265
18,Col12_T,Collins Place (North),2009,Outdoor,-37.81344861,144.9730535
25,MCEC_T,Melbourne Convention Exhibition Centre,2013,Outdoor,-37.82401776,144.9560443
58,Bou688_T,Bourke St - Spencer St (North),2018,Outdoor,-37.81686074,144.9535808
2,Bou283_T,Bourke Street Mall (South),2009,Outdoor,-37.81380667,144.9651672
20,LtB170_T,Chinatown-Lt Bourke St (South),2013,Outdoor,-37.81172913,144.9682466
10,BouHbr_T,Victoria Point,2009,Outdoor,-37.81876473,144.9471055
49,Eli501_T,QVM-Therry St (South),2017,Outdoor,-37.80730067,144.9595606
37,Lyg260_T,Lygon St (East),2015,Outdoor,-37.80310271,144.9667145
21,Rus180_T,Bourke St-Russell St (West),2013,Outdoor,-37.81244703,144.9677876
40,Spr201_T,Lonsdale St-Spring St (West),2015,Outdoor,-37.80999341,144.9722759

FORMATSTRBOOST

Format a string using boost::format

Parameters

FORMATSTRBOOST(format string, pairs of (value, type[integer, string, float] ) )

Example
FORMATSTRBOOST('Latitude %.4f  //  Longatude %.4f', FIELDSTR(Latitude), float, FIELDSTR(Longatude), float)

Take some latitude & longatude field values that are rounded to 6 decimal place accuracy, concatenate them together and round to 4 decimal place accuracy.

FORMATASTRBOOST
Example
FORMATSTRBOOST('%.x', FIELDSTR(Decimal_Numbers), integer)

Pass a decimal number and convert it to hexadecimal.

FORMATASTRBOOST2

FRACTODEC

Turns a fractional value into decimal

Parameters

FRACTODEC(string, precision)

Example
FRACTODEC(FIELDSTR(FRACTION),4)
FRACTODEC

GETBARCODEGLYPHS

Returns the glyphs to use from the specified barcode font

Parameters

GETBARCODEGLYPHS(font name)

Example
GETBARCODEGLYPHS(FIELDSTR(Font_Name))
GETBARCODEGLYPHS

GETFIELDPLACECOUNT

Get the place count of a given field.
Returns the number of times the field has been placed in the front-most document (currently active document).

Parameters

GETFIELDPLACECOUNT(field name)

Example
GETFIELDPLACECOUNT(File)

This example has some PDF pages placed in the document as images. You can can see even though the images are on the document page the field "Display_GETFIELDPLACECOUNT" still has the count of 0. To update the count, right click on the field column in the data source panel and select from the menu "Update Selected Custom Field(s)". This occurs becuase the GETFIELDPLACECOUNT field is only ever tracking the front-most document. If many documents are open, it is only the currently active document (the front-most document) that GETFIELDPLACECOUNT does the count on.

GETFIELDPLACECOUNT

The count for the amount of times the "File" column images appear in the document is now shown.

GETFIELDPLACECOUNT2

GETFIELDPLACESTATE

Get the place state of a given field.
Returns the values "unplaced","unknown","ok","error".

Parameters

GETFIELDPLACESTATE(field name)

Example
GETFIELDPLACESTATE(File)

This example has some PDF pages placed in the document as images. You can can see even though the images are on the document page the field "Display_GETFIELDPLACESTATE" still has the state of unplaced. To update the state, right click on the field column in the data source panel and select from the menu "Update Selected Custom Field(s)". This occurs becuase the GETFIELDPLACESTATE field is only ever tracking the front-most document. If many documents are open, it is only the currently active document (the front-most document) that GETFIELDPLACESTATE calculates a fields state on.

GETFIELDPLACESTATE1

The state of each records field "File" now has its state shown. If its not in the document, it is "unplaced". If its in the document ist state is "OK".

GETFIELDPLACESTATE2

GETNTHPOPULATEDPARAM

Given any number of parameters, returns the n’th non-empty parameter (starting from zero)

Parameters

GETNTHPOPULATEDPARAM(field index, parameter…​)

Example
GETNTHPOPULATEDPARAM(0,FIELDSTR('Current_Price'),FIELDSTR('Future_Price'),FIELDSTR('Price_Flag'))

In this example we have three pricing fields. We always want to make sure an item has a price, and by default the "Price_Flag" is always set to "POA". So we want the order to be to return the "Current_Price" first. If it has no value go to the "Future_Price" field. If it has no value as well return the "Price_Flag".

GETNTHPOPULATEDPARAM

GETSCRATCHDOCUMENTID

Returns the ID of a scratch document, for using with SNIPPETDEPTH and SNIPPETWIDTH commands

Parameters

GETSCRATCHDOCUMENTID(full path or filename in the data source Assets folder)

Example
GETSCRATCHDOCUMENTID(FIELDSTR(File))
GETSCRATCHDOCUMENTID

The "Assets" folder is located in the Data Source (eg. cunka.com in this case) folder you are using in your "EasyCatalog Workspace". The "Assets" folder contains the file "Cunka_Template.indd".

GETSCRATCHDOCUMENTID2

GOOGLEQRCODEURL

Generates a Google Charts URL to create a QRCode with the given content

Needs a connection to the internet.

Parameters

GOOGLEQRCODEURL(width, height, content)

Example
GOOGLEQRCODEURL(500,500,FIELDSTR(URL))
GOOGLEQRCODEURL

Populate the field with content for text representation of what the image will contain. Do this by simply grabbing, as in this example, the contents of the field 'URL'.

GOOGLEQRCODEURL4

The 'Picture Content' of the field is where the GOOGLEQRCODEURL command is put. Take careful note the default setting of "Folder" has been changed to "URL".

GOOGLEQRCODEURL2

This is the output result.

GOOGLEQRCODEURL3

GROUPAVG

Returns the average value of a given field in a group

Parameters

GROUPAVG(group path delimited by colons, field to average)

Example
GROUPAVG('Entertainment:Brand','Price')

Takes all the "Price" fields in the group "Entertainment:Brand", adds them up, then returns the result in the field "TVprice_GROUPAVG".

GROUPAVG

GROUPCOLLATEPAGES

Creates a field which can be used to group all records that fit a page

Parameters

GROUPCOLLATEPAGES(group path delimited by colons, field to sort by, page depth, page width in points, field containing record depth in points, field containing header depth in points, field containing header width in points)

Example
GROUPCOLLATEPAGES('', Lot_Number, 769, 523, RowDepth, HeaderWidth, HeaderDepth)

GROUPCOUNT

Returns the number of groups or records in a group

Parameters

GROUPCOUNT(group path delimited by colons)

Example
GROUPCOUNT('Entertainment:Brand')

Takes the group "Entertainment:Brand", and counts the amount of records, then returns the result in the field "Count_GROUPCOUNT".

GROUPCOUNT

GROUPCOUNTUNIQUE

Returns the number of unique instances of a fields content in a group

Parameters

GROUPCOUNTUNIQUE(group path delimited by colons, field to count instances of)

Example
GROUPCOUNTUNIQUE('Entertainment:Brand','Screen')

Takes the group "Entertainment:Brand", looks in the field "Screen" and counts how many unique values are in it.This example has the values "HD" and "4K" so it will display 2 in the field "Count_GROUPCOUNTUNIQUE".

GROUPCOUNTUNIQUE

GROUPCREATEPAGINATIONGROUPINGS

Used to create groupings by a specified size, usually a page size

Parameters

GROUPCREATEPAGINATIONGROUPINGS(group path delimited by colons, field to sort by, size available, field containing record size, adjust by field, sub grouping field )

Example
GROUPCREATEPAGINATIONGROUPINGS(Cat,Sort,728.549,ROWDEPTH,IMAGEROWADJUSTER,SubCat)

GROUPCROSSTABLEHEAD

Returns cross table column heading

Parameters

GROUPCROSSTABLEHEAD(group path delimited by colons, field to sort by, field to cross by, heading number (0..n))

Example
GROUPCROSSTABLEHEAD(,,GlassType,0)
GROUPCROSSTABLEHEAD1

This example starts here and extends across to the GROUPCROSSTABLEVALUE command.

Here we have data for a door company that has products with different configurations. With any particular door style, there are various glass styles that can go into the door. We start this example off by creating all the table headers - which will be coming from the glass styles.

Create Column1 header.

GROUPCROSSTABLEHEAD2
Example
GROUPCROSSTABLEHEAD(,,GlassType,1)

Create Column2 header.

GROUPCROSSTABLEHEAD3
Example
GROUPCROSSTABLEHEAD(,,GlassType,2)

Create Column3 header.

GROUPCROSSTABLEHEAD4

GROUPCROSSTABLEVALUE

Returns cross table cell content

Parameters

GROUPCROSSTABLEVALUE(group path delimited by colons, field to sort by, field to lookup, field to match, field contents to return)

Example 1
GROUPCROSSTABLEVALUE('DoorType:DoorStyle','','GlassType','Column1','StyleCode','-')

This example continues from the example given in GROUPCROSSTABLEHEAD.

Create a column for the Column1 values

GROUPCROSSTABLEVALUE1
Example 2
GROUPCROSSTABLEVALUE('DoorType:DoorStyle','','GlassType','Column2','StyleCode','-')

Create a column for the Column2 values

GROUPCROSSTABLEVALUE2
Example 3
GROUPCROSSTABLEVALUE('DoorType:DoorStyle','','GlassType','Column3','StyleCode','-')

Create a column for the Column3 values

GROUPCROSSTABLEVALUE3

Create a table to populate the data into.

GROUPCROSSTABLEVALUE4

Final result. Shows each Door Style in the grey column. Shows the Glass Styles across the top in the black row. Relevant data is populated underneath.

GROUPCROSSTABLEVALUE5

GROUPFIRST

Returns the value of a given field for the first record in a group

Parameters

GROUPFIRST(group path delimited by colons, field to sort by, field to return)

Example
GROUPFIRST('Entertainment:Brand','Price','Series')
GROUPFIRST

GROUPGETNTHPOPULATEDFIELDNAME

This command accepts a group path, an index number and a list of field names. It will look within the given groupings and return the name of n’th populated column.

This command will accept a list of field names and return the name of the n’th populated one. This function is useful for creating ‘Column 1 Name’, ‘Column 1 Value’, ‘Column 2 Name’, ‘Column 2 Value’, etc data columns.

Field name can be a regular expression.

Parameters

GROUPGETNTHPOPULATEDFIELDNAME(group path,field index (starting at 0),field 1 name, field 2 name…​ )

Example
GROUPGETNTHPOPULATEDFIELDNAME('Entertainment:Brand',0,Name,Series,Price)

Works in a similar way to GETNTHPOPULATEDPARAM. The difference is it works on the group "Entertainment:Brand" and is looking to return field names. The sequence is "Name", "Series" and "Price". Its been told to look for populated fields in "Name" first, thus in this example they are all populated so it returns "Name" in the "Display_GROUPGETNTHPOPULATEDFIELDNAME" field. However, if one of the name fields was empty, it would return the next in the sequence which is "Series".

GROUPGETNTHPOPULATEDFIELDNAM

GROUPGRIDLAYOUTORDER

Create a numerical sequence value which enable records to be paginated on a grid.

This takes a page grid size, and fields for each records size, then assigns a sort order to each record, enabling them to be paginated using guide based pagination.

Parameters

GROUPGRIDLAYOUTORDER(group path delimited by colons, field to sort by, row count, column count, width field, height field)

Example
GROUPGRIDLAYOUTORDER('Parent Category:Child Category','',4,3,x,y)

GROUPINDEX

Creates an index based on the given field names.

Parameters

GROUPINDEX(group path delimited by colons, page number, field names to index,…​)

Example
GROUPINDEX('Entertainment:Brand',PageNumber,Brand)
GROUPINDEX

GROUPISFIRST

Returns TRUE for a record in the first n positions of a group

Parameters

GROUPISFIRST(group path delimited by colons, field to sort by, (optional)number of positions - default is 1)

Example
GROUPISFIRST(Entertainment:Brand,Price)
GROUPISFIRST

GROUPISLAST

Returns TRUE for a record in the last n positions of a group

Parameters

GROUPISLAST(group path delimited by colons, field to sort by, (optional)number of positions - default is 1)

Example
GROUPISLAST(Entertainment:Brand,Price)
GROUPISLAST

GROUPLAST

Returns the value of a given field for the last record in a group

Parameters

GROUPLAST(group path delimited by colons, field to sort by, field to return)

Example
GROUPLAST(Entertainment:Brand,Price,Series)
GROUPLAST

GROUPLIST

Create a series of values in a group.
The series can be separated by optional parameters for first, regular and last occurance.
The default is seperator is comma.

Parameters

GROUPLIST(The default is comma group path delimited by colons, field to sort by, field to concat, (opt.)first separator, (opt.)regular separator, (opt.)last separator, (opt.)add all, (opt.)add empty values)

Example
GROUPLIST(Entertainment:Brand,Price,Series,' / ' ,' / ',' / ')

Sometimes you may want a field in a group of records wrapped up so all the values can be seen in one field divided by a seperator of our choice. By using GROUPLIST we can achieve this.

This example takes the group "Entertainment:Brand", sorts it by the "Price" field. Then concatenates all the values in the "Series" field together using the " / " seperator, into the field "Display_GROUPLIST".

GROUPLIST

GROUPMAX

Returns the maximum value of a given field in a group

Parameters

GROUPMAX(group path delimited by colons, field to max)

Example
GROUPMAX(Entertainment:Brand,Price)

Using the group "Entertainment:Brand" , the maximum value in "Price" is found and returned into the field "Display_GROUPMAX".

GROUPMAX

GROUPMIN

Returns the minimum value of a given field in a group

Parameters

GROUPMIN(group path delimited by colons, field to min)

Example
GROUPMIN(Entertainment:Brand,Price)

Using the group "Entertainment:Brand" , the minimum value in "Price" is found and returned into the field "Display_GROUPMIN".

GROUPMIN

GROUPNUMBERSEQUENCE

Given a list of page numbers, create a list of page number ranges.

Parameters

GROUPNUMBERSEQUENCE(group path delimited by colons, page number field)

Example
GROUPNUMBERSEQUENCE(Entertainment:Brand,Page_Numbers)

This example takes the group "Entertainment:Brand", then concatenates all the values in the "Page_Numbers" field together into the field "Display_GROUPNUMBERSEQUENCE".

GROUPNUMBERSEQUENCE

GROUPONCHANGE

Returns TRUE everytime a field changes, FALSE otherwise

Parameters

GROUPONCHANGE(group path delimited by colons, field to sort by, field to check for changes)

Example
GROUPONCHANGE(Entertainment:Brand,Price,Brand)

Takes the group "Entertainment:Brand", sorts by the "Price" field, then looks at when the field "Brand" changes. The result TRUE (when the "Brand" changes) or FALSE is then returned into the field "Display_GROUPONCHANGE".

GROUPONCHANGE

GROUPRTOTAL

Returns the running total of a given field in a group

Parameters

GROUPRTOTAL(group path delimited by colons, field to sort by, field to total)

Example
GROUPRTOTAL(Entertainment:Brand,Price,Price)

Using the group "Entertainment:Brand" , the field "Price" is used to sort the order, then each record for "Price" calculates a running total of the "Price" field and is returned into the field "Display_GROUPRTOTAL".

GROUPRTOTAL

GROUPSCRIPT

Call a LUA based script. A 'recordset' object is passed with the group contents. The returned result is a table. (For use in a Tabular field)

Parameters

GROUPSCRIPT(group path delimited by colons, field to sort by, script name)

Example
GROUPSCRIPT('Group1','Price','Brians.lua')

The field format of "Display_GROUPSCRIPT" must firstly be set to "Tabular". The "Source:" must be then be set to "Command Script".

GROUPSCRIPT1

Put the command into the "Custom Field" contents.

GROUPSCRIPT2

The result shows the table returned by the "Brians.lua" script.

GROUPSCRIPT3
--[[

    Brians.lua
    Put this script into the "Scripts" folder of the datasource

    by Brian Cowell  contact@cunka.com

]]

-- create a new table
mytable = TABLE.new();

-- EasyCatalog passes a recordset to LUA
-- Starting at the first record loop through each one
for i=1,recordset:size() do
  -- get the current record
  myRecord = recordset:getrecord(i)
  -- get the fields Group2, Name, Price, Size & Status from the record
  group2=myRecord:field('Group2')
  name=myRecord:field('Name')
  price=myRecord:field('Price')
  size=myRecord:field('Size')
  status=myRecord:field('Status')
  -- add the  rows and columns to the table
  mytable:cell(i,1):setcontent(group2:content())
  mytable:cell(i,2):setcontent(name:content()..' '..size:content())
  mytable:cell(i,3):setcontent('$'..price:content()..' ('..status:content()..') ')
end

-- return the table
mytable:present();

GROUPSEQUENCE

Returns one value from a sequence depending on where the record appears in a group

Parameters

GROUPSEQUENCE(group path delimited by colons, field to sort by, colon delimited sequence list, (optional) field name - TRUE to include record in sequence)

Example
GROUPSEQUENCE('Entertainment:Brand','Price','A:B:C:D')

Using the group "Entertainment:Brand" and sorting by the "Price" field, take the sequence of "A:B:C:D" and sequentially apply it to the records and return the result in the "Display_GROUPSEQUENCE" field.

While this example simply used "A:B:C:D", it could have easily been colors,InDesign master page names, numerical numbers etc.

GROUPSEQUENCE

GROUPSEQUENCEONFIELDCHANGE

Returns one value from a sequence depending on where the record appears in a group

Parameters

GROUPSEQUENCEONFIELDCHANGE(group path delimited by colons, field to sort by, colon delimited sequence list, field name - reset sequence when this field has content)

Example
GROUPSEQUENCEONFIELDCHANGE('Entertainment','Price','black:white:red','Series')

Using the group "Entertainment:Brand" and sorting by the "Price" field, take the sequence of "black:white:red", sequentially apply it to the records when the field "Series" changes. Then return the result in the "Display_GROUPSEQUENCEONFIELDCHANGE" field.

Now the trick to GROUPSEQUENCEONFIELDCHANGE is not what content is in the field "Series", but whether content exists or does not exist.

The sequence starts off with "Black" and always uses "Black" if the field "Series" has content. The first empty field in "Series" becomes "White" and the next empty becomes "Red". However, if there is content in "Series", it refers back to "Black".

GROUPSEQUENCEONFIELDCHANGE

GROUPSERIES

Populate a group with a numerical series

The direction of sorting (ascending/descending) can be set in the custom field group path and sort parameters.
Prefix each field name with ‘<’ for a descending sort; ‘>’ for an ascending sort. If unspecified, the default is an ascending sort

Parameters

GROUPSERIES(group path delimited by colons, field to sort by, starting integer, increment, (optional)increment every nth record count)

Example
GROUPSERIES(Entertainment:Brand,Price,10,10)

Using the group "Entertainment:Brand" , populate the "Display_GROUPSERIES" field from the groups first record with incrementing numbers, starting at 10 and incrementing by amounts of 10.

Counting restarts at a new group.

GROUPSERIES

GROUPSERIESONFIELDCHANGE

Populate a group with a numerical series that increments each time a given field changes value

Parameters

GROUPSERIESONFIELDCHANGE(group path delimited by colons, field to sort by, field to monitor for changes, starting integer, increment, (optional) true/FALSE - include blank fields, (optional)increment every nth change )

Example
GROUPSERIESONFIELDCHANGE(Entertainment:Brand,Price,Series,10,10,true)

Using the group "Entertainment:Brand" and sorting by the field "Price", look for changes in the field name "Series". The changes we are looking for are not the content itself, its if there is or is not any content at all. If the field "Series" does have content, then the first occurence will start off with the number 10, and increment by the count of 10 for every subsequent occurence.

Counting restarts at a new group.

GROUPSERIESONFIELDCHANGE

GROUPSNIPPETDEPTH

Returns the depth of a snippet when rendered with records in a group

Parameters

GROUPSNIPPETDEPTH(group path delimited by colons, field to sort by, snippet path)

Example
GROUPSNIPPETDEPTH(Group1:Group2,Sort,FIELDSTR(mySnippet))
GROUPSNIPPETDEPTH

GROUPSUM

Returns the total of a given field in a group

Parameters

GROUPSUM(group path delimited by colons, field to add up )

Example
GROUPSUM(Entertainment:Brand,Price)

Using the group "Entertainment:Brand" , get all the values in the "Price" fields and calculate there sum total. The result is returned into the field "Display_GROUPSUM".

GROUPSUM

GROUPTABULARHEADERUNION

Takes tables from a group of records and creates tables with a common set of headers

Parameters

GROUPTABULARHEADERUNION(group path, tabular field name )

Example
GROUPTABULARHEADERUNION(Section:Category,AttributeList)

GROUPXREFFIELD

Returns the value of a field from another record in a group

Parameters

GROUPXREFFIELD(group path delimited by colons, field to sort by, field to search for, field content to search for, field contents to return )

Example
GROUPXREFFIELD('Parent Category:Child Category',''PartNo',FIELDSTR('XRefPartNo'),'Page')

GROUPXREFFIELDLIST NEW !!!

Behaves like XREFFIELDLIST, but this function limits searches to the specified group.

Parameters

GROUPXREFFIELDLIST(group path, sort field, field to search, field content to search for, field contents to return, (optional)first separator, (optional)middle separator, (optional)end separator)

Example
GROUPXREFFIELDLIST('Parent:Child','Price','PartNo',FIELDSTR('XRefPartNo'),'Page')

HTMLCLEAN

Cleanup raw HTML using a HTML5 parsing algorithm. Balances start/end tags and adds missing tags html

Parameters

HTMLCLEAN()

Example
HTMLCLEAN(FIELDSTR(DataTable))

HTMLCOLUMNCOUNT

Returns the maximum number of columns in a HTML table.
Returns 0 if one doesn’t exist

Parameters

HTMLCOLUMNCOUNT(html string)

Example
HTMLCOLUMNCOUNT(FIELDSTR(HTMLtable))
HTMLCOLUMNCOUNT

Source HTML table used in the field "HTMLtable".

<table>
    <tbody>
    <tr>
        <td>Item Code</td>
        <td>Name</td>
        <td>Weight</td>
        <td>Stock</td>
    </tr>
    <tr>
        <td>CNK-BBQ</td>
        <td>Cunka BBQ Shapes</td>
        <td>100g</td>
        <td>Available</td>
    </tr>
    <tr>
        <td>CNK-SAV</td>
        <td>Cunka Salt &amp; Vinegar</td>
        <td>95g</td>
        <td>Available</td>
    </tr>
    <tr>
        <td>CNK-PZZ</td>
        <td>Cunka Pizza Shapes</td>
        <td>107g</td>
        <td>On Order</td>
    </tr>
    <tr>
        <td>CNK-BAC</td>
        <td>Cunka Bacon &amp; Cheese</td>
        <td>110g</td>
        <td>Available</td>
        </tr>
    </tbody>
</table>

HTMLENTITYDECODE

Decode a string with HTML entities.

HTML entities are

Character Entity Value Description

&nbsp;

Inserts A Non-Breaking Blank Space

&

&amp;

Ampersand

&para;

Paragraph Symbol

§

&sect;

Section Symbol

"

&quot;

Quotation Mark

©

&copy;

Copyright Symbol

®

&reg;

Registered Symbol

&trade;

Trademark Symbol

&ldquo;

Opening Double Quotes

&rdquo;

Closing Double Quotes

&lsquo;

Opening Single Quote Mark

&rsquo;

Closing Single Quote Mark

&bull;

Big List Dot

·

&middot;

Medium List Dot

&hellip;

Horizontal Ellipsis

|

&#124;

Vertical Bar

¦

&brvbar;

Broken Vertical Bar

&ndash;

En-Dash

Em-Dash

«

&laquo;

Angle Quotation Mark (Left)

»

&raquo;

Angle Quotation Mark (Right)

&lsaquo;

Single Left Angle Quotation

&rsaquo;

Single Right Angle Quotation

Parameters

HTMLENTITYDECODE(string)

Example
HTMLENTITYDECODE(FIELDSTR(HTMLEntity))
HTMLENTITYDECODE

HTMLROWCOUNT

Returns the maximum number of rows in a HTML table.
Returns 0 if one doesn’t exist.

Parameters

HTMLROWCOUNT(html string)

Example
HTMLROWCOUNT(FIELDSTR(HTMLtable))

This example uses the same HTML code used in the HTMLCOLUMNCOUNT example.

HTMLROWCOUNT

I2OF5

Encodes the given numerical value into barcode font glyphs in the Interleaved 2 of 5 format.

Parameters

I2OF5(string)

Example
I2OF5('1234567890')

IF

Evaluate a condition, returning TRUE/FALSE or optional values

Parameters

IF(string, operand, value, (optional)value if TRUE, (optional)value if FALSE)

Example
IF(FIELDSTR(Price), '>', 2500, 'YES ! The price is greater than 2500', 'No. The price is less than 2500')
IF1
Example
IF(FIELDSTR(Price), '>', 2500)

Shows TRUE or FALSE

IF2

IMAGEASPECT

Determines the aspect of an image field (Width / Height)

Parameters

IMAGEASPECT(field name)

Example
IMAGEASPECT(Image)
IMAGEASPECT

IMAGEPATH

Returns the full path of the image for the given field

Parameters

IMAGEPATH(field name)

Example
IMAGEPATH(Image)
IMAGEPATH

INDEXOF

Find the character index of one string within another, starting at the specified text index.

Returns -1 if nothing is found.

Parameters

INDEXOF(string to search within, string to search for, index to start from (default 0))

Example 1
INDEXOF(FIELDSTR(Series),'-')

Find the index of "-" (the amount of characters in the string) and return the numerical result.

INDEXOF
Example 2
INDEXOF(FIELDSTR(Name),'sonic')

Find the index of "sonic" (the amount of characters in the string) and return the numerical result. If it does not find an index, it returns the value of -1.

INDEXOF2

LASTINDEXOF

Find the character index of one string within another - working backwards through the string - starting at the specified text index.

Parameters

LASTINDEXOF(string to search within, string to search for, index to start from (defaults to the end of the string) )

Example
LASTINDEXOF(FIELDSTR(Name),'a')

Sometimes there may be more then one occurence, this finds the last occurence. In this example we are finding the letter "a" in "Panasonic" and "Samsung".

Keep in mind counting of characters starts at 0.

LASTINDEXOF

LEFTSTR

Returns the left part of a field

Parameters

LEFTSTR(field name, number of characters)

Example
LEFTSTR(FIELDSTR(Brand),4)
LEFTSTR

LENGTH

Returns the number of characters in the given field.

Parameters

LENGTH(the string to return the length of)

Example
LENGTH(FIELDSTR(Brand))
LENGTH

LITERAL

Returns the contents of the given parameter. This function is useful for passing a string literal to a command that expects a field name

Parameters

LITERAL(string)

Example
LITERAL('abcdefg')

LOADFILE

Load a Unicode encoded file

Parameters

LOADFILE(file path)

Example 1
LOADFILE(FIELDSTR(TextFiles))

This loads in a simple text file containing no Unicode encoding.

LOADFILE
Example 2
LOADFILE(FIELDSTR(TextFiles))

This loads in a text file containing Unicode encoding.

LOADFILE2

LOOKUP

Searches a field in each record and then returns a value for another field. Handles multiple matches.

Returned values are a table.

If a data source name is not included, the LOOKUP will be applied to its own data source panel by default.

Parameters

LOOKUP(search string, search field, return field(s), data source name)

Example
LOOKUP(FIELDSTR(ID), ID, 'Description,Price', accessories.xls)

LOWER

Returns the contents of a field in lower case

Parameters

LOWER(field name)

Example
LOWER(Series)
LOWER

MAX

Returns the maximum of the arguments

Parameters

MAX(argument1, argument2, …​ )

Example
MAX(FIELDSTR(Price1),FIELDSTR(Price2),FIELDSTR(Price3))

Takes the values in the fields "Price1", "Price2", "Price3" and returns the maximum value in the field "Display_MAX".

Will also accept a comma sperated list if only 1 argument is supplied.

MAX

MIN

Returns the minimum of the arguments

Parameters

MIN(argument1, argument2, …​ )

Example
MIN(FIELDSTR(Price1),FIELDSTR(Price2),FIELDSTR(Price3))

Takes the values in the fields "Price1", "Price2", "Price3" and returns the minimum value in the field "Display_MIN".

Will also accept a comma sperated list if only 1 argument is supplied.

MIN

MOD

Returns the remainder after a number is divided by a divisor

Parameters

MOD(number, divisor)

Example
MOD(FIELDSTR(Amount),FIELDSTR(DividedBy))
MOD

MUL

Multiply one number by another

Parameters

MUL(number, number)

Example
MUL(FIELDSTR(Amount),FIELDSTR(MultipliedBy))
MUL

PARTSTR

Returns part of a delimited field such as 'a,b,c'

Parameters

PARTSTR(field, index (starting at 0), delimiter)

Example
PARTSTR(DelimitedText,FIELDSTR(Index),FIELDSTR(DelimiterUsed))
PARTSTR

PDFCROPTO

Sets the PDF crop option. Can be used in the picture import location.

Cropping values can be contentvisibleonly, art, page, trim, bleed, media, contentalllayers.

Parameters

PDFCROPTO(cropping value)

Example
PDFCROPTO(bleed)C:\EC_Commands

This example uses a PDF that has a bleed setting on it.
The field name "File" contains the CUNKA2.PDF.

PDFCROPTO

The field name "File" is set up for the scaling to fill the frame from the top left and has the command PDFCROPTO(bleed)C:\EC_Commands placed in the picture import location.

PDFCROPTO2

This is the PDF placed on the page with its bleed still in place.
The bleed is the blue frame around the placed PDF.

PDFCROPTO3

PDFIMPORTPAGE

Sets the PDF page to import.
Can be used in the picture import location to force a specific page to import.

One thing that should be observed using PDFIMPORTPAGE is that the data source panel does not preview the page it is importing. The preview shown is a low res image of page 1 from the PDF.
Parameters

PDFIMPORTPAGE(page number to import, starting from 1 )

Example
PDFIMPORTPAGE(FIELDVAL(Page))C:\EC_Commands

This examples uses CUNKA.PDF. Here are the 4 pages in the PDF.

PDFIMPORTPAGE1

The preview in the data source panel shows a low res picture of page 1.
The example will be importing page 2 of the CUNK.PDF into the document.

PDFIMPORTPAGE2

The PDFIMPORTPAGE command is in the "picture location" along with the file path (Windows7) to the location of the PDF. Take note that each page has its own "Page" field (using FIELDVAL()) that instructs what page to import.

PDFIMPORTPAGE3

Page 2 is imported and placed on the page.

PDFIMPORTPAGE4

PDFPAGECOUNT NEW !!!

Returns the number of pages in the given PDF.
Will return a value of 0 if the PDF cannot be opened or parsed.

Parameters

PDFPAGECOUNT(filepath to PDF)

Example
PDFPAGECOUNT('C:\EC_Commands\CUNKA.PDF')

PDFTRANSPARENTBACKGROUND

Sets the PDF transparent background import option on or off. Can be used in the picture import location

Parameters

true/false

Example
PDFTRANSPARENTBACKGROUND(TRUE)

RANDOM

Creates a random number integer in the specified range

Parameters

RANDOM(minimum value, maximum value)

Example
RANDOM(FIELDVAL(Minimum), FIELDVAL(Maximum))
RANDOM

RECORDTIMESTAMP

Return a records timestamp

Parameters

RECORDTIMESTAMP()

Example
RECORDTIMESTAMP()
RECORDTIMESTAMP

REGEX

Search and replace the given string using a regular expression.

A regular expression is a special text string for describing a search pattern.

There are a few online resource tools that can help you build regular expressions and educate how they work.

Parameters

REGEX(the string to search, a regular expression, the replacement string)

Example 1
REGEX(FIELDSTR(Text), '[a-zA-Z]','')

Removes any characters from "a-z" and "A-Z". Not specifying a replacement string removes characters.

REGEX1
Example 2
REGEX(FIELDSTR(Text), '([a-zA-Z]+,|\s)','')

This REGEX examples also removes characters. However, it is been very specific with what it chooses. It is looking for any whitespace as well as characters from "a-z" and "A-Z"..

REGEX2
Example 3
REGEX(FIELDSTR(Product Code), '^(\d{3}-)',FIELDSTR(Prefix)-)

In this REGEX example we are looking at replacing the first values of Product Code with a new designated Prefix (eg CAT). The conditions for this REGEX is it must only replace a Product Code that begins with 3 numbers,and must leave the other Product Codes as they are.

REGEX3

REGEXESCAPE

Escapes the regular expression reserved characters in the provided string content.

Here is the list of reserved characters use by REGEXESCAPE.

Regular Expression Reserved Characters

[

\

^

$

.

|

?

*

+

(

)

{

}

Regular expressions contains reserved characters required to perform pattern matching. If you use say the + character as part of pattern matching a regular expression, it must be escaped through the use of the \ character, otherwise it may not be found.

1+1
1\+1

Using the custom reference REGEXESCAPE there is no need to provide the \.

Parameters

REGEXESCAPE(string)

Example
REGEXESCAPE(FIELDSTR(myField))

REGEXV1

Search and replace the given string using a regular expression.
This uses an older regular expression parser and is more limited then REGEX. This parser will run faster then REGEX if the expression can be run.

Parameters

REGEXV1(the string to search, a regular expression, the replacement string)

Example
REGEXV1(FIELDSTR(Stock Code), '^(...)(...)(..)','ABC')

REMOVEBLANKLINES

Removes blanks lines from a given string. Only lines ending with a hard return (called "Forced Line Breaks" with InDesign) are removed. Formattings tags are ignored

Parameters

REMOVEBLANKLINES()

Example
REMOVEBLANKLINES(FIELDSTR(TextWithBlankLines))

Shows text with blank lines.

REMOVEBLANKLINES1

Shows result with blank lines removed.

REMOVEBLANKLINES2

REMOVEDUPLICATES

Removes duplicate values from the given string

Parameters

REMOVEDUPLICATES(separator,string)

Example
REMOVEDUPLICATES(FIELDSTR(Delimiter),FIELDSTR(TEXT))

This example has delimited text with many duplicates. By using the REMOVEDUPLICATES we can remove the duplicate occurences between the delimiter.

The screenshot below shows the orginal text, the delimiter and the processed result in the "Display_REMOVEDUPLICATES" field.

REMOVEDUPLICATES

REPLACE

Performs a simple search-and-replace operation on the source string.

Parameters

REPLACE(source string, search text, replace text)

Example 1
REPLACE(FIELDSTR(Series), '-', '')

Find and remove all occurences of the "-" character in the "Series" field and show results in the "Display_REPLACE" field.

REPLACE
Example 2
REPLACE(FIELDSTR(Series), '-7', '**')

Find and replace all occurences of the "-7" string in the "Series" field with "**" and show results in the "Display_REPLACE" field.

REPLACE2

RESOLVEGROUPING

Resolves a parent / child hierarchy into a full path, separated by >>. group id, data source name, group field name to return, group id field name, parent group id field name

Parameters

RESOLVEGROUPING()

Example
RESOLVEGROUPING(FIELDSTR(Group ID), groups_table, Group Name, Group ID, Parent ID)

RIGHTSTR

Returns the right part of a field

Parameters

RIGHTSTR(field name, number of characters)

Example
RIGHTSTR(FIELDSTR(Series),3)
RIGHTSTR

ROUNDVAL

Round a given value

Parameters

ROUNDVAL(value, precision, TRUE/FALSE - remove trailing zeros))

Example 1
ROUNDVAL(FIELDSTR(Price),2,FALSE)
ROUNDVAL
Example 2
ROUNDVAL(FIELDSTR(Price),2,TRUE)

Rounds to 2 decimal places and removes any trailing 0’s.

ROUNDVAL2

SENTENCECASE

Returns the contents of a field in sentence case

Parameters

SENTENCECASE(field name)

Example
SENTENCECASE(Description)
SENTENCECASE

SNIPPETDEPTH

Returns the depth in POINTS of a snippet for each record.
This command will be useful to calculate how many records can fit on a page.

For performance reasons turn off the ‘Automatically Update Content’ option on the Custom Field Field Options pane.

Parameters

SNIPPETDEPTH(file path to snippet)

Example
SNIPPETDEPTH(FIELDSTR(mySnippet))

The snippets depths are measured in points.

SNIPPETDEPTH

SNIPPETWIDTH

Returns the width in POINTS of a snippet when populated in a temporary document

Parameters

SNIPPETWIDTH(file path to snippet)

Example
SNIPPETWIDTH(FIELDSTR(mySnippet))

The snippets widths are measured in points.

SNIPPETWIDTH

SORT

Sorts the given delimited string into ascending or descending order.

SORT also identifies numeric ranges (eg. 1-3, 3-15) as numbers. However, it only sorts the number preceeding the hyphen.

Parameters

SORT(ascending/descending,separator,string)

Example 1
SORT(TRUE,FIELDSTR(Delimiter),FIELDSTR(Text))

Sort the delimited text into ascending order. (TRUE)

SORT1
Example 2
SORT(FALSE,FIELDSTR(Delimiter),FIELDSTR(Text))

Sort the delimited text into descending order. (FALSE)

SORT2
Example 3
SORT(TRUE,FIELDSTR(Delimiter),FIELDSTR(Text))

Sort the delimited text that includes numeric ranges into ascending order. (TRUE)

SORT3

SQL

Execute an SQL statement. Data Sources are virtual tables.

Requires the Relational module.

Parameters

SQL(statement, output format(xml/html/htmlnoheader/text/textnoheader))

Example
SQL('SELECT * FROM ''ACCESSORIES'' WHERE ID = 123','HTML')

STRIPWHITESPACE

Remove whitespace from a string

Parameters

STRIPWHITESPACE( the string, (optional) TRUE to remove all whitespace, FALSE to remove just at the start and end. defaults to FALSE)

Example 1
STRIPWHITESPACE(FIELDSTR(BadText), TRUE)
STRIPWHITESPACE1
STRIPWHITESPACE2
Example 2
STRIPWHITESPACE(FIELDSTR(BadText), FALSE)
STRIPWHITESPACE3

SUB

Description

Returns the value or the secondary arguments subtracted from the first

Parameters

SUB(argument1, argument2, …​)

Example
SUB(FIELDSTR(CustomersPrice), FIELDSTR(Discount),FIELDSTR(Variation))

Takes the value in the field "CustomersPrice" and subtracts the values in fields "Discount" and "Variation" from it and returns the value in the field "Final_Price_SUB".

SUB

SUBSTR

Description

Returns part of a field

Parameters

SUBSTR(field name, start index starting at 0, length)

Example
SUBSTR(FIELDSTR(Name),0,4)
SUBSTR

SUM

Description

Returns the sum of the arguments

Parameters

SUM(argument1, argument2, …​)

Example
SUM(FIELDSTR(Price),FIELDSTR(Postage))

Takes the values in the fields "Price" & "Postage", calulates there sum and returns the value in the field "Display_SUM"

SUM

TABULARVALUE

Description

Return cell contents from the given tabular field

Parameters

TABULARVALUE(field name, field id, record id)

Example
TABULARVALUE('Accessories','1','1')

TITLECASE

Description

Returns the contents of a field in title case

Parameters

TITLECASE(field name)

Example
TITLECASE(Name)
TITLECASE

TRUNCATESTR

Description

Removes the last N characters from a string

Parameters

TRUNCATESTR(string, number of characters to remove)

Example
TRUNCATESTR(FIELDSTR(Text),4)
TRUNCATESTR

UNIQUESTR

Description

Return the unique entries in a given string input

Parameters

UNIQUESTR(string, input separator, output separator)

Example
UNIQUESTR(FIELDSTR(Text),',','|')

Works in a similar way to the REMOVEDUPLICATES command.

UNIQUESTR

UPC

Description

Returns a UPC barcode.

Requires the font CarolinaBarUPC.

Parameters

UPC(numerical value)

Example
UPC(UPCcode)
UPC

UPPER

Description

Returns the contents of a field in upper case

Parameters

UPPER(field name)

Example
UPPER(Brand)
UPPER

URLDECODE

Description

Decodes the given URL string. URL must begin with 'http' or 'https'.
For security purposes, its best to use only URLs that begin with 'https'.

Parameters

URLDECODE(string to decode)

Example
URLDECODE(FIELDSTR('EncodedURL'))
URLDECODE

URLENCODE

Description

Encodes the given URL string. URL must begin with 'http' or 'https'.
For security purposes, its best to use only URLs that begin with 'https'.

Parameters

URL encoding replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits.

URLENCODE(string to encode)

Example
URLENCODE(FIELDSTR('Image Names'))
URLENCODE

URLSTR

Description

Retrieves a string from a URL

Parameters

URLSTR(url string, (optional )username and password seperated by a colon for HTTP authentication)

Example 1
URLSTR(http://feeds.bbci.co.uk/news/rss.xml)
Example 2

Getting a string from a URL that requires password authentication

URLSTR(‘https://www.mywebsite’,’jdoe:password’)

WORDWRAP

Description

Word wraps the given string to a specified line length

Parameters

WORDWRAP(string, line length, break character (optional))

Example
WORDWRAP(FIELDSTR(Text),4,^n)
WORDWRAP1
WORDWRAP2

XREFFIELD

Description

Returns the value of a field from another record.
Returns the first instance found.

There is an option to do advanced cross referencing across data sources

Searches can be a "search for" using the % character in the search string as a prefix and suffix. This allows searching the beginning of a string, the ending of a string, or whether a string contains specific content.

  • Containing
    % character at the prefix and suffix of the search string.
    Search anywhere in the string for the characters "XXXX". eg. '%XXXX%'

  • Begins with
    % character at the prefix of the search string.
    Search the beginning of the string for "CatNo.". eg. '%CatNo.'

  • Ends with
    % character at the suffix of the search string.
    Search the end of a string for the image extension ".JPG". eg. '.JPG%'

Parameters

XREFFIELD(field to search, field content to search for, field contents to return, (optional)data source to search)

Example
XREFFIELD('PartNo',FIELDSTR('xRefPartNo'),'Page')

This example shows the cross referencing of a product items page (Cordless Drill) and an accessories page (batteries).

XREFFIELD

XREFFIELDLIST

Description

As XREFFIELD, but this function will return a separated list of results

Parameters

XREFFIELD(field to search, field content to search for, field contents to return, (optional)first separator, (optional)middle separator, (optional)end separator, (optional)data source to search)

Example
XREFFIELDLIST('PartNo',FIELDSTR('XRefPartNo'),'Page',',',',',' and ')

©2019 Brian Cowell, Cunka.com

Automation with EasyCatalog

EasyCatalog can use any of the three available scripting languages that InDesign uses. The focus here is Adobes flavour of JavaScript and EasyCatalogs inbuilt adaption of the LUA programming language.

JavaScript control of EasyCatalog requires the purchase of the optional Scripting plug-in available from 65bit. No additional modules are required for programming with LUA.

Paginating large catalogues

<COMING SOON>

INDESIGN

Close dialog windows

With InDesign, its quite easy to run with a lot of dialog windows open. This can become a problem with documents adding up to hundreds of pages. +

Resources on speeding up InDesign

David Blatner’s article called Why is InDesign so slow? : https://indesignsecrets.com/why-is-indesign-soooo-slow.php

Erica Gamet’s article called 6 Tips to Speed Up InDesign : https://indesignsecrets.com/6-tips-speed-up-indesign.php

EASYCATALOG

Many open data source panels

If you are doing a lot of development with EasyCatalog, its quite easy to accumulate a lot of open data source panels. The panels dont need to be visible, they only need to be open. This means EasyCatalog will be loading and tracking them, as well as InDesign.

Now with small data source panels, this may not become an issue. However, if you are dealing with thousands of records with many panels open, you will notice sluggish behaviour from EasyCatalog and InDesign. Shut down and close panels you are not using.

Configuration files

<TO DO>

Stay up to date

Due to a change with InDesign we started noticing a script ran for 4 hours started hitting 5 hours for pagination for a 1000 page catalogue. Our analysis showed the size of the data had not increased, nor the complexity of the pagination in the libraries. After a few weeks of testing the previous version of EasyCatalog/InDesign and the newer versions, we found that InDesign was activating the "preflight" panel while paginating. This added a lot of overhead into InDesign as the preflight was now checking the pages as EasyCatalog was doing its work !

As a consequence, we notified 65bit who then fixed the issue with an update. As of version 14.0.0 automatic pre-flight is now disabled while before pagination commences. Stay up to date with EasyCatalog.

Using LUA sockets slows performance

Setting "Enable Sockets" to TRUE is only useful for debugging LUA. It can also slow the performance of EasyCatalog. When running scripts, ensure you have turned this parameter back to FALSE.

InDesign Preferences → EasyCatalog → Advanced → LUA "Enable Sockets"

Adobe InDesign Javascript

Determine the users operating system

operatingSystem = $.os.indexOf('Win') >= 0 ? "Windows": "Mac";

File path seperator

If you plan on retrieving or saving files through scripting, you can use through the operating system discovery to determine which directory seperator to use.

File paths can be different from Windows to a Mac. If a script may run on either, its best to get the script to determine what directory seperator to use and hold the result in a variable.

dirSeparator = $.os.indexOf('Win') >= 0 ? "//": "\";

Track the time taken

With long running processes, its handy to know how long a script will take to run.

$.hiresTimer; // starts the timer.
// Final script time taken calculation
var time = $.hiresTimer / 1000000;
alert("Total Time : " + time.toFixed(2) + " seconds");

Improve InDesigns speed

app.scriptPreferences.enableRedraw = false;

Close all currently open InDesign libraries

You can close all the currently open InDesign libraries in various ways. Here is the shortest method.

app.libraries.everyItem().close();

Here is the longer method.

var myLibraries = app.libraries; // get all open libraries
if (myLibraries.length > 0) {
    var libraryNames = (myLibraries.everyItem(0).name).toString(); // string containing all library names
    for (var i = myLibraries.length - 1; i > -1; i--) { // looping backwards because closing libraries changes the indexes
        if (myLibraries[i].associatedPanel != null && myLibraries[i].associatedPanel.visible == true) {
            myLibraries[i].associatedPanel.visible = false;
        }
        myLibraries[i].close(); // file closed
    }
}

Close all the documents currently open

The following will close all the open documents without saving.

app.documents.everyItem().close(SaveOptions.NO);

Applying InDesign master pages

// Get the currently opened document
myDoc = app.activeDocument;

// Get the first page and change the master spread to "D-Delta"
myDoc.pages.firstItem().appliedMaster = myDoc.masterSpreads.item("D-Delta");
InDesign Master Page

Using layers

Layers allow you a greater depth of design flexibility with an InDesign template. EasyCatalog "furniture" and libraries can be easily used.

You should always make sure you are paginating with EasyCatalog into the "active" layer. Otherwise you will see blank pages.
Layers 1

Make a layer visible.

myDoc = app.activeDocument;
myDoc.layers.itemByName("Red").visible = true;

Hide a layer.

myDoc = app.activeDocument;
myDoc.layers.itemByName("Red").visible = false;

Set a layer to be "active".

//Set the active layer
myDoc = app.activeDocument;
myDoc.activeLayer = myDoc.layers.itemByName("Green");

Create a log file

A log file is very handy to have to track progress of a script, keep data on what was used, or simply diagnose issues.

The code below uses a timestamp to put into the file name. The actualy writting of the text file is handled through a function called logWrite(text). You simply call the function when you want something written into a log file. It will calculate the time and if a file exists, it will append to it, or create a new file should one not exist.

var timeNum = new Date().getTime();  // used if you create a log file that requires a time stamp
function logWrite(text) { // write the logging file
    var myTextFilePath = logFilePath + timeNum + "_log.txt";
    var myTextFile = new File(myTextFilePath);
    if (myTextFile.exists) {
        myTextFile.open("e");
        myTextFile.seek(0, 2);
    } else {
        myTextFile.open("w");
    }
    var d = new Date().toLocaleString();
    myTextFile.write(d + " ");
    myTextFile.write(text);
    myTextFile.close();
}

Example of writing text to the file.

…​. // write text to a file
logWrite("Begin STAGE 1");
…​. // do some EasyCatalog pagination
…​. // write more text to the file
logWrite("STAGE 1 has completed.");

Additional resources

The InDesign JavaScript Reference Guide
http://jongware.mit.edu/idcs6js/index.html

The InDesign scripting playground
http://www.indiscripts.com/

InDesign scripts by Peter Kahrel
http://www.kahrel.plus.com/indesignscripts.html

EasyCatalog Javascript

Scripting Module Documentation

The "EasyCatalog Object"

EasyCatalog scripting begins with the creation of the "EasyCatalog Object".

var myEasyCatalog = app.easycatalogObject;

Alternatively, you can skip storing the object in a variable and continue to reference it directly. Examples throughout this guide will reference the EasyCatalog Object directly, but its more common to use a variable.

Here is an example showing the EasyCatalog Object usage in both instances and both result in the same thing.

var myEasyCatalog = app.easycatalogObject;
var myDataSources = myEasyCatalog.datasources.everyItem().name;
//
// Above is the same as below
//
var myDataSources = app.easycatalogObject.datasources.everyItem().name;

Data Sources

All EasyCatalog Data Sources must exist in the "EasyCatalog Workspace" folder.

A Data Source can be referenced directly.

var myDS = app.easycatalogObject.datasources.item("ElectronicParts.xlsx")

Alternatively, you can also collect all available Data Sources in an array and choose one.

var myDataSources = app.easycatalogObject.datasources.everyItem().name;

To make all the data sources easily selectable, use a dropdown box in a panel.

var srcnameField = dropdowns.add({stringList: myDataSources, selectedIndex: 0});

The value srcnameField is used to capture the selected data source from the myDataSources array.

var dataSourceName = myDataSources[srcnameField.selectedIndex];

Use selected the Data Source selected from the array.

try { //ensure the data source name is valid
    var myDS = app.easycatalogObject.datasources.item(dataSourceName);
    var myDV = myDS.dataviews.item(dataSourceName);
    alert("Data Source File: " +myDS.dataSourceSpecifier);
} catch (err) {
    alert("Cannot find data source " + dataSourceName);
    exit();
}

Using configuration files

Data panels can be set up so you can group your structure and apply a sort order to your data source. You can easily save your settings as a "configuration file".

EasyCatalog allows you to change between different configuration files quickly and easily. As an example, you may have a configuration file that generates all your contents, and another that creates your index.

myDV.applyConfiguration("Catalogue_contents");
//…​…​…​..
// Paginate the catalogue contents
// …​…​…​.
// Now change to a different configuration
myDV.applyConfiguration("Catalogue_index");
EasyCatalog Workspace Folder location

Close all open Data Sources

You can easily close all the open panels (Data Sources)

app.easycatalogObject.dataviews.everyItem().closeDataView();

Capturing pagination code

If you can manually paginate your document, you can automate it. At the pagination dialog, EasyCatalog gives you the opportunity to copy to the clipboard the Javascript settings to use in your script.

To capture to the clipboard, click on the symbol on the bottom left of the paginate dialog window.

myDSO.setPaginationOption("assettype","1")
myDSO.setPaginationOption("paginationtype","0")
myDSO.setPaginationOption("assetfield","")
myDSO.setPaginationOption("usegeometry","false")
myDSO.setPaginationOption("paginationlogic","1")
myDSO.setPaginationOption("librarylocation","")
myDSO.setPaginationOption("rulesetname","CUNKA_COLORS")
myDSO.setPaginationOption("insertpages","true")
myDSO.setPaginationOption("undosupport","true")
myDSO.setPaginationOption("continueonerror","false")
myDSO.setPaginationOption("optimizedcopy","false")
myDSO.setPaginationOption("updatefurnitureafterpagination","false")
myDSO.setPaginationOption("masterpaginationtype","0")
myDSO.setPaginationOption("flowbasedstylename","")
myDSO.setPaginationOption("restrictverticalmergetopagebounds","false")
myDSO.setPaginationOption("autoapplyparaspacebefore","false")
myDSO.setPaginationOption("flowbreakonfield","")
myDSO.setPaginationOption("flowbreakonfieldbreaktype","1")
myDSO.setPaginationOption("flowprocessfurnitureduringpagination","false")
myDSO.setPaginationOption("maximumnumberofpages","0")

Pagination script code

Capturing pagination rule code

Right click on an "Action" in the Pagination Rules window and select Copy Script Call. This will capture to the clipboard the Javascript code for the "Action" for use in a script.

Formatting rule code

app.easycatalogObject.setPaginationRule(myPageItem,"Brand","0x53500kInCatContainsNameKey","Panasonic","eShow");

Formatting rule code

app.easycatalogObject.setPaginationRule(myPageItem,"0x92100kFittingAttributeStringKey","0x92100kFittingAttributeValueFrameToContent");

EasyCatalog LUA

Set up "Enable Sockets"

Debugging LUA can be done remotely through the LUA ZeroBrane Studio IDE editor.
To connect the editor to EasyCatalg you need change the LUA "Enable Socket" parameter from FALSE to TRUE in the EasyCatalog Preferences.

Setting "Enable socket" to TRUE can slow down the performance of EasyCatalog. Recommended to turn back to FALSE when not debugging LUA.

InDesign Preferences → EasyCatalog → Advanced → LUA "Enable Sockets"

LUA Enable socket preference

Get a records contents using FIELD

Using the FIELD parameter, a reference to a field name for a record can be called using FIELD.get('XXXXX')
The contents for that field can be retrieved by using :content().

Example 1

This is a simple concatenation of two fields of a record using FIELD and returned as a new value.

-- Use FIELD to retrieve a fields content of the current record. This is grabbing the PartNo.
firstThing = FIELD.get('PartNo'):content();

-- Use FIELD to grab the current records contents. This is grabbing the xRefPartNo.
nextThing = FIELD.get('xRefPartNo'):content();

-- Simple concatenation of strings and return the result
return firstThing.." --> (Spare battery) "..nextThing;

LUA FIELDgetcontent2

LUA FIELDgetcontent

Example 2

Using a FIELD called 'Name', use that records content to first filter results, then return a tabular table.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Get the records content for the field 'Name'
currentName = FIELD.get('Name'):content();

-- Create a filter on the Name field looking for the current value of the variable currentName
filteredset = recordset:filter('Name',currentName)

-- Convert the fields of all the records to columns and rows into a table
-- use the following fields
result = filteredset:tableof('PartNo','Name','Type')

-- Pass the new table back to the tabular field
return result:present()

LUA FIELDgetcontent4

LUA FIELDgetcontent3

TableOf

Using TableOf, fields(s) can be grouped into a table and the result returned into a Tabular field.
By default if no field names are stipulated, the table returned is of the whole data panel.

The EasyCatalog field must be set up to be a tabular field.

LUA TableOf panel3

Example 1

No field names are stipulated to TableOf, so everything is returned to the tabular field.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Convert the fields of all the records to columns and rows into a table
-- By default, if no fields are specified all fields are used.
result = recordset:tableof()

-- Pass the new table back to the tabular field
return result:present()

LUA TableOf panel4

LUA TableOf panel

LUA TableOf panel2

Example 2

The TableOf parameter is now instructed to return a table made up from the 'PartNo','Name' & 'Type' fields.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Convert the fields of all the records to columns and rows into a table
-- Specify fields to use.
result = recordset:tableof('PartNo','Name','Type')

-- Pass the new table back to the tabular field
return result:present()

LUA TableOf panel5

Sorting a recordset

A recordset can be sorted further through the use of the :sort() method.
The :sort() method takes 1 or more field names to sort by.

Example

This example is asking the recordset to be sorted by the 'PartNo' field.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Sort the list of records by PartNo
recordset:sort('PartNo')

-- Convert the fields of all the records to columns and rows into a table
-- Specify fields to use.
result = recordset:tableof('PartNo','Name','Type')

-- Pass the new table back to the tabular field
return result:present()

Filtering a recordset

While having access to a recordset is handy, been able to filter the data down to a specific set of records can be a powerful tool. Through the use of the :filter() method, its possible within LUA to filter the recordset.

The :filter() method takes a minimum of two parameters. The field name and value.

Example

In this example the recordset is been asked to filter by the field name 'Name' and the value of 'Ryobi'. The new filtered recordset is stored in the variable filteredset.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Create a filter on the Name field looking for anything by Ryobi
filteredset = recordset:filter('Name','Ryobi')

-- Convert the fields of all the records to columns and rows into a table
-- use the following fields
result = filteredset:tableof('PartNo','Name','Type')

-- Pass the new table back to the tabular field
return result:present()

LUA Recordset filter

LUA Recordset filter2

Styling a tabular table

When a table is created in LUA, you can return the tabular table back with an existing InDesign Table style that exists in your document.
To do this, you use the :setstyle() method for tables and the name of the Table style in InDesign

Example

The table style 'Products' is applied to the tabular table.

-- Get the list of records
recordset = DATASOURCE.get():getrecordset()

-- Sort the list of records by PartNo
recordset:sort('PartNo')

-- Convert the fields of all the records to columns and rows into a table
-- Specify fields to use.
result = recordset:tableof('PartNo','Name','Type')

-- Use an existing InDesign table style to make the table pretty
result:setstyle("Products")

-- Pass the new table back to the tabular field
return result:present()

LUA TableStyle

LUA TableStyle2

Using Appearance to change the panel style

Each field in the datasource panel allows you to control how its displayed through the "Appearance" tab. With the use of color you can easily color co-ordinate your fields amongst many fields to display a better user experience.

The "Appearance" parameter goes one step further through the use of LUA. You can code in shapes (circles, squares) as well as custom colors. It also allows you to "conditionally" apply the shapes and color that are determined through field values.

You will see drawrect(x,y,width,height) used without x,y,width,height been declared. If you dont supply values in these fields, it defaults to its own internal values.

LUA Appearance 1

LUA Appearance 2

LUA Appearance 3

Example 1

This example uses conditions to define the "Appearance".
Through the 'Brand' field, the datasource is color co-ordinated dependent on whether 'Brand' contains the value 'Panasonic'. If it does the cells are colored Purple, if it isn’t the cell is colored Brick Red.

LUA Appearance 4

if field('Brand') == "Panasonic" then

-- set color to Purple
  setopacity(0.2)
  setcolor(102,0,102)
  drawrect(x,y,width,height)
else

-- set color to Brick Red
  setopacity(0.2)
  setcolor(153,0,0)
  drawrect(x,y,width,height)
end
Example 2

Easily change the "Appearance" colors. This example shows how to easily remove the LUA opacity setting to make colors brighter.

Appearance Colors

Appearance Color Table

Appearance Color Name

RGBA with opacity

RGB without opacity

Light blue

79, 153, 255, 0.2

79, 153, 255

Red

255, 0, 0, 0.2

255, 0, 0

Green

79, 255, 79, 0.2

79, 255, 79

Blue

0, 0, 255, 0.2

0, 0, 255

Yellow

255, 255, 79, 0.2

255, 255, 79

Magenta

255, 79, 255, 0.2

255, 79, 255

Cyan

0,255,255,0.2

0,255,255

Gray

127,127,127,0.2

127,127,127

Black

0,0,0,0.2

0,0,0

Orange

255,102,0,0.2

255,102,0

Dark Green

0,84,0,0.2

0,84,0

Teal

0,153,153,0.2

0,153,153

Tan

204,153,102,0.2

204,153,102

Brown

153,51,0,0.2

153,51,0

Violet

153,51,255,0.2

153,51,255

Gold

255,153,0,0.2

255,153,0

Dark Blue

0,0,135,0.2

0,0,135

Pink

255,153,204,0.2

255,153,204

Lavender

153,153,255,0.2

153,153,255

Brick Red

153,0,0,0.2

153,0,0

Olive Green

102,102,0,0.2

102,102,0

Peach

255,153,153,0.2

255,153,153

Burgundy

153,0,51,0.2

153,0,51

Grass Green

153,204,0,0.2

153,204,0

Ochre

153,102,0,0.2

153,102,0

Purple

102,0,102,0.2

102,0,102

Light Gray

186,186,18,0.2

186,186,18

Charcoal

170,163,181,0.2

170,163,181

Grid Blue

122,186,216,0.2

122,186,216

Grid Orange

255,181,107,0.2

255,181,107

Fiesta

247,89,107,0.2

247,89,107

Light Olive

140,165,107,0.2

140,165,107

Lipstick

206,130,181,0.2

206,130,181

Cute Teal

130,206,193,0.2

130,206,193

Sulphur

206,206,130,0.2

206,206,130

Grid Green

155,221,155,0.2

155,221,155

White

255,255,255,0.2

255,255,255

Overview of DOCUMENT

LUA TableStyle

LUA TableStyle

LUA TableStyle

Controlling a Frame from a Script Label

LUA commands can be used to control the behaviour of a Frame through the script label.

Example

The script label has LUA code in it, which on pagination determines from the field 'Brand' what objectstyle to apply to the frame. If its "Panasonic", it chooses one color, if its "Samsung" it chooses another.

getBrand = FIELD.get('Brand'):content()
if(getBrand=="Panasonic") then
  frame:applyobjectstyle("Panasonic")
else
  frame:applyobjectstyle("Samsung")
end

LUA Frame and script label

Overview of FIELD

LUA Field

Overview of RECORD

LUA Record

Overview of TEXT

LUA Text

Event Scripts

What are Event Scripts?

External scripts can be created and called in response to certain events in EasyCatalog. These are known as Event Scripts.

Event Scripts are programmed using Adobe Javascript. They are required to be placed in the Scripts sub folder located in the Data Source workspace.

Event Script parameters are accessed by the application object scriptArgs

// Example
var myID = Number(app.scriptArgs.getValue("id"));

PostLoadDataSource.jsx

250

Called after loading a Data Source into memory.

Parameters

datasource

//
// PostLoadDataSource.jsx
//
//
// by Brian Cowell
// http://www.cunka.com/easycatalog/myEasyCatalog.html
//
//
// OBJECTIVE : Get information the data source when the panel is loaded up.
//
//

// writes the Adobe ExtendScript console if it is open

$.writeln("---- POST LOAD DATA SOURCE SCRIPT ----");

// get the current data source name passed by the script

var ds = app.scriptArgs.getValue('datasource');
$.writeln("Loaded DATA SOURCE : "+ds);

var myDS = app.easycatalogObject.datasources.item(ds);
var myDV = myDS.dataviews.item(ds);
$.writeln("DATA SOURCE state : "+myDS.loadState);

var myDSFields = myDS.fieldNames;
$.writeln("Total Fields : "+myDSFields.length);

PostSynchronizeWithDataSource.jsx

300

Called after synchronizing the panel with the Data Source.

Parameters

datasource

PostPurgeDeleted.jsx

120

Called after removing records marked as deleted.

Parameters

datasource

PrePaginateDocument.jsx

Called just before paginating a document.

300
//
// PrePaginateDocument.jsx
//
//
// by Brian Cowell
// http://www.cunka.com/easycatalog/myEasyCatalog.html
//
//
// OBJECTIVE : Test to make sure Fields exist before paginating. If they DO NOT exist, the script will create them.
//
//

// writes the Adobe ExtendScript console if it is open

$.writeln("---- PRE PAGINATION SCRIPT ----");

// The field names we will be testing to make sure exists.

var fieldTestList =[
    "materialColor",
    "materialType",
    "materialTable",
    "selectionTable",
   "flammabilityRating"
];

// Get the currently selected Data Source

var ec = app.easycatalogObject;
var myDSV = ec.selectedDataView();
var myDS = myDSV.parent;

$.writeln(myDS.dataSourceName); // write the data source name to the console

// loop through list of fields to check
for (i = 0; i < fieldTestList.length; i++) {
    try{
        var option = myDS.getFieldOption(fieldTestList[i], "name");
        //$.writeln("Confirm field "+fieldTestList[i]+" exists.");
    }
    catch(err){
        custField(fieldTestList[i],""); // create field if it doesnt exist
        //$.writeln("Create custom field to replace missing field "+fieldTestList[i]);
    }
}

///////////////////////////////////////////////////////////////////

// Function to create the custom fileds
function custField(fieldName,fieldContent){
    try{
        myDS.addCustomField(fieldName,fieldContent);
        $.writeln("Created custom field : "+fieldName);
        }
    catch(err){
        $.writeln("FAILED to create custom field : "+fieldName);
        }
}

PostPaginateDocument.jsx

300

Called after document pagination

Parameters

datasource, documentTitle

PreUpdateDocument.jsx

400

Called before updating a document.

PostUpdateDocument.jsx

400

Called around updating fields in a document.

Parameters

datasource, document

PreImageImport.jsx

Called before importing an image.

PostImageImport.jsx

Called around image updates.

Parameters

datasource, field, key, id

PostPaginateItem.jsx

Master based pagination only.

150

Called after paginating an item.

Parameters

datasource, key, documentTitle, id

PaginationProgress.jsx

200

Called during pagination

Works with ADOBE InDesign Server only.

Parameters

datasource, stepindex, stepindex, stepmessage, id

Getting Help

You can go directly to the creators of EasyCatalog : EasyCatalog Support Page

Brian Cowell can be contacted at contact@cunka.com

©2019 Brian Cowell