Trivial story: you just have reopened an old InDesign document — or even a fresh one — and dozens of obscure names populate the style panels. You do not remember what that pesky “TDM Sub2” style refers to, or what it looks like, or where it is used. So you'll have to run the F/C dialog, select a Find Format, etc. We have a faster solution: right-click the style and “Goto Sample”…

Yes, it's that dumb, we simply added a Goto Sample item to the style panel popup menu. The style doesn't even need to be actually selected, just right click on the name.

What happens then? The underlying script automatically does what you would have done by hand: it runs a Find query, gets a sample text (if any) and shows it to you. This way you can navigate very quickly from style to style, check the elements that interest you, give the style a more meaningful name, change its formatting attributes, and so on.

I've been waiting for this feature for years and still don't understand how InDesign developers never implemented it.

The Script “StyleListGotoSample”

The script StyleListGotoSample.jsx was designed as a “startup script”, so you will install the JSX file — or a shortcut to it — in a subfolder named startup scripts (instead of Scripts Panel). If such a subfolder does not exist in your current installation, just create it.

The last step is to restart InDesign, which makes the Goto Sample action available in your style panel popup menu. The feature applies to both the Paragraph Styles and Character Styles panel.

If you visit this website from time to time, you know that it contains a plethora of free InDesign scripts, but you may not know that other cool nuggets are regularly open-sourced in our GitHub repository called IdGoodies. The latter being hardly documented, here is an overview of some scripts—and interesting code snippets—you will find there…

1. BookUpdateTOCs (script)

Updates all Tables of Contents in the active Book. — You may find convenient to batch-update all TOCs present in a book, since InDesign doesn't seem to provide such a feature. This script inspects every chapter and runs the Update-Table-Of-Contents command if available. Then it displays a basic report at the end of the process.

TECH NOTE. — Chapters that aren't presently visible are temporarily opened, saved, and closed.

→ BookUpdateTOCs.jsx

2. DocPreventOpening (script)

Prohibits the opening of certain InDesign documents based on their filename. — This script prevents the opening of documents having a certain filename pattern. Change the RE_EXCLUDE constant in the code to make it fit your needs. The implementation relies on the event beforeOpen available in CS5/CS6/CC.

• To install the event listener just execute the script manually (once).

• To uninstall the listener, close your InDesign session. Of course if you have installed the code as a “startup script”, remove it from its folder!

DISCLAIMER. - Do not install this script as a startup script unless you really know what you are doing. Users will be unable to open documents having a certain file name pattern and won't be notified. In case you deploy this solution, make sure your clients are informed. Always provide instructions for uninstalling!

→ DocPreventOpening.jsx

3. DocShowClosestByName (script)

Makes active the closest document (with respect to name). — Based on the discussion “Javascript to find a similar filename among all open documents”, this script automatically selects the document having the most similar filename based on the Levenshtein distance.

TECH NOTE. — A custom RegExp can be supplied to the showClosestDocByName function in order to filter out specific name parts that must be ignored anyway (typically, shared suffixes among your set of documents.)

→ DocShowClosestByName.jsx

4. LinkAutoUpdate (script)

Updates links dynamically. — This script automatically updates ‘out-of-date’ links in InDesign. It is an event listener. You can either run it manually during your session, or load it as a startup script.

TECH NOTE. — An alternate code exists based on a script from あるふぁ（仮） which listens to the event afterAttributeChanged and delegates the task to BridgeTalk. The present implementation relies on the event afterLinksChanged available in CS5/CS6/CC.

→ LinkAutoUpdate.jsx

5. ReframeAllPages (script)

Reframes all pages with respect to item bounds. — Considering the active document, this script scans the page items of each page, determines the overall bounding box and reframe the page so it exactly fits the area. Page margins are reset to zero too.

TECH NOTE. — The script is undo-able and displays a short report.

→ ReframeAllPages.jsx

6. SelApplyStyleNone (script)

Resets the selection to the [None] style. — This script forcibly applies the [None] character style to the selected text or insertion point (if any), making sure that all specific character attributes are removed. The code has the same effect than clicking [None] in the Character Style panel (which unfortunately cannot be easily associated to a KB shortcut despite countless InDesign user requests.) So, you can attach a KB shortcut to this script and have a manual control of the “Apply None” action.

TECH NOTE. — All InDesign versions should be supported from CS4 to CC. Also, the script is undo-able (Cmd Z.)

→ SelApplyStyleNone.jsx

7. SelPlacePDFPage (script)

Simple interface for changing placed PDF page. — Need to constantly change the page of a placed PDF in the active document? Just select the graphic container and run this script.

ORIGINAL DISCUSSION: adobe.ly/3HoxrZ2

→ SelPlacePDFPage.jsx

8. DocBackupSave (snippet)

Backups a document before saving. — This function creates a backup of the target document before it saves it, so the consecutive versions are memorized, timestamped, and remain safe in a subfolder. The first time you call the function on a fresh, not-saved document, it simply invokes the native save method. Then, any subsequent call copies the existing document file in a backup folder before saving the new version. Each backup file is named as follows,

    <YYYY>-<MM>-<DD>_<hhmmss>_<DocumentFileName>

where the timestamp <YYYY>-<MM>-<DD>_<hhmmss> reflects the modified date/time of the document version.

Using backupSave(myDoc) rather than myDoc.save() may protect you against doomsday scenarios where a huge, in-progress document gets suddenly corrupted and cannot be recovered from the regular autorecovery feature. (Besides that, having consistent backups is still useful for ‘historizing’ your projects...)

TIP. — Assign your backupSave(); script a KB shortcut, e.g. Cmd+Alt+S, going into Edit > Keyboard Shortcuts…

→ DocBackupSave.jsx

9. DocGrepTextFindAll (snippet)

Gets all Grep/Text found items in a temp file. — This function lists all text items found by the active GREP query (or TEXT query if no GREP available.) Results are saved in a UTF8-encoded file (typically findGrep.txt) then shown to the user. The function itself returns true if all went fine.

TIP. — Assign your showFindAll(); script a KB shortcut, e.g Cmd+Alt+F, going into Edit > Keyboard Shortcuts...

→ DocGrepTextFindAll.jsx

10. FontGlyphCount (snippet)

Fast Glyph Counter for InDesign Font. — This snippet adds a glyphCount method to Font instances. You can use it in scripts that need to know how many glyphs are available in a font, in particular those which handle GID.

→ FontGlyphCount.jsx

11. GroupAddItems (snippet)

Adds one or several PageItems to a Group. — This snippet provides a addItems method to any singular Group instance. Such a feature is not available in InDesign's scripting API and it is hard to implement in a way that does not temporarily destroy the target group. The present solution relies on a brilliant idea proposed by Uwe Laubender — originally discussed in the InDesign Scripting Forum.

TECH NOTE. — The trick is to create a temporary MultiStateObject (MSO) which can then handle the target group into a State. New items are added to that state. When the state is finally released, the original group is restored with its new components. Issues may still arise in edge cases. The present code should deal with the target group G being part of an AnchoredObject (AO), or inside a ‘nested item’ (i.e pasted into.) However, no solution has been found in the particular case of G being directly nested in a SplineItem.

→ GroupAddItems.jsx

12. SelFirstImage (snippet)

Gets the top-left-most graphic. — Given a target page (and optionally a target layer) this snippet identifies and returns the “top-left-most” SplineItem containing a Graphic object. By ‘top-left-most’ we mean the object whose (top+left) coordinate is minimal. On average, this determines what the user perceives as the first geometric container of the page.

