The grab function fetches the required value from a variable in the specified numerical index position.
Syntax
{collectionVariable | grab:indexPosition:'variable'}
Use Cases
There are a few different ways to use the grab function. It is possible to grab a specific piece of data, or an entire collection. It is also possible to perform a ‘double grab’ by first specifying the sub-collection we’re grabbing, then retrieving a specific piece of data within that sub-collection. Using the following sample data set, let’s explore the different use cases.
|
Directors |
Offices Held |
Address |
Communications |
|---|---|---|---|
|
1. Monica Geller - incoming
|
|
90 Bedford Street, Unit 19 |
Email: mongellar@javu.com Phone: (212) 845-1239 |
|
2. Ross Geller - confirmed
|
|
99 Bedford Street, Unit 25 |
Email: rgellar@nyu.edu Phone: (718) 404-2886 |
|
3. Chandler Bing - confirmed
|
|
90 Bedford Street, Unit 20 |
Email: bingchan@sadr.com Phone: (212) 749-1986 |
|
4. Joey Tribbiani - incoming
|
|
90 Bedford Street, Unit 20 |
Email: joeyactor69@aol.com Phone: (718) 966-4049 |
|
5. Phoebe Buffay - confirmed
|
|
495 Grove Street |
Email: phoebenotursula@gmail.com Phone: (718) 813-9300 |
|
6. Rachel Green - incoming
|
|
90 Bedford Street, Unit 19 |
Email: rachel.green2@lv.com Phone: (212) 202-1005 |
Grabbing Data
When we want to grab a specific piece of data, we simply format our code according to the general syntax, including any filters or functions to refine the data:
{directors | status:'confirmed' | orderBy_B:'lastName' | grab:'1':'taxCountry'}This code is going into the directors collection, filtering for confirmed directors only, sorting alphabetically by last name, then grabbing the tax residency of the first individual who matches this criteria.
|
Monica Gellar |
Ross Gellar |
|
Canada |
To grab the tax residency information of the second individual who matches this criteria, Phoebe Buffay, simply change the index position of the grab function to ‘2,’ as follows:
1{directors | status:'confirmed' | orderBy_B:'lastName' | grab:'2':'taxCountry'}The {taxCountry} that would be grabbed with the second code would be Panama for Phoebe.
Grabbing Collections
Within a root collection, if we want to go into a sub-collection and loop through the data, we can grab that specific sub-collection, and instruct the system to loop through all the data available. When used in this way, the grab function is being used within a loop, and must be opened with a # and closed with {/}.
In this example, we are using collection loops. Loops should be used with caution when coding PDF forms as most forms require each specific piece of data to be filled in its own field.
1{#directors | status:'incoming' | grab:'1':'officesHeld'}{office}{/}This code is going into the directors collection, filtering for incoming directors only, grabbing the entire Offices Held sub-collection for the first incoming director, then looping through all the offices within the Offices Held sub-collection.
|
Monica Gellar |
Monica Gellar |
Chief Executive Officer President |
{#directors | status:'incoming' | grab:'2':'officesHeld'}{office}{/}The {office} that would be grabbed with the second code would be Secretary for Joey.
Grabbing Data within a Grabbed Collection, or the ‘Double Grab’
Occasionally, it is necessary to grab specific data within a specific grabbed sub-collection. We can do this by combining the syntax above to create the ‘Double Grab’. Since this is not looping through the sub-collection, there’s no need to use opening or closing tags.
{directors | grab:'1':'communications' | filter:'label':'Email' | grab:'1':'value'}This code is going into the directors collection, grabbing the entire Communications sub-collection for the first director, Monica Gellar, filtering all the labels for Email (being the communication type), then grabbing the first email listed for Monica.
|
Monica Gellar |
Email: mongellar@javu.com Phone: (212) 845-1239 |
{directors | grab:'2':'communications' | filter:'label':'Email' | grab:'1':'value'}This code is going into the directors collection, grabbing the entire Communications sub-collection for the second director, Ross Gellar, filtering all the labels for Email, then grabbing the first email listed Ross.
|
Monica Gellar |
Email: rgellar@nyu.edu Phone: (718) 404-2886 |
|
Beware when using any Find and Replace functions with the ‘Double Grab’, as the index position is very important. In the above case, to grab the email listed for the second director, we must change the index position of the sub-collection only. The index position for ‘value’ does not change.
In this case, if we used Find and Replace and replaced every grab:'1' with grab:'2', the code would look like this:
{#directors | grab:'2':'communications' | filter:'label':'Email' | grab:'2':'value'}
This code would be grabbing the Communications sub-collection for the second director correctly, and then trying to grab the second email listed for the second director.
There would be no output since there is no second email listed for Ross.