^{Excerpted from my book FrameScript for Newbies  Copyright [7/17/2007] by Paul Schnall}

Loops are a way of moving through a book or document and running lines of code on each object of a particular type. For example, looping through every paragraph (paragraph being the object) in a document and searching for a specific word or text is easily done using this construct.

Items that can be looped through include but are not limited to:

• Paragraphs
• Tables 
• Table rows
• Table Cells
• Docs in a book
• Pgf formats
• Variables
• Cross References

Figure 1) How Loops Work

Loop While

The Loop While construction continues to run as long as the While Condition (the part in the parenthesis) is true. The condition can be an equation or a FrameMaker object. When the condition is a FrameMaker object, then the condition is true so long as there remains another object specified by the condition within the document().

For example I want to loop through all of the tables in a document. I start by looking (Loop While) within every paragraph for table anchors. When I find a paragraph with a table anchor I can run some lines of code on the table. The loop continues to move through the document until there are no more paragraphs left.

Loop While allows you to set a variable for the condition.

Defining any object or variable that can be only true or false specifies a method of controlling the loop. The loop will continue while the variable returns a true value.

Say we start out by assigning a variable vPgf to the first paragraph in the main flow of the document. We run some lines of code on this paragraph. We can then reassign the variable vPgf to the NextPgfInFlow, and then run the same lines of code on the second paragraph.

Some properties allow us to start at the end of the document and move forward to the beginning.

Figure 2) Looping through paragraphs

The two scripts above are identical except for the starting point and direction of the loop.

Example 1

Loop While (vPgf)

Do Something Here.

Set vPgf = vPgf.NextPgfInFlow;

EndLoop

This Loop will move from one Paragraph to the next until it reaches the end of the document. At the end of the document when the script moves from the last paragraph to the end of the document vPgf.NextPgfInFlow will have a value of 0 because there are no paragraphs left in the document, and the loop will stop. At this point the script goes to the line of code after the EndLoop command.

Example 2

Set n = 0;

Loop While (n<= 25)

Set n = n + 1;

Do Something Here.

EndLoop

This loop starts out with n being set to 0 before the loop starts. Within the loop the value of n is increased by 1 with each iteration of the loop.
When the value of n is greater than 25 the script will exit the loop.

The While condition can be anything that has a value of 0(false) or 1(true).

In the first example

moves the script through the doc and in the second example

moves the script through the doc.

Loop Until

Loop Until is the same as Loop While but here the value of the conditional variable is opposite. That is, a value of 0 (false) will continue the loop and a value of 1 (true) ends the loop.

Loop ForEach

The Loop ForEach command will loop through a FrameMaker Object and loop through each sub object. A sub object could be a table anchor within a paragraph.

The Command Reference Guide has a table showing the loop ForEach object and its corresponding source object that can be looped using this command. The following code drills down to each paragraph in each cell in a selected Table.

//Don't select the Table using the Table anchor. Select any of the cells in the table.

Set vCurrentDoc = ActiveDoc;

Set vTbl = Selectedtbl;

Loop ForEach(Row) In(vTbl) LoopVar(vtblRow)

Loop ForEach(Cell) In(vtblRow) LoopVar(vtblCell)

Loop ForEach(Pgf) In(vtblCell) LoopVar(vtblCellPgf)

/*

do something here

*/

EndLoop

EndLoop

EndLoop

Update DocObject(ActiveDoc) Redisplay;

Counters

Counters are an easy way to control a loop. They can also be a safety valve during the creation of a script to prevent an unending loop. If there is nothing to advance the loop it runs through the same paragraph again and again until the script crashes.

When loops do not have a way out the only way to stop the script is to shut the program with the task manager. And this can result in losing what you have written so far.

The following script goes through the active doc and counts the Paragraphs.

Set vCurrentDoc = ActiveDoc;

Set vPgf = vCurrentDoc.MainFlowInDoc.FirstPgfInFlow;

Set n = 1;

Loop While (vPgf)

Set n = n+1;

If n = 100

LeaveLoop

EndIf

Set vPgf = vPgf.NextPgfInFlow;

EndLoop

Display 'There are '+ n +' paragraphs in the current document.';

LoopNext

This command tells the script to jump out of the loop and continue with the next iteration of the existing loop.

LeaveLoop

The leaveloop command jumps out of the current loop and starts the script after the Endloop command.