It's often necessary to include data from a record's related lists in your documents. In the template editor, S-Docs includes a powerful, easy-to-use related list generator just for this purpose.

For example, if you have a template from an opportunity, you can insert a related list that will display certain fields from an opportunity's child quote records. The S-Docs related list generator provides a complete range of flexibility in developing templated related lists. For example, without even editing any code, you can adjust the formatting of the related list's table and columns, select any of the related list object's fields that you would like displayed in your table, and even filter/sort the related list rows by user-specified criteria. If you decide to go one step further and edit the related list source code, the possibilities for modification become endless.

This guide will discuss how you can use the S-Docs template editor to create a table with columns comprised of related list fields. In the following steps, we will be creating a very basic related list that might generate the following document:

Dev Guide - Adding a Related List (1)

The document above was generated from a template for an opportunity. In this template, we inserted a related list for an opportunity’s child quote records. You can find a list of more advanced related list column attributes in our Advanced Template Features document.

Note: This article goes over how to use the Insert Related List button to format your related list data into a table. If you have other formatting requirements, please see our guide to customizing your related list layout. You can also generate a separate document for each record in your related list. For extensive customization opportunities, you may also want to consider generating a component template for each record in your related list. This method allows you to format your data in a separate component template in any way that you like, and reference that component in your main template.

Use The "Insert Related List" Button

Now, let's begin! In the template editor for our opportunity template, we start by clicking the Insert Related List button at the top of the page.

Select A Related List

The following window will appear. You have the option to edit a previous related list, or start with a new one, which is what we'll do in this example. The drop-down menu under “Step 1: Select a Related List” allows you to select an available related list for your object. In this case, we selected the quotes related list for our opportunity.

Choose Table Columns

We then scroll down to Step 2: Choose Table Columns. Under the “Available Fields” list, we can select fields from the quote object to be used as columns in the table that we are inserting. To add a field as a column in our table, click the name of that field and then click the button under “Add” (similarly, you can select a field in “Selected Columns” and click the button above “Remove” to remove that field from your table’s columns).

We added two fields to our selected columns. This will result in a “name” column and a “grand total” column for our table; when we generate a document for this opportunity, the name of each quote will be displayed under the “name” column, and the grand total of each quote will be displayed under the “grandtotal” column (we can edit the names of the columns later).

Note that some of these fields have this character to the right of them: “>.” In our example, we see that two of these fields are “contact id >” and “created by id >.” These fields correspond to IDs of object records in our related list; clicking on them will bring up another menu where we can pull data from these object records. In the table in our example, we will include a column for the nickname of the user who created the quote.

So, in our resulting table so far, we will have a column for the name of each quote related to the opportunity that we generate a document for, as well as columns for the grand total of each quote and the nickname of the user who created that quote. Note that we can change the order of our columns with the Move Up and Move Down controls. This will change the order of the columns as they appear in the final table from left to right (up is left and down is right; the uppermost column in the “Selected Columns” list will be leftmost in the resulting table).

So, our columns would currently appear in this order:

Dev Guide - Adding a Related List (6)

To move the nickname column to the left, we select CreatedBy.communitynickname and move it up.

Now, the columns in our resulting table will appear as follows:

Dev Guide - Adding a Related List (8)

Format Table Columns

After selecting all the columns you’d like to have in your related list, open the Format Data Columns tab.

Here, we can edit how each column will appear. By default, our columns will be named “name,” “communitynickname,” and “grandtotal.” We can change these names under “Header Text (Column Header).” The other fields offer useful formatting options for each entry under the selected column. For the “grandtotal” column in our example, we set the prefix text to “$” and the format number to #,###.## so that grandtotal entries will be formatted as currency.

Additional Table Formatting & Styles

After formatting your columns, click Formatting & Styles to apply even more formatting to your table. We can change the table style as a whole as well as change the formatting of the text in each individual column.

Filter & Change Row Order

You can also filter out rows and change the order in which the rows are sorted using SOQL and filter logic by accessing the Filters and Sort Order tab. Examples of filter logic are included under the description for each field in this tab: for example, using “CreatedDate = THIS_YEAR” in the first field would make our table comprised of quotes from this year; quotes related to our opportunity from other years would not be included. The other two fields allow us to limit the number of rows created in our table, and to sort our rows by filter logic or SOQL ORDER BY clauses.

Dev Guide - Adding a Related List (12)

Edit Source Code

Finally, view the Advanced tab to see the source code generated for the table you have been creating. You may edit the source here before inserting the table if you wish to fine tune your table’s qualities (you can also edit your related list in the template editor's source mode after inserting your related list). You can edit the CSS here in order to fine-tune the formatting of your table (e.g. border-width, font-size, the background color of even rows, etc.). If you'd like more control over your related list's layout, you can customize your related list code; extensive documentation on this can be found here.

Insert Your Related List

Click Insert to insert the table into your template.

Note that we do not see any data or fields under our columns, as this is a template. The table will populate as expected upon document generation. If you wish to edit your table after insertion (such as adding and deleting certain fields it uses as columns), you can click Insert Related List again and select your related list under the Edit a Previous Related List section.

You may also edit it in the source editor. That's it! You are now ready to use related lists in your templates.