Loop through a list of items

If you have an integration setup that is sending data in an array or JSON object, you can set up loops in your document to print that information. This article will walk through multiple ways to accomplish this as well as how to best test your document before it goes live.

Examples of how arrays of data are used with Formstack Documents include; line items on an invoice, child records associated with a parent record in a CRM, or a list of items for a report.

 

Overview of Data Structure

Viewing Data in Formstack Documents

Create a Simple List

Create a Table

Create a Bulleted/Numbered List

Sorting Your List

Sort by Multiple Fields

Sum Calculation in a Loop

Extra - Salesforce Mapping Screen (Documents For Salesforce Specific)

Overview of Data Structure

From a technical standpoint, your data will look like this for HTTP POST (name/value pairs)

items[0][Name]=Shirt&items[0][Quantity]=2&items[0][Price]=19.95&items[1][Name]=Jeans&items[1][Quantity]=3&items[1][Price]=89.99

Or JSON:

{"items":[{"Name":"Shirt","Quantity":"2","Price":"19.95","Total":"39.90"},{"Name":"Jeans","Quantity":"3","Price":"89.99","Total":"269.97"}]}

Viewing Data in Formstack Documents

Formstack Documents makes it easy to see if the data we are receiving from your system is in an array. 

• First go into your document settings tab and look at the bottom of the screen
• Under the "Status" options, select "Test Mode". This will turn the document into test status and will allow you to run your data flow tests without using your standard merge allotment. These merges will instead count towards your test merge limit. Please refer to this article for a deeper breakdown of merge types.
• Select "Save Merge Data for Debugging". This option will allow us to hold the data for up to 24 hours and will allow you to easily view how we are receiving the data you are sending to us. 
• Click "Save Settings"

• Run a test from your system to us to produce data for our system.
• Once the test has run, go to the "Overview" tab on your document and you will now see a new option called, "View Data". Select that option and you will be presented with all of the data we have received from your system.

• If an array of data was sent over to us, you will see the term "Array" in the list of data as well as how many items are within that array.  By clicking on the line item, it will expand that array and you can see each of the items that were sent over. If you click on each of the items within the array, we will provide you with the proper name of that item in dot notation form. 

Create a Simple List

If you have a list of items that you would just like to print in your document, you can use the following {foreach} code

{foreach from=$items item=_row}
{$_row.Quantity} x {$_row.Name} = ${$_row.Price|number_format:2}
{/foreach}

Create a Table

If you're generating an invoice, you're probably looking to create a table that loops through each of the line items and prints them on a new row in the table.  No problem!  We've added a new "tablerow" tag that you can use and it tells our system to treat the table row as a loop.  The tag works exactly like a "foreach" loop, so all you need to do is use "tablerow" instead of "foreach" and we'll handle the rest.

Here's an example:

The data that you send through to a table row loop needs to be an array (ie and array of products) that can be easily looped through.  The part after the dot in the variable name is the individual property for that element in the array.

If you'd like to skip items in the list, you can use an if statement in your table like this:

Create a Bulleted/Numbered List

You can also use special "listrow" code to loop through items in a list to create a bulleted list.  Like this:

• {listrow from=$products item=_p}{$_p}{/listrow}

Sort Your List

If you would like to sort your items based on a certain "key" you can do so using the "sort" modifier in this format "|sort:[KEY]:[asc or desc]" (asc is default). For example:

{foreach from=$items|sort:"Name" item=_row}
{$_row.Quantity} x {$_row.Name} = ${$_row.Price|number_format:2}
{/foreach}

To sort by price in descending order:

{foreach from=$items|sort:"Price":"desc" item=_row}
{$_row.Quantity} x {$_row.Name} = ${$_row.Price|number_format:2}
{/foreach}

Sort By Multiple Fields

If you would like to sort your items based on multiple keys, you can do so using the "multisort" modifier in this format "|multisort:[KEY1]:[asc or desc]:[KEY2]:[asc or desc]" (asc is default). For example: 

{foreach from=$items|multisort:"Name":"asc":"Price":"desc" item=_row}
{$_row.Quantity} x {$_row.Name} = ${$_row.Price|number_format:2}
{/foreach}

Sum Calculation in a Loop

If you would like to take a numeric field of each item in your loop and sum the total values, you can do so by adding a calculation inside the loop. In the example below, this added calculation is in the "Total" column. For example: 

Salesforce Mapping Screen (Documents For Salesforce Specific)

Here is what the mapping screen in our Documents For Salesforce product looks like. Mapping to child objects of the object you have selected as your primary object or mapping to the "Full Object" you are working with will produce an array of data that will be sent over to Formstack Documents. 

Note - For more information on our Documents For Salesforce product, please review this article .