reference
Table Of Contents
Color
background(bgColor)
Sets a background on the current page.
blendMode(obj, blendMode)
Sets the blend mode of a page item.
color(Get)
Gets or creates a color.
colorMode(colorMode)
Sets the color mode to RGB or CMYK.
fill(fillColor, [name])
Sets the fill color of shapes and text.
fillTint(tint)
Sets a tint for the current fill color.
gradient(c1, c2, [name])
Gets or creates a gradient.
gradientMode(gradientMode)
Sets the gradient mode to linear or radial.
lerpColor(c1, c2, amt)
Calculates colors between two other colors.
noFill()
Disables fill color of shapes and text.
noStroke()
Disables drawing a stroke around shapes.
opacity(obj, opacity)
Sets the opacity of a page item.
stroke(strokeColor)
Sets the stroke color.
strokeTint(tint)
Sets the tint of the current stroke color.
swatch(swatchName)
Gets a color swatch.
Data
Collections
forEach(collection, cb)
Runs a function on all elements of an array.
Conversion
binary(num, [numBits])
Converts a number to a binary string.
hex(value, [len])
Converts a number to a hex number.
unbinary(binaryString)
Converts a binary number string to a number.
unhex(hex)
Converts a hex number to a number.
CSV
CSV.parse(String, [delimiter])
Parses (decodes) a CSV string to an array.
CSV.stringify(Array, [delimiter])
Stringifies (encodes) an array to a CSV string.
HashList
HashList()
HashList is a data container to store key - value pairs.
HashList.clear()
Deletes all key - value pairs in a HashList.
HashList.get(key)
Gets a HashList value by its key.
HashList.getKeys()
Gets an array of all HashList keys.
HashList.getKeysByValues()
Gets an array of all HashList keys sorted by their values.
HashList.getSortedKeys()
Gets an array of all HashList keys in a sorted order from higher to lower magnitude.
HashList.getValues()
Gets an array of all HashList values.
HashList.hasKey(key)
Checks if a HashList key exists.
HashList.hasValue(value)
Checks if a HashList value exists.
HashList.remove(key)
Removes a HashList key - value pair by its key.
HashList.set(key, value)
Sets a HashList key - value pair.
JSON
JSON.parse(text, [reviver])
Parses (decodes) a string to a JSON object.
JSON.stringify(value, [replacer], [space])
Stringifies (encodes) an object or an array to a JSON string.
String Functions
contains(searchContainer, valueToFind)
Checks wether a string contains a specific string or if an array contains a specific element.
endsWith(searchContainer, valueToFind)
Checks wether a string ends with a specific string or if an array ends with a specific element.
join(array, separator)
Combines an array into a string.
nf(value, leftDigits, rightDigits)
Formats numbers into strings, with options for leading and trailing zeros.
nfc(value, leftDigits, rightDigits)
Formats numbers into strings, including comma separators to mark units of 1000.
nfp(value, leftDigits, rightDigits)
Formats numbers into strings, including a leading + or -.
nfs(value, leftDigits, rightDigits)
Formats numbers into strings, including a blank space before positive numbers.
split(str, [delim])
Splits a string using a specific string or character as divider.
splitTokens(str, [tokens])
Splits a string using a list of strings as dividers.
startsWith(searchContainer, valueToFind)
Checks whether a string starts with a specific string or if an array starts with a specific value.
trim(str)
Removes whitespace from the beginning or end of a string.
trimWord(s)
Removes whitespace and punctuation from the beginning and end of a string.
Type-Check
isArray(obj)
Checks wether a var is an array.
isInteger(num)
Checks wether a var is an integer.
isNumber(num)
Checks wether a var is a number.
isString(str)
Checks wether a var is a string.
isURL(url)
Checks wether a var is a valid URL string.
Document
clear(container)
Removes all page items in a given container.
close([saveOptions], [file])
Closes the current document.
doc([doc])
Creates a document or gets the current one.
group(pItems, [name])
Creates a group from page items or gets a group.
layer([layer])
Creates, sets or gets a layer.
referencePoint([referencePoint])
Sets the reference point for the transform() function.
remove(obj)
Removes an InDesign object.
revert()
Reverts a document to its last saved state.
ungroup(group)
Ungroups a group and returns its items.
units([units])
Sets the units of the document.
Canvas
bleeds([top], [right], [bottom], [left])
Sets the document bleeds.
canvasMode(mode)
Sets the dimensions of the working canvas.
guideX(x)
Creates a vertical guide line.
guideY(y)
Creates a horizontal guide line.
margins([top], [right], [bottom], [left], [pageNumber])
Sets or gets the margins of a page.
pasteboard(h, v)
Sets or gets the pasteboard margins.
Page
addPage([location])
Adds a new page to the document.
applyMasterPage(page, master)
Applies a master page to a page.
masterPage(master, [pageIndex])
Sets a master page to be the active page.
nextPage()
Jumps to the next page.
page([page])
Jumps to a page or gets the current one.
pageCount([pageCount])
Returns the number of pages in the document.
pageNumber([page])
Returns the page number of a page.
previousPage()
Jumps to the previous page.
removePage([page])
Removes a page from the document.
Page Items
applyObjectStyle(item, style)
Applies an object style to a page item.
arrange(pItemOrLayer, positionOrDirection, [reference])
Arranges a page item or layer before or behind other page items and layers.
bounds(obj)
Calculates the geometric bounds of a page item or text.
duplicate(item)
Duplicates a page or page item.
graphics(container, [cb])
Runs a function on a collection of graphics in a container or returns them.
items(container, [cb])
Runs a function on a collection of page items in a container or returns them.
label(itemOrLabel, label)
Tags a page item with a script label or finds an item by label.
labels(label, [cb])
Runs a function on all page items of a script label or returns them.
linkedTextFrames(item, [cb])
Runs a function on a chain of linked text frames or returns them.
nameOnPage()
Returns an item on the active page by name.
objectStyle(itemOrName, [props])
Creates or gets an object style.
selection([item])
Returns the first selected object or selects an object.
selections([cb])
Runs a function on all selected page items or returns them.
textFrames(container, [cb])
Runs a function on a collection of text frames in a container or returns them.
Text
addToStory(story, itemOrString, insertionPointOrMode)
Adds a page item or string to a story.
characters(container, [cb])
Runs a function on all characters in a container or returns them.
lines(container, [cb])
Runs a function on all text lines in a container or returns them.
linkTextFrames(textFrameA, textFrameB)
Links two textframes.
paragraphs(container, [cb])
Runs a function on all paragraphs in a container or returns them.
placeholder(textFrame)
Fills a text frame with placeholder text.
stories(container, [cb])
Runs a function on all stories in a container or returns them.
textStyleRanges(container, [cb])
Runs a function on all text style ranges in a container or returns them.
words(container, [cb])
Runs a function on all words in a container or returns them.
Type-Check
isText(obj)
Checks wether a var is an InDesign text object.
Environment
delay(milliseconds)
Pauses script execution for a certain amount of time.
frameRate([fps])
Sets the framerate of a looping script.
height
The height of the current page.
inspect(obj, [settings])
Inspects a var and lists its properties and methods.
printInfo()
Prints info about the current environment to the console.
projectFolder()
Gets the current document’s project folder.
property(obj, prop, [value])
Sets an objects property.
size([widthOrPageSize], [heightOrOrientation])
Sets the size of the current document.
width
The width of the current page.
Constants
stackArray
The name of the current script.
VERSION
The basil version.
Image
image(img, x, [y], [w], [h])
Adds an image to the document.
imageMode([mode])
Modiefies the location from which images draw.
Input
shellExecute(cmd)
Executes a shell command and returns the result.
Files
download(url, [file])
Downloads an URL to a file.
file(filePath)
Returns a file.
files([folder], [settings])
Gets all files of a folder.
folder([folderPath])
Returns a folder.
loadCSV(file, [delimiter])
Gets and parses the contents of a CSV file.
loadJSON(file, [userAgent])
Gets and parses the contents of a JSON file.
loadString(file, [userAgent])
Gets the contents of a file or loads an URL into a string.
loadStrings(file, [userAgent])
Gets the contents of a file or loads an URL into an array of its individual lines.
selectFile([settings])
Opens a dialog to select a file.
selectFiles([settings])
Opens a dialog to select multiple files.
selectFolder([settings])
Opens a dialog to select a folder.
Time & Date
day()
Returns the current day of the month.
hour()
Returns the current hour.
millis()
Returns the milliseconds since starting the script.
millisecond()
Returns the milliseconds of the current time.
minute()
Returns the current minute.
month()
Returns the current month.
second()
Returns the current second.
timestamp()
Returns a timestamp.
week()
Returns the current week number of the year.
weekday()
Returns the current day number of the week.
year()
Returns the current year.
Math
Calculation
abs(val)
Calculates the absolute value (magnitude) of a number.
ceil(val)
Calculates the closest integer value that is greater than or equal to the value of the parameter.
constrain(aNumber, aMin, aMax)
Constrains a value to not exceed a maximum and minimum.
dist(x1, y1, x2, y2)
Calculates the distance between two points.
exp(x)
The exp() function returns ex, where x is the argument, and e is Euler’s number
floor(a)
Calculates the closest integer value less than or equal to a value.
lerp(value1, value2, amt)
Calculates a number between two numbers at a specific increment.
log(x)
Calculates the natural logarithm of a number.
mag(x, y, [z])
Calculates the magnitude (or length) of a vector.
map(value, istart, istop, ostart, ostop)
Maps a number from one range to another.
max(a, [b], [c])
Determines the largest value in a sequence of numbers.
min(a, [b], [c])
Determines the smallest value in a sequence of numbers.
norm(aNumber, low, high)
Normalizes a number from another range into a value between 0 and 1.
pow(num, exponent)
Facilitates exponential expressions.
round(value)
Calculates the integer closest to a value.
sq(aNumber)
Squares a number.
sqrt(val)
Calculates the square root of a number.
Constants
EPSILON
Epsilon
HALF_PI
Half Pi
KAPPA
Kappa
PI
Pi
QUARTER_PI
Quarter Pi
SINCOS_LENGTH
Sin Cos Length
TWO_PI
Two Pi
Random
noise(x, [y], [z])
Returns the Perlin noise value at specified coordinates.
noiseDetail(octaves, fallout)
Adjusts the character and detail of the noise() function.
noiseSeed(seed)
Sets the seed value for noise().
random([low], [high])
Generates a random number or returns a random array item.
randomSeed(seed)
Sets the seed value for random().
Trigonometry
acos(value)
Returns the arc cosine of a value.
asin(value)
Returns the arc sine of a value.
atan(value)
Returns the arc tangent of a value.
atan2(y, x)
Calculates the angle from a specified point to the coordinate origin.
cos(rad)
Calculates the cosine of an angle.
degrees(aAngle)
Converts a radian measurement to the corresponding value in degrees.
radians(aAngle)
Converts a degree measurement to the corresponding value in radians.
sin(rad)
Calculates the sine of an angle.
tan(rad)
Calculates the ratio of the sine and cosine of an angle.
Vector
Vector(x, y, [z])
A class to describe a two or three dimensional vector.
Vector.add(v, [y], [z])
Adds x, y, and z components to a vector or adds one vector to another.
Vector.angleBetween(v1, v2)
Calculates the angle between two vectors.
Vector.array()
Returns the vector as an array.
Vector.cross(v1, v2)
Calculates the cross product of two vectors.
Vector.cross(v, [y], [z])
Calculates the cross product from this vector to another.
Vector.dist(v1, v2)
Calculates the Euclidean distance between two points.
Vector.dist(v, [y], [z])
Calculates the distance from this vector to another.
Vector.div(v, [y], [z])
Divides this vector through another.
Vector.dot(v, [y], [z])
Calculates the dot product from this vector to another.
Vector.dot(v1, v2)
Calculates the dot product of two vectors.
Vector.get()
Gets a copy of the vector.
Vector.heading()
Returns the 2D orientation of the vector.
Vector.limit(high)
Normalizes the length of the vector.
Vector.mag()
Calculates the magnitude of the vector.
Vector.mult(v, [y], [z])
Multiplies this vector with another vector.
Vector.normalize()
Normalizes the length of the vector to 1.
Vector.set(v, [y], [z])
Sets the x, y, and z component of the vector.
Vector.sub(v, [y], [z])
Substracts x, y, and z components or another vector from this vector.
Vector.toString()
Returns data about a vector as string.
Output
Console
print(msg)
Prints a message to the console.
println(msg)
Prints a message line to the console.
Files
saveCSV(file, data, [delimiter])
Encodes a CSV-object array to multi-line strings and saves it to a CSV file.
saveJSON(file, data)
Encodes an object to a JSON string and saves it to a JSON file.
savePDF(file, [showOptions])
Exports the document as PDF.
savePNG(file, [showOptions])
Exports the document as PNG.
saveString(file, string)
Writes a string to a file.
saveStrings(file, strings)
Writes an array of strings to a file.
Shape
pathToPoints(obj, [addPoints])
Get points and bezier coordinates from path(s).
Attributes
ellipseMode(mode)
Sets how new ellipses are drawn.
rectMode(mode)
Sets how new rectangles are drawn.
strokeWeight(weight)
Sets the stroke width for lines and borders.
Primitives
arc(cx, cy, w, h, startAngle, endAngle, [mode])
Draws an arc.
ellipse(x, y, w, h)
Draws an ellipse.
line(x1, y1, x2, y2)
Draws a line.
point(x, y)
Draws a point.
quad(x1, y1, x2, y2, x3, y3, x3, y3)
Draws a quad.
rect(x, y, w, h, [tl], [tr], [br], [bl])
Draws a rectangle.
triangle(x1, y1, x2, y2, x3, y3)
Draws a triangle.
Vertex
addPath()
Adds a new path during shape drawing.
beginShape()
Starts drawing a complex path or shape.
endShape(shapeMode)
Finishes drawing a complex path or shape.
vertex(x, y, [xLeftHandle], [yLeftHandle], [xRightHandle], [yRightHandle])
Adds a vertex during drawing complex paths or shapes.
Structure
mode(mode)
Sets the performance mode to allow hiding or freezing the document during script execution.
noLoop()
Stops basil from looping.
Transform
applyMatrix(matrix)
Multiplies the current matrix by another one.
popMatrix()
Pops the current transformation matrix off the matrix stack.
printMatrix()
Prints the current matrix to the console.
pushMatrix()
Pushes the current transformation matrix onto the matrix stack.
resetMatrix()
Replaces the current matrix with the identity matrix.
rotate(angle)
Rotates an object.
scale(scaleX, scaleY)
Scales an object.
transform(pItem, type, [value])
Transforms an object.
translate(tx, ty)
Translates (moves) an object.
Typography
createOutlines(item, [cb])
Convert text items to outlines.
text(txt, x, y, w, h)
Creates a text frame.
Attributes
textAlign(align, [yAlign])
Sets the text alignment.
textFont([fontName], [fontStyle])
Sets the text font.
textKerning([kerning])
Sets the text kerning.
textLeading([leading])
Sets the text leading.
textSize([pointSize])
Sets the text size.
textTracking([tracking])
Sets the text tracking.
typo(item, property, [value])
Sets text properties.
Constants
LOREM
A Lorem ipsum string.
Styles
applyCharacterStyle(text, style)
Applies a character style to text.
applyParagraphStyle(text, style)
Applies a paragraph style to text.
characterStyle(textOrName, [props])
Gets a text’s character style or gets a character style by name.
paragraphStyle(textOrName, [props])
Gets a text’s paragraph style or gets a paragraph style by name.