This article is overview of what loops are and how to use them. For a more specific outline of the Loop action functionality, see the Loop Action in the Action Reference.
What is a Loop?
A loop is simply a way of saying to do the same thing over and over again. We use loops frequently in our every day lives to simplify instructions. For example, when giving directions, it is much easier to say “walk four blocks,” rather than “walk a block, then another block, then another block, and then another block.”
Loops are used in Fuga the same way: to tell the Flow to repeat the same set of actions multiple times. For example, if you want to duplicate and move an object ten times, instead of creating ten duplicate actions, you can simply insert one duplicate action into a loop and tell the loop to repeat the action ten times.
You can tell a loop to repeat based on different factors, like a specific number of repetitions, how many items are selected, or a range of dates.
When combined with other actions, loops are even more powerful. When using a loop with the If action you can create exceptions, where you perform a set of actions except when a certain condition is met (e.g., move all boxes, except for the boxes that contains the text “do not move me”).
A loop variable is used to keep track of the current status of the loop (that is, the current step its on or the current object selected). This information is used by Flow to determine how many more times to repeat the loop, and can also be used by other actions within the loop.
Creating a Loop and Inserting Actions Into It
To create a loop, click the Flow actions category in the Fuga Workshop panel, and select Loop from the actions toolbox to place the action into the flow. Setup the loop actions parameters based on your loop type, as explained further down in this article.
To insert actions into the loop you can either:
- Insert new actions into the loop by clicking the Insert Action action and then clicking the new actions to insert into the loop from the actions toolbox.
- Drag preexisting actions in between the Insert Action action and the Loop.
In Fuga, the different loop types provide different ways of specifying how many times to repeat the loop. This is useful in the same way that it’s useful to specify to either “walk 100 steps” or to “walk until you reach the post-office,” depending upon the situation.
A Numeric Loop repeats the same set of actions an exact number of times. Using a numeric loop you can say “repeat these actions ten times” or “repeat these actions 100 times.” This loop is normally used when there is a fixed number of repetitions you want.
The Numeric Loop Variable
When you define a numeric loop, the loop variable serves as a counter for keeping track of which step you are on. This counter increases each time the Flow goes through the loop, and the flow will know to stop the loop when it reaches the number you specify.
Using a Basic Numeric Loop
For an basic example of a numeric loop, see the Basic Loop example under the Loop Action in the actions reference.
Advanced Numeric Loops
Using the From, To, and Step fields, you can also make the loop do things like count backwards, or count in multiples of a certain number. As you get more familiar with Fuga, you’ll find that there are some specific design issues where using advanced counting can be useful.
To count backwards to one, insert the number you would like to start counting from in the From field. In the To field insert 1, or the number you want to count down to. In the step field, insert -1.
To count in multiples, insert the number you would like to count from in the From field, and the number you would like to count to in the To field. In the Step field insert the number would like to increase or decrease the variable by.
For an example of advanced counting, see the Advanced Counting example under the Loop Action in the action reference.
Counting Based On A Variable
You can use a numeric variable for any of the From, To, and Step fields for additional flexibility.
Selected Objects Loops
A Selected Object Loop cycles through each selected object and performs the actions within the loop on each one. It’s the equivalent of saying “repeat these actions on each one of the selected objects.” This loop is used when you want to base the amount of repetitions on an amount of objects, however many there may be.
The Object Selection Order In a Selected Objects Loop
When using a Selected Objects Loop, you can define how Fuga should cycle through the selected objects (i.e., what order they’re selected in) using the Selected Object Loop Parameters.
The Select Objects Loop Variable
The Selected Objects Loop variable stores the name of the selected object at each step. If you would like an additional variable to keep track of how many times the loop has repeated as well, create one in the variable table in the Workshop panel, and use the Set action to increase the variable by 1 each time the loop is performed.
Using a Selected Objects Loop
For an example of using a Selected Objects loop, see the Selected Objects Loop Example in the Loop Action’s article in the action reference.
A Data Row Loop repeats based on the amount of data rows in a specified CSV. Using a Data Rows loop is the equivalent of saying “Repeat these actions for each row in a CSV.”
The Data Rows Loop Variable
The Data Rows Loop variable stores the number of the current row. When counting rows keep in mind that row numbers are counted from the first row under the column headings, so row 1 is the first row with the data we would actually want to insert into the document. This is different than in spreadsheet editors, which count the row with the column headings as the first row.
Using a Data Rows Loop
For an example of using a Data Rows loop, see the Data Rows example in the Loop Action’s article in the action reference. Also see the multiple rows examples from the Load Vars and Load Data action reference pages, and the article on File Paths (since you need to specify the spreadsheet file path in order to use this option).
Other Loop Types
For information on the other types of loops, see the Loop Action in the Action Reference.
Additional Ways to Manipulate Loops
If you want to stop the loop when an alternative condition is met, you can use the Stop Loop action. For example, you could use the selected objects loop to cycle through all the selected objects as it normally would, but if the text inside an object says “stop here” you can use the Stop Loop action to stop the loop there and move on to the rest of the actions in the flow. To stop the flow all together when a certain condition is met you can use the Stop action.
Next Loop Step
If you want to stop the current loop step and move onto the next one, you can use the Next Loop Step action. When performed, this action will tell Fuga to skip the actions under it in the loop and to move onto the next loop step. For example, in a selected objects loop you could tell Fuga to move to the next loop step when the text in an object says “skip me” and Fuga won’t perform the rest of the actions on that object, but then will continue with the rest of the loop.