> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/reports/report-tag-conventions/collections.md). # Collections Some sources of Project content are in the form of **collections**, meaning that when the reporting system returns results based on your report tags for these it'll potentially find *multiple* results. Examples of this include * Location information – the system will go find information on all the location points that are associated with your context * Media – the system will go find the all media files and file details that are associated with your context There are more collections that can be sourced with the reporting system, and you can find more detail on them in [later sections of this documentation](https://codifi-fdm.gitbook.io/codifi-reports/reports/report-tag-conventions/report-tag-sources). Collections need to be handled in a special manner when constructing your report tags that involve them. {% tabs %} {% tab title=".docx" %} You have options for how to construct your report tags for collections: 1. Using a "foreach" 2. Using a "forone" 3. Using a "first" 4. Using a "table" *** ## "foreach" Conventions Since a report tag that involves a collection can return multiple results, you can instruct the system to "loop" through the results and to provide certain content back *for each* result. A "for each" report tag will print content for each result based on how you write your tags within the opening and ending elements of the "for each" tag. {% hint style="info" %} Remember: a "for each" *must* have both an opening and an ending element in order for the system to recognize your tags. These elements must be separated on their own lines, by paragraph breaks (i.e enter/return, not shift+enter) {% endhint %} Here's how a "for each" is written > {{foreach(collection)}} > > {{term}} > > {{endForeach}} Note that there is an opening element and an ending element. Here's an example of how a "for each" can be applied > {{foreach(medias)}} > > {{image}} > > {{endForeach}} This will print an image onto the report for any photos that are related to your current context, if any. Each image returned in the results will be printed on a separate line. ## "forone" Conventions Alternatively, if you don't want the system to loop through and return the content you've specified for all the results in a collection, you can use a "forone" instead of a "foreach". This will return only one result from the potentially multiple results in a collection. You can more clearly specify which result out of the collection will be returned by using filters. Here is how a "forone" is written > {{forone(collection)}} > > {{term}} > > {{endForone}} Here's an example of how it can be applied > {{forone(medias)}} > > {{image}} > > {{caption}} > > {{endForone}} This will look for the collection of media related to the contexts the report is generated from, and will return a single result out of that media collection, for which the system will print a photo (in the default style since no options were specified) along with the caption of that photo. ## "first" Conventions Similar to a "for one", you can also use a "first" to pull content from a single result in a collection. This approach can be helpful in situations where, for formatting reasons, you don't want to have to break up the flow of your document with multiple lines. Here's how a "first" is written > {{first(collection).term}} Here's an example of how it can be applied > {{first(locations).ZoneNumber}} This will return the first location point for the location of your context, and print the UTM Zone Number of that location point. ## "table" Conventions Collections can also be constructed within tables. Here's how you write a collection into a table

Here's an example of how an application for a table

This will print a table of photos and their captions for any image media files that are related to your context. Each result will print on a new row in the table; the table will automatically expand as necessary to add new rows depending on how many results are returned in the collection. In the above to examples, the table was given a header row while preparing the report template, and the labels of those columns in that row were written normally in plain text. If you know what you intend on having in each column, you can use a method like that to simply write what your columns are. However, if you would instead like determine these more dynamically, the reporting system can programmatically determine your header row and how many columns you'll need. Here's how you can write this

With these conventions, the system will read that you want it to programmatically determine what your columns and headers will, and that you want it to print the corresponding values from the results of the collection in rows below the header row. Here's an example of how this can be applied

This will return a table of the fields in the context that the report is generated from, where there will be a column for every field in that collection – the column headers determined by the field label of each field – and then in the following rows will contain the values for each result. {% hint style="info" %} This method of constructing tables can be helpful when attempting to print results for a number of different Records of the same Archetype, and also when attempting to print the data from a repeater section within a Record. {% endhint %} ## Nested Collections Collections can be tagged into collections into collections into collections into other collections on and on until either the Codifi system explodes from the endless regression of collections or the universe does, whichever occurs first. You have the flexibility to tag either style of collection (“foreach” or table) within either style of collection, and you can have multiple at each level of the nesting. Here's an example

This would print several collections returned from your report context, at three different nested levels… * A collection (in “foreach” format) of the direct child Records from your context, listing them by Record Name * Within that collection, for each child you’d have a collection (in table format) of descendants (all descended related Records for each child), printing out the Name of each descendant and its Status * Within that collection, yet another collection (in “foreach” format) of the UTM location coordinates for each of those descendants, printing out the Zone Number, Easting, and Northing for all coordinates associated with each descendant * Also within the collection of direct children, a collection (in “foreach” format) of all the media associated with each child, where photos would be printed, along with the Title and Caption for each photo ## The Context of Collections Keep in mind that when you tag a collection into a report, when the reporting system is returning results for that tag it'll shift its context of "where" it's working to be that collection. Once the system gets past the ending element of your collection's report tag, it'll shift back to whatever context it was on previously. Take the nested collections example above :point\_up: and let's assume that the report is being generated from a specific Record within a Project. The beginning context is the Record that you chose to generate the report from, but once the system reaches the first collection... > {{foreach(children)}} ... it will shift the context to each direct *related* child Record as it loops through the found results of that collection. You can see that while working in that context, the system has been instructed to source the {{name}} of each child Record (and the system knows that you mean the name of the child Records, since the context is the collection of children. Within each result of that collection, there's another collection... > {{table(descendants)}} ...meaning it will be shifting the context to each related descendant Record (aka all downstream children of each context in the previous collection) as it loops through the results. You can see that the system has also been instructed to source a {{name}} here as well. The system knows that you mean the name of each descendant Record from each of the original child Records, because the context is that you are looking at the collection of descendants within the collection of children. Within that table collection there's another collection... > {{foreach(locations)}} ...meaning it will be shifting the context to each location point of each descendant Record in the previous collection. {% endtab %} {% tab title=".xlsx" %} The only tag used in Excel reports is a "block." A block will repeat a group of cells for each element of the collection passed to it. A block takes three arguments `{{block(#ofRows,#ofColumns,collection)}}` So in the following example, we are repeating the 1 row and 4 columns below the block tag, and this will print a new row for each element contained in the collection.

{% hint style="warning" %} The row containing the {{block(...)}} tag will be deleted. If the collection passed as an argument to the block has no element, the block and the specified number of rows beneath it will be deleted. {% endhint %} {% endtab %} {% endtabs %} *** See [Report Tag Sources](/codifi-docs/reports/report-tag-conventions/report-tags-and-properties.md) to find details about collections that can be used to source data from Projects.