→ SelFirstImage.jsx

13. SelFlattenTransform (snippet)

Flattens the transformations of the selection. — This snippet operates on the selection. It clears the transformation attributes of every SplineItem while keeping path points in place. At the end of the process the objects look the same but they no longer undergo any scaling/rotation/shear component.

TECH NOTE. — The present implementation does not scan inner items from groups, MSOs, etc.

→ SelFlattenTransform.jsx

14. TableCellBox (snippet)

Creates a box enclosing a cell (or cell range). — Takes a table cell (single or plural specifier) and creates a Rectangle object that encloses the area, with respect to cell stroke(s) and existing transformations. This snippet is a 'proof of concept' following this technical discussion. The code illustrates and extends an idea from Uwe Laubender.

TECH NOTE. — The implementation deals with various InDesign issues, in particular the obj.duplicate() bug that affects GraphicCell's inner object. Also, the code supports the case of MSO or Button entities in the graphic cell. It can generate multiple ‘boxes’ if the incoming cell range runs across different spreads (due to threaded frames.)

→ TableCellBox.jsx

15. TextSortParagraphs (snippet)

Fast sort of InDesign paragraphs. — This snippet re-orders a range of paragraphs according to a sort function. By default Array.prototype.sort is applied to the contents, but the client code can supply a custom function as 2nd argument.

TECH NOTE. — The present implementation provides a mechanism that actually reorders the paragraphs once sorted and preserves individual character attributes. This is done by moving text ranges at the DOM level (no extra text container is created during the process.) The algorithm has been optimized to reduce the necessay moves to the strict minimum, so this function should run fast on average.

→ TextSortParagraphs.jsx

Go further! Discover IdExtenso, our opensource ExtendScript framework for InDesign.

Jean loup Fusz, un des piliers fondateurs de Swash Formation, m'a tendu un micro lors du lancement d'IndexMatic³.

Ceux qui ont déjà croisé Jean loup dans le cadre de l'InDesign User Group parisien ou sur les plateaux d'Adobe France connaissent son art de la médiation et le soin qu'il met à éclairer les angles morts en matière de design graphique et typographique. C'est donc un collègue scrupuleux et passionné qui m'a passé à la question dans cette interview parue la semaine dernière sur le blog de Swash.

Occasion inespérée (pour moi !) de donner quelques pistes sur ce drôle de métier qu'est l'automatisation InDesign. Et, pour vous, occasion de découvrir un Opac (Organisme Prestataire d’Actions de développement des Compétences) dynamique et sans ornières. Merci à eux pour ce sympathique coup de projecteur !

→ https://www.swash-formation.fr/ressources/indexmatic-outil-de-generation-dindex-dans-indesign-presente-par-son-auteur-marc-autret/

• Voir aussi : « Échantillonnez vos glyphes avec DeliverGlyphs » (script de JL Fusz)

Imagine you can extract, quantify, analyze and index every bit of text from your InDesign documents, in any language, based on your own criteria: a predefined word list, a set of fine-tuned regular expressions, such or such character styles or containers. This tool has just been born and is called IndexMatic³.

“Wait a minute! We already have a pretty suitable script for that purpose.” Yes indeed, IndexMatic² has been known for a decade by thousands of users around the world, and it still provides satisfactory results when it comes to making an independent index from an InDesign book. Well, it is exactly for this reason that IndexMatic³ succeeds and supplants it. Years of user feedbacks and feature requests… Read this little anthology:

— Is there no way to include/exclude paragraph STYLES selectively?

— Pleaaaase! Provide a solution for having page HYPERLINKS in the index!

— I need more ALPHABETS! Could it be possible to parse and index documents in Cyrillic, Hebrew, Arabic?

— Too bad I can't do a THREE or FOUR LEVEL index. Why stop at two?

— Can your program reveal matches in CONTEXT, as in the figure below?

— How can I target specific chapters in my book? And/or a CUSTOM SELECTION of opened documents?

— Could you please allow me to PREVIEW the results of my regular expressions? So frustrating that IndexMatic² ends up finding no results because of syntax errors!

— How could I filter out NOISE WORDS like ‘the’, ‘that’, ‘and‘, ‘which’…? (And the same in other languages!)

— We need much more contol on final SEPARATORS, cross-references and formatting! Also, our guidelines require us to format PAGE RANGES according to the Chicago Manual of Style rules.

— Is it possible to get ALPHABETIC HEADINGS A, B, C… automatically generated. I'm exhausted from manually adding those lines and reworking the layout.

— What about NOTE NUMBERS? I'd like to see them in the index.

And so on. In twelve years I counted a hundred requests of this kind, all extremely relevant, which could not be implemented in IndexMatic² as easily as one might think.

IndexMatic³: Reworked From Scratch

Consider iX³ as the premium flavor of IndexMatic, the one that addresses the above questions (and many more). It has been carefully redesigned with real-life user requests in mind. Its new “search engine” is faster, Unicode-aware, much more stable, and delivers instant results that you can view upfront, in the main dialog!

The script of course supports InDesign CC 2023… and still works fine in previous versions (CS6/CS5/CS4):

Above all, IndexMatic³ adds around fifty features to IndexMatic², some essential, others more advanced, which you will discover step by step by reading the user manual (109 pages).

So, What's The Deal?

• First, install and test the TRY version. If you have used IndexMatic² before, the difference should be obvious to you. (Note that iX³ and iX² are totally independent. Both can be installed in InDesign without conflict.)

• How is the TRY version limited? All the features are available but you cannot produce more than 50 index entries. It is however very sufficient to evaluate the program, and to determine whether or not your projects require a more powerful tool than those you already have.

• What about the previous version? Because IndexMatic³ is a major upgrade (also referred to as the “expert” version), we decided to maintain IndexMatic² (the legacy version) as a separate product, still available but no longer updated. Hence users and customers can still access a more affordable solution. IndexMatic² is known to run decently in InDesign 2023—although it hasn't been updated for several years.

• Why such a price difference between iX² and iX³? Just to give you a simple, quantitative comparison, the current IndexMatic² release has 5,600 lines of code, while IndexMatic³ (build 3.2301) has 40,000 lines of code (2,5MB). You will understand very quickly, by testing the two solutions, that they are not on the same scale.

