# Text

The text method is for changing the content and / or format of text and fitting texts to text frames or text frames to text.
Unlike Illustrator's native text variable where you can only change the entire contents of a text frame, with Darty-Ai you can change both the contents and format of either entire or parts of text frames.

# Targeting Text

To change the text of an entire text frame use the top row of the table or the tagSearch property and specify the tag of the text frame to be changed.
To change the text of specific words use the find property and specify the words to be changed.
By default only words surrounded by double {{curly}} or ((round)) parenthesis will be targeted.
Use the mode property to change this behavior.
To target specific words in a specified text frames, set both the tagSearch (or top row of the table) and the find properties. tagSearch: animals find: cat will target the instances of cat but only the ones found in text frames tagged animals.
If you want to target a single instance of a {{template}}, give it a unique name 😀

In the below sample text, if you use find: consectetuer adipiscing elit the fist two instances of the find text will be targeted, the third will not, because it is not surrounded by double parenthesis. When the text is changed the parenthesis will be removed.
If you want to target all instances of a set of words including ones not surrounded by parenthesis, use mode: all, that will target all instances, parenthesis will be not be removed.

Lorem ipsum dolor sit amet, {{consectetuer adipiscing elit}}, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi.
Lorem ipsum dolor sit amet, ((consectetuer adipiscing elit)), sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat, consectetuer adipiscing elit.

# Modes

In most cases you do not need to set mode, by default if the find property is used, words surrounded by double {{curly}} and ((round)) parenthesis will be targeted. If a tagSearch is set and the find property is not set and the entire contents of the tagged frame will be targeted.

