# 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, 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. |
# 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 Template
Row - 1
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.
shrinkTextshrinks the font sizes of overflowing frames so that they no longer overflow.fitFramewill increase or decrease the height of the text frame so that the frames entire contents fits in it.fitTextresizes the fonts to, as much as possible, fill the entire frame with it's contents.
If you use thefindproperty 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 theallTextproperty to true, the entire contents of the frame will be fitted to the frame in the same way it does when using thetagSearchproperty.
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! |
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 Template - Row - 1
Row - 2
fittingMethod: fitText
Row - 3
fittingMethod: shrinkText
Row - 4
fittingMethod: fitFrame
Note: the size of the type on path frame is not changed and the text still overflows the path
Row - 5
# 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 |
composer | 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! |
everyLineComposer | Whether the every-line or single-line version of the text composer should be used Valid Values: true or false [Default] |
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 |
firstLineIndent | The fist line indent of the paragraph Sample Values: 12.7, 3mm, .5", 0p6 |
clearCharacterOverrides | Whether or not to clear all the paragraph and character styles overrides in the paragraph containing the text being targeted. Valid Values: false[Default] ortrue |
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 |
overprintFill | Whether or not to overprint the fill Valid Values: false or true |
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 |
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 |
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 |