• What Special Upgrade Price? The regular price for one IndexMatic³ lifetime license is, officially, €129. A 40% discount applies to IndexMatic² users whenever they decide to purchase the expert version. So they can always get access to iX³ for €79 (saving €50). Also, take note that during a short promo period, the 40% discount will apply to newcomers as well. (We decided to be generous with them too, shouldn't we?) But after that short period, only IndexMatic² users will have access to the PROMO code. (More detailed instructions will be sent to them.)

Acknowledgments

The development of IndexMatic³ would not have been possible without the invaluable help of some of my colleagues whom I would like to especially thank here:

— Peter Kahrel, one of the most knowledgeable people I know on both indexing issues and InDesign scripting!

— Roland Dreger, a German-speaking designer and developer who helped me a lot on translating the UI in German, and brought me a bunch of technical suggestions.

— Laurent Tournier, a friend and GREP-expert (well known to indiscripts' French visitors I guess) who is a seasoned IndexMatic user, always extremely relevant in his criticisms and ideas.

— Janus Bahs Jacquet, a Danish correspondent and IndexMatic user who suggested some very subtle improvements to the search system and other layers of the program.

— Ariel Walden, talented and renowned colleague at Id-Extras, who gave me helpful insights into Hebrew and right-to-left writing systems, and how they're handled in InDesign.

— Jean-Claude Tremblay, another famous InDesign guru and trainer, who helped me clarify didactic aspects in the iX²-to-iX³ transition.

The funniest thing I've read about the ExtendScript-to-UXP migration is in the (AI-generated?) documentation from Adobe: “ExtendScript uses an antiquated version of JavaScript (ES3), from the era when JavaScript was coded on punched cards.” LOL! Adobe is trying to make us feel like our JSX scripts are ancient artifacts, but let's see if IDJS will actually bring about a technological revolution in InDesign…

Unfortunately, there's not much information out there on this subject yet. The developers at Adobe.com have attempted to provide a cursory overview after InDesign 2023 (18.x) was released last October, but it's like trying to find a needle in a haystack of irrelevant and repetitive data.

I'm hoping that more thorough guides will be created soon—maybe on GitHub, github.com/AdobeDocs/uxp-indesign (when the many “lorem ipsum” will mutate into statements!)—but for now, it seems like script developers will have to rely on trial and error to document their own experiences. Thankfully, some of my colleagues are already on the case and are leading the charge for the “Unified Extensibility Platform” (UXP) revolution and the IDJS scripting file format.

UXP “Things You Need To Know”

First and foremost, UXP is the "modern way to create scripts and plugins for Creative Cloud products", it's like a magic wand that turns modern JavaScript (ECMAScript 6) and HTML markup into controls in native application windows. The most valuable resource I have seen on this subject is the YouTube's playlist UXP: Things you need to know created by the wizard Davide Barranca almost two years ago!

→ UXP: Things you need to know (Videos)
→ See also Davide's great opus Adobe UXP plugins development with React JS

Learning from UXP Announcements

The numerous UXP and UXP Scripting announcements posted last year on Medium's Adobe Tech Blog channel are still worth reading today to get a sense of the hype. Read especially those written by Padma Krishnamoorthy.

→ Big Updates Coming to UXP (22-Mar-2022)
→ Announcing UXP Scripting in Photoshop (9-Aug-2022)
→ See also, from V. Nachiyar, InDesign v. 18 Ships w/ Scripting Powered by UXP
→ and, from P. Barman, How Openicon Uses a Single UXP Codebase for Multiple Creative Cloud Apps

InDesign Scripting Gurus to the Rescue

Now, regarding more specifically UXP Scripting for InDesign—that is, the IDJS “specification” intended to ultimately replace JSX—a nice overview was posted last November by Gregor Fellenz, in German (translate.google is your friend if you don't speak German!) Last December, Martin Kraetke posted in turn an excellent article that sheds additional light on the syntactic jump from ExtendScript to ECMAScript 6. (UXP scripts are based on the V8 engine from Google Chrome, associated to a specific API wrapper for handling InDesign components.)

→ Quickstart UXP Scripting (DE) by G. Fellenz
→ Was bringt InDesigns neue UXP Scripting API? (DE) by M. Kraetke

Roland Dreger's GitHub Repositories

Finally, the scrupulous Roland Dreger—one of the most valuable script developers in the InDesign universe—jumped into the pot and opened the InDesign UXP Scripting repository, a set of “collected resources, articles and tutorials around UXP Scripting in Adobe InDesign”. On the other hand, he started experimenting with IDJS in a second repository: InDesign UXP Scripting Snippets. Although still in their infancy, these resources will allow you to familiarize yourself with the new concepts and get started writing scripts in the IDJS dialect.

→ InDesign UXP Scripting (Resources)
→ InDesign UXP Scripting Snippets

Geometry in InDesign can get deadly complex. Take a document, create a frame, insert a table, change a particular cell into a “graphic cell,” convert its inner object into an ellipse, play with strokes, rotate and scale the object, transform the parent frame in the fanciest way. Then ask yourself the question: what are the exact coordinates, shape or area of the final table cell?…

And still! I didn't tell you the whole story. Things like below may happen in a parallel universe (click the image to get a full insight into the nightmare) :

Even if no transformed spread incident occurs in the InDesign viewport, the problem of determining the basic, visually obvious coordinates of a Cell object remains highly technical. Just recently, Gerald Singelmann and Uwe Laubender discussed this thorny issue in the valuable HilfDirSelbst forum (in German.) My colleagues explore various approaches and tricks for recovering those hidden (x,y) data which the InDesign scripting DOM refuses to show us.

Note. — I also released my own solution in the IdGoodies repository, but the present post is not about the subtleties of that script.

One key fact is worth repeating here—as I feel it goes dramatically unnoticed (or misunderstood?) by InDesign scripters:

       One can always access the bounding box of a page item
       IN THE PERSPECTIVE OF ITS PARENT SPACE.

Sorry for the capital letters, that's really the crucial part. The “Parent Space Bounding Box”, also referred to as the “in-parent box”, is something that InDesign users cannot see in the GUI. But we scripters can grab it then study its coordinates, its transform state, and so on. Chapter 3 of the Coordinate Spaces and Transformations eBook explores the subject in depth.

Now, what does this visually mean? How does this help solve the “cell box” problem?

Well, look closely at the below image. The green Oval is the item inside the graphic cell (i.e., myCell.pageItems[0].) This object is badly distorted by internal transformations, as reflected in the GUI by its Inner Space bounding box. And that's all the scripting system will deliver us, geometrically speaking, since the cell container has no true geometric existence (no path, no bounds, no transformation matrix.)

Our goal is however to see the cell container as if it was itself a graphic object (which it is not!) We want to know its position, its dimensions, its transform state… Anyhoo, we want to get our hands on the red dotted rectangle representing the edges of the cell.

Now here is the little miracle. The cell object is drawn with respect to the TextFrame where the table flows. And this text frame happens to materialize the Parent Space of the green object (the one inside the cell.) Therefore, our cell container exactly matches the Parent Space Bounding Box (the “in-parent box”) of the Oval. I should say, more precisely, the “in-parent's visible bounding box”, the one that takes into account strokes and effects like the thick green border around the geometric path:

That's it! You just learned the magic parent box trick!

Disappointed? Ok, suppose you need to get the coordinates of point A marked on the figure. Its location, entirely determined from the inner object, can now be resolved as follows:

const MY_LOC = [
    AnchorPoint.TOP_LEFT_ANCHOR,
    BoundingBoxLimits.OUTER_STROKE_BOUNDS,
    CoordinateSpaces.PARENT_COORDINATES  // <<< HERE'S THE TRICK
    ];
 
myInnerObject.resolve( MY_LOC, <anySpace> )[0];
// where <anySpace> is any destination space
 

These really are the coordinates of point A, not those of the top-left corner of the intrinsic bounding box, nor those of the in-pasteboard bounding box (which by the way could be determined using the very same method.)

This way of defining and accessing locations in a nontrivial bounding boxes is what makes InDesign's coordinate system a powerful toolbox for solving hard issues like the “cell box” problem I have just sketched.

Admittedly, this is not an appetizing subject. Although I have studied it for years, I still need to reread my own conclusions and recipes—endlessly!—to bring them back to my head. Nobody is comfortable with these damn matrices and coordinate spaces, and neither am I. Not to mention the bugs and quirks that InDesign injects here and there to belie the rules.

But I don't know of any other way to resolve coordinates regardless of user/UI settings. In many circumstances you just can't trust the geometricBounds property, or if you can, it will not reveal the rotation/scale/shear components that a particular component undergoes, nor will it tell you how to grasp implicite coordinates resulting from transformations.

Consider the task of creating a yellow rectangle that perfectly covers the selected cell while inheriting its particular transform state relative to the pasteboard. For my part, I would be absolutely unable to write such a script without resorting to special coordinate spaces and transformations.

On the other side, InDesign scripts that entirely relie on that dark energy are harder to design, implement, debug and understand. This is a huge downside. But once you've found the key to open one lock, it seems to open all the others!

After a few days of rewriting and fixing bugs, when I ran TableCellBox.jsx on a severely disarticulated document, I was almost surprised that the subsystem didn't explode while calculating the transformation matrices!

• See also:
— Spaces and Transformations in InDesign (the definitive guide);
— HilfDirSelbst: “Koordinaten einer Tabellenzelle” (DE).

While working on his Measurements scripts, my colleague Mikhail Ivanyushin reported me weird biases related to units conversion. In particular, he observed a discrepancy between InDesign's display and direct results from ExtendScript when addressing inches-to-ciceros translation…

The Issue

Mikhail considered the case of setting a frame width to (exactly) 12.75in:

Now, right-clicking the horizontal ruler and changing the measurement unit to “Ciceros”,

you get the value 71c9.441 in typographic notation (which means 71+9.441/12 in decimal notation.)

So, according to InDesign, 12.75in ≈ 71c9.441. The symbol ≈ accounts for the approximation.

Note. — InDesign's display precision is 1/10,000 up to 4 decimal points, and all measurements are internally coerced into PostScript points. See “Precision of HurryCover Measurements” for a more detailed discussion on this topic.

However, Mikhail's original ExtendScript code produced a slightly different result (71c9.5866), which deviates from the displayed value by +0c0.1456, that is, +0.0121 ci in decimal notation. This really is a tiny difference—something like 55 µm—but Mikhail wanted to explain the gap and improve his script. Most InDesign users aren't familiar with rounding errors, so they may visually consider 71c9.5866 as a wrong value compared to 71c9.441. In fact, they differ only by the size of three neurons!

In the previous version of the SizeInUnitsEng.jsx script, the general strategy was to apply an Adobe-to-French-Points conversion when dealing with ciceros. For that purpose, the factor 3528/3759, or similarly 254/271 was used, based on the fact that “French inch has size 27.1 mm [resp. French point is 0.3759 mm]; while Adobe inch is 25.4 mm long [resp. Abobe point is 0.3528 mm].”

Also, it was assumed that UnitValue's metric accurately reflects those ratios… which didn't appear to be the case at all!

So, What Is a Cicero?

• According to wikipedia FR, one cicero is 12 Didot points, that is:

    1 ci ≈ 4.512 mm.

(The ≈ symbol is very important here, as the definition of the “point” itself varied across History, as well as the “French inch”.)

• According to wikipedia EN, a better estimation of the cicero (“1/6 of the historical French inch”) would be:

    1 ci ≈ 4.51165812456 mm.

• According to InDesign's display, 1000 ciceros equals 4511.278 mm, so:

    1 ci ≈ 4.511278 mm.

• Finally, according to the UnitValue class implemented in InDesign/ExtendScript,

    1 ci ≈ 4.51104 mm,

so we clearly get an uncertainty from the 4th decimal place when dealing with millimeters.

Regarding inches, it's worth mentioning that InDesign display is altered by rounding errors as well, so it may appear that it doesn't even comply with its own rules in some cases. Just consider the 12.75in example above:

    12.75 in ≈ 71c9.441  (ID display.)

Now, in Adobe metrics, we have two known facts:

    (a) 1 in = 72pt (Adobe measurements.)

    (b) 1 ci = 12.7872pt (straight from UnitValue.)

From (a), 12.75in = 918pt;
from (b), 10000ci = 127872pt,
which leads to the following conversion table:

It comes 12.75 inches = (71 + 117/148) ciceros. The decimal part expressed in 12th gives 351/37 (≈ 9.486486486), so the best approximation we can write is:

    12.75 in ≈ 71c9.4865 (our result — vs. 71c9.441 from ID.)

So, according to our own calculations, InDesign displays is “wrong” by about +0c0.04. Still a microscopic error!

Choose your Factor!

As a matter of fact, we don't know with a sufficient accuracy the internal factor that UnitValue uses when it converts from ciceros. However, since it is considered that 1 cicero should equal “12 French points”, the best offer we can provide from the UnitValue perspective is:

    const K = 12/(UnitValue("1ci").as("pt")); // 0.93843843843844

The value of K falls between 254/271 (≈0.937269373) and 3528/3759 (≈0.938547486) mentioned earlier. There are good reasons to suppose it will bring more consistent results.

Here is a sample script that you can use for testing this approach:

 
// Proposed factor when using intermediate
// conversion to points (French vs. Adobe.)
// ---
const K = 12/(UnitValue("1ci").as("pt"));
 
// Input parameters
// ---
var inputString = "12.75";
var inputUnit = "in";
 
// Rounding param.
// ---
var round = 4;
 
// Conversion.
// ---
var sizeAsAbobePt = UnitValue(inputString, inputUnit).as("pt");
var sizeAsFrenchPt = sizeAsAbobePt*K;
 
floatResult = parseFloat(sizeAsFrenchPt/12);
intResult   = parseInt(sizeAsFrenchPt/12);
 
// Refine the frac. part (typographic notation.)
// ---
diff = floatResult - intResult;
frac12 = (diff*12).toFixed(round);
 
// Output.
// ---
alert( intResult + "c" + frac12 );  // 71c9.4865
 

This leads to a very good approximation (71c9.4865) although InDesign still displays different digits (71c9.441) that anyway diverge from the theoretical result.

Note. — Don't be surprised if you observe differences at the 2nd or 3rd position after the decimal point in a fraction that itself represents how many 12th of the cicero unit we should take! The disagreement between 71c9.49 and 71c9.44 is, in fact, anecdotal. Since K is uncertain from the third decimal place, 10*K is uncertain from the 2nd decimal place, 100*K is uncertain from the 1st decimal place, and so on. In our particular example, sizeAsAbobePt is about 918 (in pt), which may even lead to a greater error. If we have used K=254/271, the final result would have been 71c8.4133! And I do not mention the additional rounding errors introduced by floating-point arithmetic (multiplications and especially divisions.)

A More Direct Solution

But, to me, there was still a mystery in Mikhail's algorithm: why on earth would the Adobe-to-French points translation have to be made?

Indeed, is there anything wrong in just invoking UnitValue(input).as("ci")?

Here is the simple code I've tested while investigating the issue:

var v = UnitValue("12.75in").as("ci");
// => 71.7905405405405 ; exact: 71 + 117/148.
 
// Convert decimal notation into typographic notation `#c#.#`
// ---
var n = parseInt(v,10); // Integer part: 71
 
var d12 = 12*(v-n);     // Dec. part × 12
// => 9.4864864864864 (exact: 351/37.)
 
12 <= d12 && (++n, d12-=12); // Who knows?
var result = n + 'c' + d12;
 
alert( result );
// => 71c9.4864864864864
 

Without a shadow of a doubt, this is the closest value to the theoretical result (71c9.4865) ever obtained. The reason is, almost all intermediate multiplications and divisions have been avoided, the core computation being just performed by UnitValue's internal processor.

Conclusion: if you use its native routines properly, ExtendScript can be more accurate and reliable than InDesign itself ;-)

Related links:

• Measurements and Explanations: Educational material about ratios of printing sizes, by Mikhail Ivanyushin;
• Associated Scriptopedia entry;
• IdExtenso::Units, a consistent facade for handling metrical units.

Thanks to the feedback of an expert user, we discovered a critical flaw in the OTF export module of IndyFont. In short, the script was unable to generate a valid OpenType font having more than 255 glyphs in the Private Use Area. This serious issue is now fixed in iF 1.144. Go to your private link to update!

Fast, free, and feliz, SmartSort is an InDesign script that alphabetizes word lists (paragraphs or cells) with respect to the language used in your text. It's as easy as Right Click ▸ SmartSort… ▸ Sort! Version 1.17 essentially provides stability fixes. Download/update right now, and enjoy ;-)

How do I update the script? Simple: extract the new SmartSort.jsx file from the ZIP package, quit InDesign, replace the old file in your Scripts panel folder, restart InDesign. Done.

Why should I update? SmartSort is built upon the IdExtenso framework, which is regularly improved. An major update of the Collator component has just been released and provides stability fixes. SmartSort 1.17 reflects these changes.

• See also: SmartSort user's guide (PDF).

In most cases, ExtendScript regular expressions cannot digest the (a|b)+ scheme. This bug is not new, but it's worth defining its symptoms and extent. This article presents a very simple problem, with no known solution to date…

Given an input string, suppose you want to capture every maximal substring formed of at least two letters and ending with a 'x'. (To make it simple, we shall admit that a letter is defined by its belonging to the \w class.) The solution is trivial, just run the regex /\w+x/g on the input string.

TEST #1 (ExtendScript/JavaScript)
 
input :: "Box x taxi x vaxx."
regex :: /\w+x/g
 
3 MATCHES FOUND -- See the ┊...┊ parts
 
✔ ┊Box┊ x taxi x vaxx.
✔ Box x ┊tax┊i x vaxx.
✔ Box x taxi x ┊vaxx┊.
 

Note. — We represent the consecutive matches nested in ┊...┊ based on a basic while(regex.exec(input)){...} loop that inspects RegExp.leftContext and RegExp.rightContext at each step. This presentation is more instructive than a simple display of the array of matches, because it tells us how the internal pointer of the regular expression progresses during execution.

A few things worth pointing out:
   • The isolated x are not captured because we target at least 2 letters.
   • ┊tax┊ is found in "taxi" since no \b assertion is specified.
   • ┊vaxx┊ is found rather than ┊vax┊x because \w+ is greedy, meaning that the + quantifier looks for a maximal match.

The most important fact, of course, is that the final character 'x' also belongs to the class \w. So, whenever \w+ eats too many 'x's, the regular expression is forced to backtracking. It must return what it has captured in excess from \w+ to make room for the x part. If the quantifier had been made non-greedy (/\w+?x/g) then the last match would be ┊vax┊x, which is no longer maximal.

So far, so good.

Now to the Bad News

Then, suppose your script should also consider some special syntax, say '%' followed by two digits, as representing a letter in the input string. And your goal is still to retrieve all maximal substrings formed of letters (including the %## meta-codes) and ending with 'x'. What would be the proper regex then? Easy:

   /(%\d\d|\w)+x/g

is the logical answer you probably have in mind, and it works perfectly fine… in JavaScript!

TEST #2a (JavaScript only!)
 
input :: "Box x A%22%34x V%99xx."
regex :: /(%\d\d|\w)+x/g
 
3 MATCHES FOUND
 
✔ ┊Box┊ x A%22%34x V%99xx.
✔ Box x ┊A%22%34x┊ V%99xx.
✔ Box x A%22%34x ┊V%99xx┊.
 

Unfortunately, ExtendScript has a backtracking bug since the dawn of time—which in my opinion will never be fixed—and is not able to properly manage “quantified alternatives,” that is, subpatterns of the form (A|B)+, (A|B)*, etc.

TEST #2b (ExtendScript bug!)
 
input :: "Box x A%22%34x V%99xx."
regex :: /(%\d\d|\w)+x/g
 
5 MATCHES FOUND
 
✖ Bo┊x┊ x A%22%34x V%99xx.
✖ Box ┊x┊ A%22%34x V%99xx.
✖ Box x A%22%34┊x┊ V%99xx.
✖ Box x A%22%34x V%99┊x┊x.
✖ Box x A%22%34x V%99x┊x┊.
 

Since our regex /(%\d\d|\w)+x/g should execute as well with input strings without %## forms, the bug is visible already in our original example "Box x taxi x vaxx."

TEST #3 (ExtendScript bug!)
 
input :: "Box x taxi x vaxx."
regex :: /(%\d\d|\w)+x/g
 
6 MATCHES FOUND
 
✖ Bo┊x┊ x taxi x vaxx.
✖ Box ┊x┊ taxi x vaxx.
✖ Box x ta┊x┊i x vaxx.
✖ Box x taxi ┊x┊ vaxx.
✖ Box x taxi x va┊x┊x.
✖ Box x taxi x vax┊x┊.
 

And in fact you could put anything else in the alternation structure, even a single character (% instead of %\d\d), this won't clear the symptoms. The bug is not related to the complexity of the regular expression, only to its (A|B)+ form. In many circumstances, ExtendScript's engine will just fall in an infinite loop (which you can eventually prevent by adding to the input string a suffix that the alternation can never match.)

Note, in the above results, that a ┊x┊ match is wrongly reported at any position of 'x' in the input string, including isolated 'x's that couldn't even be regarded as the tail of a regular match. So we cannot rely either on the value of regex.lastIndex as a hint for completing the matches.

Just remember this sad law:

   Any Greedy Quantified Alternative Is
   Deeply And Irreparably Flawed
   (in ExtendScript.)

Ironically, I found a partial workaround that only works when, well, we don't actually need it! Indeed, if your pattern looks like /(%|\w)+x/g in the sense that it consumes a single character on each side of the alternation, then it seems that the “lookahead trick” /((?=%|\w).)+x/g escapes the bug:

TEST #4 (Lookahead trick for single char. alt.)
 
input :: "Box x taxi x vaxx."
regex :: /((?=%|\w).)+x/g
 
3 MATCHES FOUND
 
✔ ┊Box┊ x taxi x vaxx.
✔ Box x ┊tax┊i x vaxx.
✔ Box x taxi x ┊vaxx┊.
 

But as I said we don't need it at all, since %|\w could be just encoded as a class, [%\w], which entirely eliminates the alternation structure.

Sometimes you can be satisfied with a non-greedy quantifier. In this case the RegExp instance seems to work much better, but have in mind that it won't capture maximal matches:

TEST #5 (Non-greedy quantifier)
 
input :: "Box x taxi x vaxx."
regex :: (%|\w)+?x
 
3 MATCHES FOUND
 
✔ ┊Box┊ x taxi x vaxx.
✔ Box x ┊tax┊i x vaxx.
✔ Box x taxi x ┊vax┊x.
 

(Note that the last match is then ┊vax┊x, not ┊vaxx┊.)

Conclusion

The bug documented above is without a doubt one of the most dreadful in the ExtendScript regular expression engine. Barring a miracle, it will never be resolved since ExtendScript has been sentenced to death in the medium term. However, hundreds of existing scripts are likely to use RegExp objects, and sometimes very advanced patterns, which can collide at any time with the simple case of quantified alternations.

If you found a solution that I hadn't thought of, thank you in advance for sharing it!

Although most GREP patterns are supported in IndexMatic 2, lookbehind is not. This operator allows you to capture a match only if some particular pattern occurs BEFORE it. Under certain circumstances you might need to build an index based on such fine-tuned queries. Let's see how to get around the wall…

First and foremost, remember that IndexMatic is based on ExtendScript Regular Expressions, a dialect that supports positive and negative LOOKAHEAD assertions—using the schemes X(?=Y) and X(?!Y), respectively—but cannot digest LOOKBEHIND schemes (?<=Y)X and (?<!Y)X to which GREP power users are accustomed.

Yet, the prefix elements of some expression may determine whether it is relevant or not for your index. Usually, capturing the full expression is enough to solve the problem. For example, the query /Prime Minister/ de facto excludes the isolated expression “Minister”. Thus, the LOOKBEHIND condition only makes sense when you need to capture an expression as long as it follows a certain pattern but without capturing that pattern.

Positive Lookbehind

Now suppose you are working on a product catalog such that every important name (the one you want to index) is always preceded by some 3-digit number and a pipe, like in 123|shelf. The prefix pattern \d\d\d\| is the condition that makes the word shelf relevant, but you don't want to see that code in your final index.

In GREP syntax it would suffice to use something like (?<=\d\d\d\|)\w+ to grab the name that follows any possible prefix code. But this won't work in ExtendScript.

However, IndexMatic can practically solve the problem. Just capture the whole pattern and output the relevant part:

   /(\d\d\d\|)(\w+)/ => $2

The general form of a “fake lookbehind query” is (BEFORE)(MATCH) => $2, where BEFORE stands for the prefix pattern that is required although hidden, MATCH being the visible part. Thanks to the capturing parentheses, the rule => $2 disregards the content of the first parenthesis (i.e, $1) and outputs only the MATCH component (i.e, $2.)

Note. — There is a subtle downside to this: IndexMatic still reports the page number of the whole match. If by accident BEFORE belongs to page 2 and MATCH belongs to page 3, then the final index will claim that MATCH has been found on page 2, because the first character of the string that matches /(BEFORE)(MATCH)/ is indeed on that page.

Negative Lookbehind

Here we are asked to capture a term as long as it is not preceded by a certain pattern. This sounds like a completely different problem since no positive pattern governs the prefix part. Yet we can still extract the allowed term using the below trick:

    (BEFORE MATCH)|(MATCH) => $2

where BEFORE MATCH (1st capturing parenthesis) targets the form that we want to bypass, and MATCH alone (2nd parenthesis) represents a valid match. Thanks to the alternation, the variable $1 is set whenever BEFORE MATCH is found in the text, while $2 will only receive a MATCH in the opposite case. But since the query only outputs $2, any context that leads to fulfill $1 by satisfying the BEFORE MATCH pattern is finally ignored. So you get exactly the effect of a negative lookbehind.

For illustration, let's reverse the condition of our previous example. Our goal is now to index the expressions of the form \w+ unless they are prefixed \d\d\d\|. We then just have to run the IndexMatic query

   /(\d\d\d\|\w+)|(\w+)/ => $2

Note in passing that the scheme /(X)|(Y)/ => $2 has many other applications. Say you need to identify every occurrence of the word “token”, except those that are in quotes! The easiest way to do that is to capture both forms—making sure the greedy one is placed as the first alternative—then to output $2:

   /(["“'‘]token["”'’])|(token)/ => $2

Always the same principle: consume the undesired expression in the first block to prevent the second block from capturing it.

Freya Holmér premiered in August a grandiose tutorial video, The Beauty of Bézier Curves, that every developer and/or graphic designer should watch! Especially if you are interested in the internal coding of outlines and path points in InDesign…

It is no coincidence that The Beauty of Bézier Curves sits in the top 5 of the Summer of Math Exposition contest. Grant Sanderson from 3Blue1Brown —who is himself one of the most talented authors in the field of “animated math”— urged Freya Holmér to design and polish what we might call an educational masterpiece.

Cubic Bézier curves are at the heart of InDesign (and Illustrator) paths. They are involved in all the tools and scripts that deal with “spline items,” like Wordalizer, IndyFont, Claquos, DrawWave, or the astonishing MojiDisassembler (JP) script for Illustrator.

The underlying math might intimidate the novice programmer, but Freya makes the subject so visually intelligible, and without masking the most subtle aspects, that you will master the De Casteljau's algorithm (and many other things) in less than 30 minutes!

Note. — To perfect your knowledge of Bézier curves, don't forget the comprehensive (and unsinkable) Primer on Bézier Curves from Pomax ;-)

Links:
• The Beauty of Bézier Curves: youtube.com/watch?v=aVwxzDHniEw
• 3Blue1Brown: youtube.com/3blue1brown
• Primer on Bézier Curves: pomax.github.io/bezierinfo/

In this episode we seriously improve the relationship between user settings and user interface. As a result, we get a smart InDesign script that both remembers the choices the user made within the session and adapts to the context, that is, whether the script should target the selection or a larger scope…

Preamble

Streamlining user preferences and similar data throughout your code is undoubtedly the criterion that best distinguishes amateur from professional scripts. There are many questions and issues to address here: settings should be made easily available anywhere in your code, some require refreshment when the script starts up, others are to be dynamically changed when the user clicks OK, sometimes we expect an option to persist beyond the current session (say, for example, language preferences) while in other cases we have to attach a parameter to a particular document or object.

Settings must be declared, accessed, adjusted, saved, restored. Each key/value pair has its own live cycle, its dependencies, its purpose (not necessarily noticeable to the user.) The biggest difficulty is to decouple this special data stream from local tokens (function arguments, variables, etc).

How to keep settings administered in one place while your project keeps growing and queries more and more scattered data? IdExtenso's $$.Settings module has been designed to answer that question. Simply declare a set of keys in the onEngine handler of your project and your settings are now entirely managed by this specialized module:

This short code shows how keys are declared and, more importantly, how their respective lifespan, or ‘scope’, is specified. Here are the available scopes and the corresponding scenarios:

1. CONSTANTS. Pure read-only key-value associations, which the client code cannot even change. Useful for product name, version, user license data, and the many fixed strings or numbers that the script must keep safe. Note: CONSTANT keys can be declared using an underscore prefix, e.g. _VERSION means that the key VERSION is read-only.

2. LIVE KEYS. Volatile parameters (never saved nor restored) used to share data across different places. These are not “settings” in the usual sense; they work as on-the-fly parameters registered in $$.Settings space for convenience. Use case: the active document ID, or some current target specifier, must be shared across different parts of your script.

3. RESET KEYS. Keys that can freely evolve once activated (as the LIVE Keys), but expected to always wake up at a determined value. Here ‘always’ means, “each time the script starts up.” Note: This makes a difference in engine-persistent scripts, where LIVE keys wake up in an arbitrary state (depending of previous operations) while RESET keys are guaranteed to regain their default value.

4. ENGINE KEYS. These keys are aligned with the script engine. That is, they remember their latest value throughout the session in a persistent engine, but they reset to the default value if used in the main engine. Unlike LIVE keys, ENGINE keys have a default value so they can be forcibly reset from the client code. Unlike RESET keys, they do not automatically recover their default value if the engine is persistent. Note: ENGINE is the default scope: keys declared outside of an explicit branch behave this way.

5. SESSION KEYS. Whatever the engine in use, these keys persist throughout the whole InDesign session (unless forcibly reset, or not saved.) Note: SESSION keys are kept as JSON strings in the system environment, so they enjoy a fast backup/restore mechanism compared to DOM-based routines. Use cases: whenever you need to keep track of “what happened before” in the present InDesign session, e.g, script runcount, tasks already performed, etc.

6. OBJ KEYS. These special keys are intended to be saved in an InDesign DOM object, if supplied. They activate to a default value and behave as ENGINE keys if no DOM object is provided. Otherwise, they get the value stored in that particular object. Use case: your script builds & manages data-driven documents and needs to keep some metadata attached to each of them. When the user re-opens such document, the OBJ-scoped settings reflect the specific data attached to it.

7. APP KEYS. These are the most persistent keys: InDesign will remember them even in later sessions (after quit/restart.) Note: Technically, an APP key can be thought as an OBJ key based on OBJ==InDesign. Use this scope for managing long-term user preferences. Note: your script may then offer a “Go Back to Defaults” option, which can be done using $$.Settings.reset(null).

8. HYBRID KEYS. An HYBRID key imitates the global vs. local paradigm used in InDesign preferences. If a DOM object is supplied (typically, a Document) then the value is taken from it, otherwise the application key is considered. For example, if your script provides Swatch- or Style-related settings, you may want to handle them in a global/local fashion, as InDesign does.

A unique ID must be passed in (first argument) to $$.Settings.declare(). The MD5 hash of the project name is a possible UID, as in our example, but you can use any string that meets the uniqueness condition. Settings declaration must be done once, so we use the onEngine handler (not onLoad) of our module. Another option is to call $$.Settings.declare() from a if( $$.isBooting() ){...} block. A subsequent stage, settings activation, should be performed whenever your script runs or re-runs. To give concrete meaning to these principles, let's move on to practical work!

Our Base example (Version 5)

The natural development of our project led us to add a few persistent settings that we shall make available, in the dialog window, alongside the original radius and stroke options:

• scope lets the user choose between “Selection” and “Spread”. In the latter case, the script targets all spline items available in the active spread rather than the selected object alone.

• autoRunSel is a convenient option that tells $$.PathNodes to skip the dialog if a valid selection is active. The script then automatically targets the selected object.

Note: Our SESSION settings could have been made application-persistent instead. A good practive is to develop your project in the SESSION lifespan until your code is stable and safe enough to declare APP settings. It's just a matter of replacing the 'SESSION' branch by 'APP' ;-)

Of course we have to implement the underlying tasks, in particular the processing of an entire spread. But this won't introduce any change in the hotProcess function, which was thought upstream to support any set of input arguments. Also, the script no longer needs to warn the user when no valid selection is active, since it then reacts by showing the UI in a mode that lets you change the preferences globally—I mean, even if no document is available in InDesign. The different scenarios are sketched below:

These improvements explain why the run method has been restructured a bit. But in return, a lot of unnecessary bricks were removed and the whole module now looks very consistent:

A few implementation notes:

• Line 13 introduces the new essential character of our plot: $$.Settings.

• Lines 19-49. Here is added the onEngine handler. As it only runs once per session, this is the ideal place for declaring settings.

• Lines 63-171. Distinct methods, checkSel and checkSpread, were needed to treat separately the two possible scopes (selection vs. spread.) Each of these functions answers the question: can the hot process work in my scope? In the affirmative, the target items and spread are cached in the internal keys ITMS and SPRD.

• Lines 235-263. Note how the dialog method has been flawlessly upgraded! The $$.Settings keys are now activated from the outside and passed by reference (ss argument), but the logic of the code is completely preserved. (Compare with version 4.)

• Lines 265-274. Added the “Scope” dropdown and the “Autorun on Selection” checkbox. Note how the list attribute is formatted in the <DROP> element —that's one of the goodies of the $$.Dom.Dialog module!

• Line 282. $$.Settings.activate() activates the keys in their respective mode and returns a special object, referred to as an accessor, in direct contact with all available key/value pairs. Consider it a regular JavaScript object for read/write operations. (Behind the scenes, $$.Settings keeps an eye on it though…)

• Line 313. $$.Settings.backup() must be invoked explicitly when your main routine returns. Indeed, there are many circumstances where changes aren't supposed to be saved, like when the user cancels the dialog!

Don't you feel that our PathNodes script is now very close to its stable version?

(To be continued…)

STEP 1 | STEP 2 | STEP 3 | STEP 4

Coordinate Spaces & Transformations is a free eBook covering all atomic subjects that a InDesign scripter or developer should grab before using transformation matrices and the related methods. The last update has minor corrections and notes…

(Update 14-Oct-2021). — A recent discussion with Manan Joshi led me to rephrase a few statements regarding the inner coordinate space of a PageItem. Manan observed that “for text frames the inner coordinate space seems to have its origin at the center of the frame. When resolving with respect to pasteboard or spread, the matrix obtained is of the form [1, 0, 0, 1, tx, ty].”

As a matter of fact, a TextFrame has its affine map and geometry initialized in a way that makes the inner space origin coincide with the center of its bounding box. That's clearly an exception. It wasn't mentioned in the PDF until now (we only documented the case in the ISFR series—see 1st note.) The exception is even more obvious in IDML format. Inspecting the ItemTransform attribute of a TextFrame, we see that translation arguments somehow preset the origin within the object bounding box. Then the PathGeometry structure defines the anchor points with respect to that location. By contrast, the ItemTransform of a SplineItem (e.g, a rectangle) is originally the identity matrix, meaning that the PathGeometry is fully relative to the spread origin.

The present version of the eBook doesn't deal in depth with such oddities because “case studies and special issues” are reserved for a future chapter ;-) Anyway it was important to mention the TextFrame exception from Chapter 2 onwards.

(30-Jun-2018). — It tooks me six years to document the fundamentals of InDesign “Coordinate Spaces and Transformations.” You may think I am sluggishly slow—which is a sensible diagnosis!—but the topic required a true immersion to be both experimented and covered. Chapter 5 (“The Transform Process”) is now available and makes this release consistent enough to form a kind of white paper.

1. KEY CONCEPTS
— 2D Coordinates; Affine Maps; Relative Locations, Inner Space.
— Transformations, Maps, Matrices; Matrix Patterns and Product.
— InDesign Transform Order (scaling×shear×rotation×translation).
— Transforming vs. Deforming; Hierarchical Mapping of DOM components.

2. INDESIGN COORDINATE SPACES
— Pasteboard, Spread, and Page spaces; Page Size and Location Issues.
— Inner Coordinate Space of a PageItem.
— Chasles' Relation; Moving vs. Displacing in Space…

3. BOUNDING BOXES
— Each Bounding Box Depends on a Coordinate Space.
— Each Bounding Box Defines a Coordinate System.
— Path Bounds vs. Visible Bounds.

4. RESOLVING LOCATIONS
— Definition; Location Specifier and Syntax.
— All about the resolve() method.
— Transform-Space into Bound-Space Algorithm.
— InDesign's Ruler System; Details about Page-based Rulers.

5. THE TRANSFORM PROCESS
— Understanding the “Transform Space.”
— Transformation Origin.
— MatrixContent flags and other parameters.
— Impact of Transform Preferences.

Version History

14-Oct-2021. — Version 3.2, Chapters 1—5, bookmarks, and corrections, CoordinateSpacesTransfos01-05.pdf (1.05 MB, 41 p.)

30-Jun-2018. — Version 3.1, Chapters 1—5 + bookmarks, CoordinateSpacesTransfos01-05.pdf (1.17 MB, 41 p.)

14-Jun-2016. — Version 3.0 (draft), Chapter 4 only, CoordinateSpacesTransfos04.pdf (433 KB, 12 p.)

18-Oct-2014. — Version 2.1b, added Chapter 3, CoordinateSpacesTransfos01-03.pdf (528 KB, 22 p.)

8-Oct-2014. — Version 2.1a, Chapters 1 and 2, CoordinateSpacesTransfos01-02.pdf (481 KB, 19 p.)

24-Mar-2014. — Version 2.0, “Key Concepts,” CoordinateSpacesTransfos01_KeyConcepts.pdf (377 KB, 10 p.)

21-Dec-2012. — Version 1.0, creation date (unpublished.)

• Download version 3.2 (PDF, 41 pages)

• Coordinate Spaces & Transformations Series

The previous episode dealt with modularity in IdExtenso, now is the time to take full advantage of it! Today we will see how to add a dialog interacting with user options. You will be amazed at how quickly this component fits into the script…

Preamble

IdExtenso provides various tools and modules for building advanced user interfaces. If your project needs sophisticated ScriptUI controls and event managers, you will probably turn to ScriptUI.builder and our custom factories.

However, simple dialogs perfectly fit the Dom.Dialog module, which offers a nice encapsulation of InDesign's DOM Dialog object and all associated widgets. $$.Dom.Dialog dramatically simplifies the declaration of a dialog: just pass in a XML description of all components (including additional attributes if needed) and you instantly get a consistent Dialog instance ready to run.

The box below recaps the XML elements that $$.Dom.Dialog can digest, both in abbreviated form (4 uppercase letters) and in full form:

// CONTAINERS
DROW or DialogRow
BPNL or BorderPanel
EGRP or EnablingGroup

// RADIOS
RGRP or RadiobuttonGroup
RBTN or RadioButtonControl

// MISC
STAT or StaticText
CBOX or CheckboxControl
DROP or Dropdown

// EDITBOX WIDGETS
TEBX or TextEditbox
AEBX or AngleEditbox
IEBX or IntegerEditbox
MEBX or MeasurementEditbox
PEBX or PercentEditbox
REBX or RealEditbox

// COMBOBOX COUNTERPARTS
ACBX or AngleCombobox
ICBX or IntegerCombobox
MCBX or MeasurementCombobox
PCBX or PercentCombobox
RCBX or RealCombobox

Abbreviated elements make it possible to give a very compact format to your XML data, as in our example:

<Dialog name="MyDialogTitle" canCancel="true">
    <DCOL>
        <MEBX key="radius" caption="Radius" min="0.25" max="20" />
        <MEBX key="stroke" caption="Stroke Weight" min="0" max="4" />
    </DCOL>
</Dialog>
 

Note the presence of a special attribute, key, that is automatically connected to the corresponding properties when you invoke the custom methods setValueKey and getValueKey associated to any Dialog. (This special behavior is obtained by extending Dialog.prototype when the module starts up.)

Now, take a look at the unique function we're going to add to our code:

Could we make it easier?

Our Base example (Version 4)

All we have to do is to #include the $$.Dom.Dialog module from the '/etc' branch of IdExtenso. Then we invoke $$.Dom.Dialog(myXMLDescriptor) to get a reference to the Dialog instance.

Here is the entire code of the new PathNodes script:

Really, there are very few changes from the previous version:

• Line 12 contains the #include directive for the extra module. Additional IdExtenso modules could be included at this location (after the entry point.)

• Line 14 updates the YYMMDD number, so IdExtenso knows we're working on a new version of $$.PathNodes.

• Lines 183-210. Here is implemented our new public method dialog. It creates a Dialog, presets the default options via µ.settings(), displays the dialog and updates the settings if the user has clicked OK.

• Line 213. A little trick here: the XML descriptor contains the placeholder "{µ}" which refers to the present module and retrieves its name (actually, the returned value of toString().) This avoids hard-coding the string "PathNodes".

• Line 228. That's the unique change in the run process, we have simply replaced the condition µ.canRun() by µ.canRun() && µ.dialog(), so the UI is shown before entering the hotProcess.

• Line 242-244. Another little trick! In TRACE mode, the regular command $$.PathNodes.run() is maintained so we can undo each step while debugging. Otherwise, it is more convenient to make the entire script undoable.

Here we go:

Note that the settings are not persistent for the time being. This will be the subject of the next chapter.

Enjoy!

(To be continued…)

STEP 1 | STEP 2 | STEP 3

Update (2-Oct-2021). — Version 1.28 of PageBorder fixes a UI problem in InDesign CC (the option for removing the border once created was hidden.) Tip: if you need to customize the color of the border (defaulted to Black), simply replace the name assigned to the strokeColor property, Line 26 of the script.

Need to have a page border on your job up until it goes to the printer? PageBorder quickly creates a temporary customizable black border around the active page, or every page, of your InDesign document. The script is compatible with ID CS3, CS4, and even CS5 which allows multiple page sizes per document.

A few years ago, Cari Jansen wrote the useful 1pt Stroke All Pages script for InDesign CS and CS2. Cari's code creates a rectangle on each page, set to exact page size, with fill None and stroke 1pt Black. The object is placed in a separate layer, so that it can easily be removed/disabled by the user. That's exactly what PageBorder does, except that it provides a user interface with some extra features and supports InDesign CS3-CS5.

The most important change is that we now need to support multiple page sizes per document —through the Page.bounds property. This involves resetting the rectangle size within the page loop, as shown in the below snippet:

var createBorder = function(/*Layer*/layer)
//------------------------------------------------
// this: Page [collective allowed]
{
    var pages = this.getElements(),
        alignMode = StrokeAlignment[alignStrings[align].
            toLowerCase()+'Alignment'],
        pg;
 
    var recProps = {
        fillColor: 'None',
        strokeColor: 'Black',
        strokeTint: 100,
        strokeWeight: ptBorder,
        strokeAlignment: alignMode,
        strokeType: (jDots && jDotsStyleName) || solidStyleName,
        };
 
    while( pg=pages.pop() )
        {
        recProps.geometricBounds = pg.bounds;
        pg.rectangles.add(layer,undefined,undefined,recProps);
        }
};
 

So InDesign CS5 users can apply PageBorder on this kind of spread:

PageBorder Dialog and Settings

PageBorder displays a simple dialog to let you manage a few settings. (Note that these settings are session-persistent, so the script always starts from the last configuration.)

• The Weight field allows you to set the stroke weight of the page border, from 0.1 to 5 pts. You can explicitly enter any unit, e.g. "0.3 mm". The default unit is point (pt) for CS3/CS4 users. In InDesign CS5, the default unit is the one defined in Edit > Preferences >Units & Increments > Other Units > Stroke.

• The Alignment listbox lets you choose how to align stroke over page boundaries: Inside, Outside, or Center.

• Check All Pages to apply PageBorder over the whole document. Otherwise, only the active page is processed.

• Check Dotted Stroke to get a dotted border using the “Japanese Dots” stroke type.

• The script always creates the border in a dedicated layer called PageBorderLayer, which is automatically locked. You don't need to handle or remove this layer by yourself, because the script manages it:
— To update the border(s) at any time, rerun PageBorder, adjust the settings, and press OK.
— To finally remove the border(s) when your document goes to print, run PageBorder, check Remove the border, and press OK.

• See also:
— Review and Demo of PageBorder in French (Urbanbike).
— Review on Cari Jansen's blog.
— Review on DesignGu.ru (in Russian).
— The script is mentioned on InDesignSecrets: “This Week in InDesign Articles, Number 41”.

• Special thanks and credits to: Jean-Christophe Courte, Stéphane Georis, David Blatner, and of course Cari Jansen for the original idea.