An Introduction to Writing Scripts

FrameScript is a lot like FrameMaker; it has a fairly steep learning curve, but once you learn it, you’ll find it a real workhorse. The best way to start is to read the FrameScript Scriptwriter’s Guide. And the Quick Reference will provide you shortcuts to learning the FrameScript syntax. This tutorial will introduce some foundational concepts of writing scripts that will help you get started.

Objects and properties

Before we start scripting, let’s define a couple of terms. A FrameScript script manipulates FrameMaker objects. By objects, we mean items such as paragraphs, anchored frames, and pages. FrameMaker objects have properties that are characteristics of the objects. A paragraph has a FirstIndent property and a Color property. Many of an object’s properties are the same as those accessed by the FrameMaker interface (although the names are often different); for example a paragraph’s properties can be accessed through the Paragraph Designer.

Much of the work of scripting is finding out how to access an object and which of its properties to change. Let’s see how this works by writing a short script.

Create a new, portrait document and type “Hello world!” in the first paragraph. Double-click the word Hello to highlight it. Choose FrameScript > Script Window to open the Script Window. Type the following lines in the Script Window:

Set vText = TextSelection;
Display vText;

In the first line, we are setting up a variable called vText. In programming, a variable is like a placeholder for information. You use just about any name you want for a variable as long as it is not a FrameScript command or FrameMaker object or property name. I like to start my variables names with a lower case v to distiguish them from reserved names, and so that I know at a glance that they are variables. We are using the Set command and the equal sign to set the value of vText to TextSelection. TextSelection is a FrameMaker object that represents the current text selection in a document. Click the Run button.

 The FrameScript command Display displays a message box showing you the value of vText. The contents of the message box may not seem very useful at this point, but it does tell use that we are displaying a TextRange object. Let’s modify the script: change the first line to

Set vText = TextSelection.Begin;

and click Run.

Now we are displaying a TextLoc (Text Location) object. A TextRange object is made up of two TextLoc objects; one marks the beginning of the selection (Begin), the other marks the end of the selection (End). Now change the first line to

Set vText = TextSelection.Begin.Object;

and click Run.

Now we are displaying a paragraph (Pgf) object. This is the paragraph that contains the text location (TextLoc) object which is part of the current text selection (TextRange) object.

This exercise illustrates another important concept: FrameMaker objects are usually nested inside other objects. FrameScript uses “dot-notation” to move up and down the list of objects. Once you locate the appropriate object, you can access its properties. Change the first line to

Set vText = TextSelection.Begin.Object.Properties;

and click Run. Now you see a list of the current paragraph’s properties; a list that’s probably too long to fit on your screen. Press Enter or Return key to dismiss the list. Change the word Properties to Name and click Run. The paragraph format that is applied to the paragraph is displayed.

Your first script

Let’s apply some of this FrameScript theory and write a useful script. This script will give you a sample of all of the paragraph formats in your document. It will insert one paragraph into your document for each of the paragraph formats in the document’s catalog. The paragraph will contain the format’s name and will have the format applied to it.

Loop through the paragraph formats in the document

First, click New in the Script Window to add a blank script tab. Open a new, portrait document. The first thing we need to do is get a list of the document’s paragraph formats. FrameScript has a special mechanism for accessing lists of FrameMaker objects. Type the following lines in the Script Window:

Loop ForEach(PgfFmt) In(ActiveDoc) LoopVar(vPgfFmt)

EndLoop

This script simply loops through the list of paragraph format objects (PgfFmt) in the document. At this point that’s all it does; click Run and nothing happens. We want the script to do something to each object in the list. Let’s use dot-notation to access each paragraph format’s Name property. Add the following line to the inside of the loop (before the EndLoop line):

Display vPgfFmt.Name;

and click Run.

Now the script displays the name of each of the paragraph formats. This can be a little tedious, because you have to click OK to dismiss each name. Change Display to Write Console, and click Run. Now the names are written all at once to the FrameMaker Console window. Maximize the Console window to see the list.

Write the paragraph format names to the document

Writing a script usually means performing several tasks and stringing them together. We found out how to get a list of paragraph formats, but now our task is to get this list into the document. We will need a new paragraph for each of the paragraph formats in the document. To make a new paragraph, use the New Pgf command:

New Pgf NewVar(vPgf) PrevObject(vPrevObject);

This command requires a PrevObject (Previous Object) object; in other words, an object to place the new paragraph after. Our blank document only contains one paragraph, so we can make that our PrevObject. Delete the Write Console line, and add these lines to the script between the Loop and EndLoop lines:

Set vPrevObject = ActiveDoc.MainFlowInDoc.LastPgfInFlow;
New Pgf NewVar(vPgf) PrevObject(vPrevObject);

and click Run. A new paragraph is added to the document for each of the paragraph formats in the document. The paragraphs are blank, so we need to add the paragraph format names. Add this line under the New Pgf line:

New Text Object(vPgf) vPgfFmt.Name;

The New Text command requires a location for the text; in this case, vPgf specifies the paragraph object that you just made with the New Pgf command. The text you are inserting is the Name property of the current vPgfFmt object. Delete the blank paragraphs in your document and try running the script. You should see a list of the paragraph formats in the document.

Before moving on to the next task—applying the correct paragraph format to each line—let’s examine the script so far. The first and last lines simply loop through the document’s list of paragraph formats. Whatever is inside the loop is repeated for each paragraph format in the list. This illustrates the role that variables play in scripting. The variable name vPgfFmt stays the same, but its value changes as the script executes. The same is true for the variable vPrevObject; each time through the loop it is set to the last paragraph (LastPgfInFlow) of the main flow (MainFlowInDoc) in the current document (ActiveDoc). To help you visualize this, add the following line after the Set vPrevObject line:

Display vPrevObject.Text;

and click Run. You will see that the PrevObject variable is always set to be the last paragraph. Delete this line before continuing.

Apply paragraph formats to the paragraphs

The third and final task is to apply each paragraph format’s properties to the paragraph that bares its name. As you can guess, this task will be performed inside the loop. First, add the following line before the EndLoop line:

Set vPgf.Properties = vPgfFmt.Properties;

This line simply sets the properties of the new paragraph to match the paragraph format properties. Delete all the paragraphs from your document and run the script.

Before closing the Script Window, make sure you save your script with a name you can remember. I call mine ShowAllParaFormats.fsl. The entire script is listed below for completeness.

Loop ForEach(PgfFmt) In(ActiveDoc) LoopVar(vPgfFmt)
  Set vPrevObject = ActiveDoc.MainFlowInDoc.LastPgfInFlow;
  New Pgf NewVar(vPgf) PrevObject(vPrevObject);
  New Text Object(vPgf) vPgfFmt.Name;
  Set vPgf.Properties = vPgfFmt.Properties;
EndLoop