Mode	Description
all	All instances of the `find` string will be targeted, parenthesis will not be removed
{	Instances of the `find` string which are surrounded by double {{curly}} parenthesis will be targeted, parenthesis will be removed
(	Instances of the `find` string which are surrounded by double {{round}} parenthesis will be targeted, parenthesis will be removed
{( `[DEFAULT]`	Instances of the `find` string which are surrounded by double {{curly}} or ((round)) parenthesis will be targeted, parenthesis will be removed
@	Will target the entire text of a text frame, this rarely needs setting as it will be the default behavior for when a `tagSearch` but not a `find` is set.

# Advanced Targeting with RegEx

Use modern ECMAScript-style regex, including the new v (Unicode sets) flag, for ultra-specific targeting of characters — even diacritics and emojis.

Regex	Matches
`[\u0600-\u06FF]`	All Arabic characters including diacritics
`/\p{Script=Arabic}\\|\p{M}/`	All Arabic characters, including diacritics
`/[[\u0600-\u06FF]--\p{M}]/v`	Arabic excluding diacritics
`/[[\u0600-\u06FF]&&\p{M}]/v`	Only Arabic diacritics
`/\p{Emoji}/`	All emoji characters
`/[\p{Emoji}--\p{ASCII}]/v`	Emojis without ASCII overlap

These regexes allow you to:

🎨 Color or format only diacritics, emojis, or specific script characters.
🧹 Remove unwanted characters like diacritics or control marks.
✍️ Apply fonts or text direction based on Unicode ranges.

Darty-Ai includes the u and g flags by default. Other flags (like i, m, or v) can be added manually after the closing /. You can also use patterns like \p{Emoji} without slashes, if no extra flags are needed.

# Replacing and Removing Text

replace is used to change the contents of the text. There is no need to quote find or replace strings, replace: Darty Ai is the as replace: "Darty Ai". To remove the find words, set replace to "", '' or ``, leaving replace blank will not work.

To replace a text frame with the contents of a file use the Place method.

# Text Attributes

The following text attributes can be set, See the text Method Properties and Screenshot for details.

baselineOption / position, charStyle, composer, everyLineComposer, color, firstLineIndent, fontSize, justification, leading, leftToRight, overprintFill, overprintStroke, paraStyle, strikeThrough, strokeColor, strokeJoin, strokeWidth, underline

# Styles and Overrides

You can apply paragraph and character styles Using the paraStyle and charStyle properties.
By default overrides will not be removed. Use the clearCharacterOverrides and clearParagraphOverrides properties to clear the paragraph and character styles overrides of the text being targeted. Use the clearOverridesOfWholeParagraph property to clear both the paragraph and character styles overrides of the entire paragraph.

# Sample Spreadsheet and Screenshots

																			image
details	*																		image
text					text		text		text		text			text					place
fontName	find: name	replace	fontSize	color	find: #	replace	find: birth	replace	find: death	replace	find: term	replace	underline	find: party	mode: all	replace	color	position	fit: fill	path: ~/Desktop/place/files_to_place/Presidents/
																			`fill`
Adobe Caslon Pro	`name`	George Washington	18	#999	`#`	1	`birth`	1732	`death`	1799	`term`	1789 - 1797	TRUE	`party`	`all`	Unaffiliated	#999		`fill`	1_George_Washington.jpg
Adobe Clean Bold SemiCondensed Italic	`name`	Thomas Jefferson	18	#EA9978	`#`	2	`birth`	1735	`death`	1826	`term`	1797 – 1801		`party`	`all`	Federalist	#EA9978		`fill`	2_Thomas_Jefferson.jpg
Adobe Garamond Pro	`name`	John Adams	24	#008000	`#`	3	`birth`	1743	`death`	1826	`term`	1801 – 1809		`party`	`all`	Democratic-Republican	#008000		`fill`	3_John_Adams.jpg
Adobe Garamond Pro Bold	`name`	James Madison	18	#008000	`#`	4	`birth`	1751	`death`	1836	`term`	1809 – 1817		`party`	`all`	Democratic-Republican	#008000		`fill`	4_James_Madison.jpg
Courier	`name`	James Monroe	18	#008000	`#`	5	`birth`	1758	`death`	1831	`term`	1817 – 1825		`party`	`all`	Democratic-Republican	#008000	super	`fill`	5_James_Monroe.jpg

Compare each row in the spreadsheet below with its associated screenshot below. The text frame is tagged 'details' The font has been applied to the entire text frame, the other properties have been set to the individual finds, note the * in the top tagSearch row

Original Artwork

Original Template

Row - 1

Offset Row - 2

Row - 2

Row - 3

Row - 4

Row - 5

# Fitting Methods

The fittingMethod property changes the font size or the text frames height to fit a frame's contents.

With it you can automatically:

Decrease the font size to make sure that text does not overflow.
Increase the frame height to make sure that text does not overflow.
As much as possible, fill the frame with it's contents by increasing or decreasing the font sizes.
Make a paragraph fill the text frame width.

The following values can be used: shrinkText, fitFrame, fitText and none.

You can specify specific frames to fit by using a tagSearch, otherwise set the tagSearch to * and all frames will be processed.
If you use the find property then only the paragraph containing the search string will be fitted unless you set the allText property to true.

fittingMethod works on text on paths (other than the fitFrame option) and in area text frames that have not been set to auto size, it does not work on point frames or area frame that have been set to auto size.

shrinkText shrinks the font sizes of overflowing frames so that they no longer overflow.
fitFrame will increase or decrease the height of the text frame so that the frames entire contents fits in it.
fitText resizes the fonts to, as much as possible, fill the entire frame with it's contents.
If you use the find property to specify specific text then by default the paragraph containing that text will be fitted to the width of the text frame.
If you set the allText property to true, the entire contents of the frame will be fitted to the frame in the same way it does when using the tagSearch property.

Note: You can an "Overset Text Fitting" option on the export tab to apply shrinkText and fitFrame to all texts in the document


*
text
find	fittingMethod

	`none`
	`fitText`
	`shrinkText`
	`fitFrame`
brown	`don't seem to make no difference what goes here!`

Original Artwork

Original Template - Row - 1

Row - 2

fittingMethod: fitText

The size of the text in each text frame has been proportionally increased or decreased so that the text, as much as possible, fills the frames and does not overflow

Offset Row - 3

Row - 3

fittingMethod: shrinkText

The size of the text in the overflowing text frames have been proportionally decreased so that they no longer overflow

Row - 4

fittingMethod: fitFrame

The height of the overflowing area text frames is increased so it's text no longer overflows
Note: the size of the type on path frame is not changed and the text still overflows the path

Row - 5

# Text-Direction & Composer Features

Darty-Ai provides fine-grained control over text direction, essential for accurate typesetting in Arabic, Hebrew, and similar right-to-left (RTL) languages.
Middle Eastern, Chinese, Japanese, and other language-specific typographic features can also be applied using paragraph and/or character styles — allowing full control over font behavior, punctuation, alignment, and more.

Composer Direction
Governs how the layout engine handles character flow, line breaks, and justification in this direction (rtl/ltr) using a particular composer.
Story Direction
Sets the base writing direction for the whole story (the entire continuous text flow). This is the “default” direction that new paragraphs and characters will inherit from.
Paragraph Direction
Overrides the story direction for that one paragraph. Useful if you have an RTL story but need an LTR heading in the middle, or vice versa.
Character Direction
Overrides paragraph direction for specific characters or spans. The default option here usually means “follow the paragraph/story direction.”

# Text Properties

Mode	Description
*	Set to `false` if you want the method to be skipped in a particular row. Valid Values: `true` or `false`
baselineOption / position	The position (and size) of the text in relation to the baseline Valid Values: `normal`, `superscript` `super`, `subscript` `sub`
charStyle ./ characterStyle	The case sensitive name of the character style to apply, be default overrides will not be cleared, to clear them use the clear overrides properties Sample Values: `My Char Style`, `Character Style 1`
charDirection	Text-direction of a character. Values are: `ltr`, `rtl` or `default`
composerEngine	The text composer to use Valid Values: `Adobe`, `ltr`, `latin` or `cjk` [Default] for Latin and CJK `middleEastern`, `middleEast`, `worldReady`, `rtl`, `Hebrew`, `Arabic` or `complex` for complex scripts like Hebrew, Arabic, Thai, Vietnamese, and Indic languages `adornment` is a third composer, we don't know what it is used for!
color / fillColor	The fill color of the text Sample Values: `orange` (CSS Orange), `0 40 100 0` (CMYK orange), `255 128 0` or `#ff8000` or `ff8000` (RGB Orange) `lab 66 44 74 Orange` (Create / Change a Swatch "Orange" with Lab values), `/Orange` (use an existing swatch called `Orange`), `none` See Swatch Methods for a description of swatch and color descriptions
clearCharacterOverrides	Whether or not to clear all the character style overrides in the text being targeted. Valid Values: `false`[Default] or`true`
clearParagraphOverrides	Whether or not to clear all the paragraph and character style overrides of the text being targeted. Valid Values: `false`[Default] or`true`
clearOverridesOfWholeParagraph	Whether or not to clear the paragraph and character style overrides in the entire paragraphs containing the targeted text. Valid Values: `false`[Default] or`true`
everyLineComposer	Whether the every-line or single-line version of the text composer should be used Valid Values: `true` or `false` [Default]
firstLineIndent	The fist line indent of the paragraph Sample Values: `12.7`, `3mm`, `.5"`, `0p6`
fontSize	The font size to use Sample Values: `12`, `12px`, `.5"`, `1cm`
font / fontFamily	The case insensitive name of the font family to use, if given the the style should be set using the `fontStyle` property Sample Values: `myriad Pro`, `Arial Black` ("Black" is part of the name and not the style), `Adobe 黑体 Std R`
fontStyle	The case insensitive name of the font style to use, can be used together with `font` / `fontFamily` but not `fontName` If the style does not exist then the style will not be changed Sample Values: `Bold`, `Italic`, `Condensed`, `semibold`
fontName	The name of the font including the font style Sample Values: `Myriad Pro Condensed`, `Arial Black Regular`
justification	The justification of the paragraph Valid Values: `left`, `right`, `center`, `fullLeft`, `fullRight`, `fullCenter`, `fullLeft`, `fullRight`, `fullCenter`, `full`
leading	The leading to use Sample Values: `12`, `12px`, `.5"`, `1cm`
leftToRight	Whether or not to apply a left to right character direction Valid Values: `true` [Default] or `false` suitable for right to left languages like Hebrew and Arabic
mode	The type of text / template to target Valid Values: `all` (targets text as is, no template parenthesis use), `{(` (templates must be surrounded with either double curly or round parentheses) [Default], `{{` (templates must be surrounded with double curly parentheses), `((` (templates must be surrounded with double round parentheses) See Modes
overprintFill	Whether or not to overprint the fill Valid Values: `false` or `true`
overprintStroke	Whether or not to overprint the stroke Valid Values: `false` or `true`
paraStyle / paragraphStyle	The case sensitive name of the paragraph style to apply, by default overrides will not be cleared, to clear them use the clear overrides properties Sample Values: `My Para Style`, `Paragraph Style 1`
strikeThrough	Whether or not strike through the text Valid Values: `false` or `true`
storyDirection	Text-direction of a Story. All contained paragraphs would now inherit this text-direction. Values are: `ltr` or `rtl`.
strokeColor	The stroke color of the text Sample Values: `orange` (CSS Orange), `0 40 100 0` (CMYK orange), `255 128 0` or `#ff8000` or `ff8000` (RGB Orange) `lab 66 44 74 Orange` (Create / Change a Swatch "Orange" with Lab values), `/Orange` (use an existing swatch called `Orange`), `none` See Swatch Methods for a description of swatch and color descriptions
strokeJoin	The shape to apply to the stroke's join Valid Values: `miter`, `round`, `bevel`
strokeWidth	The width of the stroke to apply Sample Values: `.5`, `1pt`, `.5mm`
underline	Whether or not underline the text Valid Values: `false` or `true`
skip	Set to `true` is you want the method to be skipped in a particular row. See * and Skip for details. Valid Values: `true` or `false`
find	The text / template you want changed (Case sensitive), specify a `tagSearch` if you want to limit the text changed to specific text frames. Use `mode` to specify what type of template to target. Sample Values: `name`, `address`
tagSearch	Specify a `tagSearch` if you want to limit the text changed to specific text frames. If no `find` is provided, the entire text frame will be changed. Sample Values: `cats`, `cats \| dogs`, `animals & !dogs`

← Tags Methods Transform Methods →