Admin

Introduction

There are plenty of times where a user might want to generate documents for each item in one of the related lists on the current record they're viewing. For example, the user may want to click a button on an Opportunity Record that sends an email to each Contact Role related to that Opportunity, or the user might want to click a button on an Account record that generates an Opportunity Summary for each Opportunity record related to that Account. Setting up this feature is as simple as copying and pasting the following code into your org.

Step 1: Create Apex Class

Head over to Setup > Build > Develop > Apex Classes > New and copy/paste the following code into your new Apex class, then click Save.
[code lang="html"]public class SDRelatedListDocumentsController {
private final String TYPE_FILTER;
public String parentId {get;set;}
public Boolean allowEmail {get;set;}
public Boolean allowCombineAll {get;set;}
public Boolean emailedDocuments {get;set;}
public String objSortFieldOrderbyDirection {get;set;}
public Map<Id, SObject> childRecordMap {get;set;}
public SDRelatedListDocumentsController() {
parentId = ApexPages.currentPage().getParameters().get('parentId');
TYPE_FILTER = 'Related List Document - ' + parentId;
}
public List<SDJobWrapper> sdocJobWrappers {
get {
List<SDJobWrapper> sdjwList = new List<SDJobWrapper>();
List<SDOC__SDJob__c> relatedListDocJobs = [
SELECT SDOC__Status_Link__c, SDOC__Oid__c,
SDOC__SDoc1__r.Id, SDOC__SDoc1__r.SDOC__Attachment_Name__c
FROM SDOC__SDJob__c
WHERE OwnerId=:UserInfo.getUserId()
AND SDOC__Type__c=:TYPE_FILTER
];
for (SDOC__SDJob__c sdj : relatedListDocJobs) {
sdjwList.add(
new SDJobWrapper(
sdj, childRecordMap.get(sdj.SDOC__Oid__c)
)
);
}
return sdjwList;
}
set;
}
public class SDJobWrapper {
public SDOC__SDJob__c job {get;set;}
public SObject obj {get;set;}
public SDJobWrapper(SDOC__SDJob__c job, SObject obj) {
this.job = job;
this.obj = obj;
}
}
public void createSDocJobs() {
delete [SELECT Id FROM SDOC__SDJob__c WHERE OwnerId=:UserInfo.getUserId() AND SDOC__Type__c=:TYPE_FILTER AND (SDOC__Status__c = 'Completed' OR SDOC__Status__c = 'Error')];
List<SDOC__SDJob__c> sdJobs = new List<SDOC__SDJob__c>();
childRecordMap = new Map<Id, SObject>();
emailedDocuments = false;
String childObjName = ApexPages.currentPage().getParameters().get('childObjName').toLowerCase();
String lookupFieldName = ApexPages.currentPage().getParameters().get('lookupFieldName');
String doclist = ApexPages.currentPage().getParameters().get('doclist');
String allowCombineAllParam = ApexPages.currentPage().getParameters().get('allowCombineAll');
allowCombineAll = allowCombineAllParam == 'true' || allowCombineAllParam == '1';
String templateBaseObject; String fieldPrefix;
if (childObjName == 'opportunitycontactrole' ||
childObjName == 'accountcontactrelation') {
templateBaseObject = 'Contact';
fieldPrefix = 'Contact.';
} else {
templateBaseObject = childObjName;
fieldPrefix = '';
}
lookupFieldName = lookupFieldName.toLowercase();
lookupFieldName = lookupFieldName.replace('__c', '__r');
if (lookupFieldName.endsWith('id')) {
lookupFieldName = lookupFieldName.substring(0, lookupFieldName.length() - 2);
}
String childrenQuery
= 'SELECT ' + fieldPrefix + 'Name, ' + fieldPrefix + 'Id '
+ ' FROM ' + childObjName
+ ' WHERE ' + lookupFieldName + '.Id =\'' + parentId + '\' ';
String additionalFilters = ApexPages.currentPage().getParameters().get('additionalFilters');
if (additionalFilters != null) childrenQuery += additionalFilters;
objSortFieldOrderbyDirection = ' ASC';
String objSortFields = ApexPages.currentPage().getParameters().get('objSortFields');
if (objSortFields != null) {
if (objSortFields.contains(' DESC')) objSortFieldOrderbyDirection = 'DESC';
objSortFields = objSortFields.remove(' DESC').remove('ASC').deleteWhitespace();
}
for (SObject child : Database.query(childrenQuery)) {
String oid;
if (childObjName == 'opportunitycontactrole' ||
childObjName == 'accountcontactrelation') {
oid = String.valueOf(child.getSObject('Contact').get('Id'));
childRecordMap.put(oid, child.getSObject('Contact'));
} else {
oid = child.Id;
childRecordMap.put(oid, child);
}
SDOC__SDJob__c sdj =
new SDOC__SDJob__c(
SDOC__Start__c=true,
SDOC__Oid__c=oid,
SDOC__ObjApiName__c=templateBaseObject,
SDOC__SendEmail__c='0',
SDOC__Doclist__c=doclist,
SDOC__Type__c=TYPE_FILTER,
SDOC__ObjSortValFieldsForSDoc__c=objSortFields
);
sdJobs.add(sdj);
}

insert sdJobs;
}
public Boolean jobsAreCompleted {
get {
Integer totalNumJobs = Database.countQuery(
'SELECT COUNT()'
+ ' FROM SDOC__SDJob__c'
+ ' WHERE OwnerId = \'' + UserInfo.getUserId() + '\''
+ ' AND SDOC__Type__c=\'' + TYPE_FILTER + '\''
+ ' AND SDOC__Status__c'
+ ' IN(\'Selected\',\'0\',\'10\',\'20\',\'40\',\'60\','
+ '\'80\',\'90\',\'95\',\'Queued\',\'Completed\',\'Error\')'
);
Integer completedSize = Database.countQuery(
'SELECT COUNT()'
+ ' FROM SDOC__SDJob__c'
+ ' WHERE OwnerId = \'' + UserInfo.getUserId() + '\''
+ ' AND SDOC__Type__c=\'' + TYPE_FILTER + '\''
+ ' AND SDOC__Status__c = \'Completed\''
);
return (completedSize + getErrorSize() == totalNumJobs) && totalNumJobs > 0;
}
set;
}
public Integer getErrorSize() {
return Database.countQuery(
'SELECT COUNT()'
+ ' FROM SDOC__SDJob__c'
+ ' WHERE OwnerId = \'' + UserInfo.getUserId() + '\''
+ ' AND SDOC__Type__c = \'' + TYPE_FILTER + '\''
+ ' AND SDOC__Status__c = \'Error\''
);
}
public PageReference returnToParentRecord() {
return new PageReference('/' + parentId);
}
public PageReference emailDocuments() {
if (!emailedDocuments) {
emailedDocuments = true;
String aid = ApexPages.currentPage().getParameters().get('aid');
String did = ApexPages.currentPage().getParameters().get('did');
PageReference emailPage = new PageReference('/apex/SDOC__SDEmail');
emailPage.setRedirect(true);
if (aid != null && aid != '') {
emailPage.getParameters().put('aid', aid);
}
if (did != null && did != '') {
emailPage.getParameters().put('did', did);
}
/* EMAIL SECTION A */
/* Emails each document individually on a per-record basis.
This occurs in the background, so the email body can't be edited in this case. */
for (SDJobWrapper sdjw : sdocJobWrappers) {
emailPage.getParameters().put('SDId', sdjw.job.SDOC__SDoc1__r.Id);
if (!Test.isRunningTest()) {
emailPage.getContent();
}
}
/* EMAIL SECTION B */
/* UNCOMMENT THIS SECTION and COMMENT OUT EMAIL SECTION A
if you want to include all documents in a single email and have
the user be redirected to the email page (where they can edit the email body)
when they click the email button. */
/*String sdocIds = '';
for (SDJobWrapper sdjw : sdocJobWrappers) {
sdocIds += sdjw.job.SDOC__SDoc1__r.Id + ',';
}
sdocIds = sdocIds.substring(0, sdocIds.length() - 1); // remove last comma
emailPage.getParameters().put('SDId', sdocIds);
return emailPage;*/
}
return null;
}
private String combineAllType = ApexPages.currentPage().getParameters().get('combineAll');
private String combinedDocUrl;
public void combineIntoSingleDocument() {
if (combineAllType == null) return;
throwExceptionIfErrors();
combineAllType = combineAllType.toLowerCase();
List<String> sdocIds = new List<String>();
for (SDJobWrapper sdjw : sdocJobWrappers) sdocIds.add(sdjw.job.SDOC__SDoc1__r.Id);
if (Test.isRunningTest()) sdocIds.add(ApexPages.currentPage().getParameters().get('testSDocId'));
String filters = 'WHERE OwnerId=\'' + UserInfo.getUserId() + '\' AND Id IN (\'' + String.join(sdocIds, '\',\'') + '\')';
List<String> orderBys = new List<String>();
if (objSortValExistsOnSDoc()) orderBys.add(' SDOC__ObjSortVal__c ' + objSortFieldOrderbyDirection + ' ');
String sdocSortFields = ApexPages.currentPage().getParameters().get('sdocSortFields');
if (sdocSortFields != null) orderBys.add(sdocSortFields);
if (!orderBys.isEmpty()) filters += ' ORDER BY ' + String.join(orderBys, ',');
if (!Test.isRunningTest()) combinedDocUrl = new List<String>( SDOC.SDJobTemplateController.combineSDocs(filters, 'PDF') )[0];
}
public void finishCombineAll() {
if (combineAllType == 'file' || combineAllType == 'attachment') {
String filename; Blob filebody;
if (Test.isRunningTest()) {
filename = 'test.txt';
filebody = Blob.valueOf('test');
} else {
filename = sdocJobWrappers[0].job.SDOC__SDoc1__r.SDOC__Attachment_Name__c;
filebody = new PageReference(combinedDocUrl).getContent();
}
// &combineall=true,file,attachment&autoRedirect=record
if (combineAllType == 'file') {
insert new ContentVersion(
Title=filename,
PathOnClient=filename,
VersionData=filebody,
FirstPublishLocationId=parentId
);
} else if (combineAllType == 'attachment') {
insert new Attachment(
Name=filename,
Body=filebody,
ParentId=parentId
);
}
}
}
private Boolean doFinishRedirect = false;
public void redirectIfComplete() {
if (!jobsAreCompleted) return;
combineIntoSingleDocument();
doFinishRedirect = true;
}
public PageReference finishRedirect() {
if (!doFinishRedirect) return null;
// PageReference.getContent() must be done in a separate transaction,
// hence splitting up redirectIfComplete and finishRedirect
finishCombineAll();
String autoRedirect = ApexPages.currentPage().getParameters().get('autoRedirect');
if (autoRedirect == null) return null;
throwExceptionIfErrors();
autoRedirect = autoRedirect.toLowerCase();
if (autoRedirect == 'record') return returnToParentRecord();
else if (autoRedirect == 'combineall') return new PageReference(combinedDocUrl);
else if (autoRedirect == 'email') return emailDocuments();
else if (autoRedirect == 'email,record') { emailDocuments(); return returnToParentRecord(); }
return null;
}
public Boolean objSortValExistsOnSDoc() {
return Schema.getGlobalDescribe().get('SDOC__SDoc__c').getDescribe().fields.getMap().get('SDOC__ObjSortVal__c') != null;
}
public void throwExceptionIfErrors() {
if (getErrorSize() > 0) throw new SDException('Error: one or more S-Docs Jobs failed');
}
public class SDException extends Exception {}
}[/code]

Step 2: Create Visualforce Page

Head over to Setup > Build > Develop > Visualforce Pages > New and copy/paste the following code into your new Visualforce Page. Name the page SDRelatedListDocuments (i.e. enter this value into both the "Label" and "Name" fields), then click Save.
[code lang="html"]<apex:page controller="SDRelatedListDocumentsController" action="{!createSDocJobs}" tabStyle="SDOC__SDTemplate__c" lightningStylesheets="true">
<apex:form >
<apex:sectionHeader title="Create S-Docs" subtitle="Generating Document(s)"/>
&lt;&lt; <apex:commandLink action="{!returnToParentRecord}">Return to record</apex:commandLink>
<br />
<br />
<apex:actionPoller action="{!redirectIfComplete}" interval="5" reRender="job_table" oncomplete="finishRedirect();" />
<apex:actionFunction action="{!finishRedirect}" name="finishRedirect" reRender="job_table" />
<div style="width: 700px;">
<apex:pageBlock id="job_table" >
<script type="text/javascript">
function displaySuccessfulEmailMsg() {
document.getElementById('email_msg').innerHtml
= "Successfully emailed documents.";
}
</script>
<apex:commandButton value="Email Documents" action="{!emailDocuments}"
disabled="{!NOT(jobsAreCompleted) || emailedDocuments}"
oncomplete="alert('Successfully emailed documents.');"
rendered="{!allowEmail}" reRender="" />
<apex:pageBlockTable value="{!sdocJobWrappers}" var="ow">
<apex:column headerValue="Name">
<a href="/{!ow['obj.Id']}" target="_blank">{!ow['obj.Name']}</a>
</apex:column>
<apex:column headerValue="Status" value="{!ow['job.SDOC__Status_Link__c']}"
style="width: 150px;" />
</apex:pageBlockTable>
</apex:pageBlock>
</div>
</apex:form>
</apex:page>[/code]

Step 3: Create Record Detail Button(s)

For each object that requires this functionality, you'll need to create a button similar to the following example created for emailing a document to each Contact Role related to an Opportunity.
[code lang="html"]{!URLFOR('/apex/SDRelatedListDocuments', null,
[
parentId=Opportunity.Id,
childObjName='OpportunityContactRole',
lookupFieldName='Opportunity',
doclist='a0K1M000000C7XO',
allowEmail='1',
aid='a0B1O000000TGNB',
did='a0V2L000000LJAH',
combineALL='file',
autoRedirect='record',
sdocSortFields='SDOC__SDTemplate__R.Name',
objSortFields='Contact.LastName'
]
)}[/code]
Here's what each query parameter denotes:
parentId: The ID of the record that users will see this button on. For example, if your users will click a button on the Opportunity record detail page that creates and emails a document for each Contact Role, this value should be {!Opportunity.Id}.
childObjName: The API name of the object type of the records in the related list. For example, if your users will click a button on the Opportunity record detail page that creates and emails a document for each Contact Role, this value should be OpportunityContactRole.
lookupFieldName: The API name of the field relating the related list object to the parent object that the user will see this button on. For example, if your users will click a button on the Opportunity record detail page that creates and emails a document for each Contact Role, this value should be Opportunity because a Contact Role record is related to its parent Opportunity record via a lookup field with API name Opportunity (e.g. if you wanted to query the IDs of all the Opportunities related to some Opportunity Contact Role with ID aXM1F000000N7XL, you would run the query SELECT Opportunity.Id FROM OpportunityContactRole WHERE Id='aXM1F000000N7XL' - notice how the Opportunity ID is accessed from the Opportunity Contact Role record through a lookup field with API name "Opportunity").
doclist: A comma-delimited list of S-Docs Template names or IDs that will be used to generate the related list documents. These S-Docs Template records should have the Related To Type set to the object of the related list records, rather than the object of the parent records. For example, if your users will click a button on the Account record detail page that creates a document for each Opportunity, this should be Opportunity, rather than Account. Going back to our Opportunity Contact Roles case is a bit more interesting: if your users will click a button on the Opportunity record detail page that creates and emails a document for each Contact Role, this shouldn't be Opportunity, of course, but it also shouldn't be OpportunityContactRole as you might have expected; rather, it should be Contact, since OpportunityContactRole is really just a relationship record linking a Contact (where the real meat of the Opportunity Contact Role data lies) to an Opportunity.
allowEmail (optional): Set this to 1 if you want to allow the user to email the generated documents. Set this to 0 or omit it altogether if you don't want to allow the user to email the generated documents.
aid (optional): A comma-delimited list of the Salesforce Attachments that you would like to attach to each email (note that emails can only be sent out if you set allowEmail to 1).
did (optional): A comma-delimited list of the Salesforce Documents that you would like to attach to each email (note that emails can only be sent out if you set allowEmail to 1).
sdocSortFields (optional): Field (or fields) on the S-Doc or S-Docs Template object to sort the documents by. In the example above, this sorts by template name.
objSortFields (optional): Field (or fields) on the base object to sort the documents by. In the example above, this sorts by Contact Last Name.
combineAll=[true|file|attachment] (optional): If this is set to true, all documents will be combined into a single PDF that can be saved as either a file or attachment.

autoRedirect=[record|combineall|email|email,record] (optional): This parameter will automatically redirect you depending on which of the four values you input. Record will redirect you back to the record you started on. Combineall will take you to the combined PDF document if you've set the comebineall parameter to true. Email will take you to the email page so you can edit the email fields before sending your documents. Email,record will automatically email the documents and redirect you back to the record you started on.

Step 4: Create Test Class

Head over to Setup > Build > Develop > Apex Classes > New and copy/paste the following code into your new Apex class, then click Save.
[code lang="html"]@isTest
private class SDRelatedListDocumentsTest {
@isTest
private static void testSDRelatedListDocuments() {
Account acct = new Account(Name='test');
insert acct;
Opportunity opp = new Opportunity(Name='test', AccountId=acct.Id, StageName='Closed', CloseDate=Date.today());
insert opp;

Test.setCurrentPage(Page.SDRelatedListDocuments);
ApexPages.currentPage().getParameters().put('parentId', String.valueOf(acct.Id));
ApexPages.currentPage().getParameters().put('childObjName', 'Opportunity');
ApexPages.currentPage().getParameters().put('lookupFieldName', 'Account');
ApexPages.currentPage().getParameters().put('doclist', '');
ApexPages.currentPage().getParameters().put('sendEmail', '0');
ApexPages.currentPage().getParameters().put('combineAll', 'file');

SDRelatedListDocumentsController sdrldc = new SDRelatedListDocumentsController();
sdrldc.createSDocJobs();
Boolean tmp = sdrldc.jobsAreCompleted;
sdrldc.returnToParentRecord();
sdrldc.emailDocuments();
sdrldc.combineIntoSingleDocument();
sdrldc.finishCombineAll();
sdrldc.redirectIfComplete();
sdrldc.finishRedirect();
}
}[/code]

Return Distinct Records With LineItemsSOQL

Say you have a LineItemsSOQL table with a query on the Opportunity object that returns a few fields from its parent Account in your template:
[code lang="html"]<!--{{!
<lineitemsSOQL>
<class>table123</class>
<soql>
SELECT Account.Name, Account.Industry, Account.Type
FROM Opportunity
</soql>
<column>Account.Name</column>
<column>Account.Industry</column>
<column>Account.Type</column>
</lineitemsSOQL>
}}-->[/code]
This is fine if you don't mind the fields from a particular Account showing up in several of your table rows (e.g. your query returns 3 Opportunities that are all linked to the same Account). However, what if your use case required that you only display the fields for each particular Account just once in your table, even if your query returns multiple Opportunities linked to that Account? To accomplish this, you would change your LineItemsSOQL code to the following:
[code lang="html"]<!--{{!
<lineitemsSOQL>
<class>table123</class>
<soql>
SELECT Count_DISTINCT(ID) cid, Account.Name, Account.Industry, Account.Type
FROM Opportunity
GROUP BY Account.Name, Account.Industry, Account.Type
</soql>
<column>Name</column>
<column>Industry</column>
<column>Type</column>
</lineitemsSOQL>
}}-->[/code]

Return Distinct Records With The Named Query Feature

This behavior is also supported with the named query feature. Typically when you query a field through a lookup field (e.g. Contact__r.Name) with the named query feature, you'd prepend the name of the field with the name of the lookup object (e.g. {{!myQuery.Contact__r.Name}}). However, when using named queries with an aggregate function (such as COUNT_DISTINCT), you should omit the name of the lookup object (e.g. use {{!myQuery.Name}} rather than {{!myQuery.Contact__r.Name}} to reference Contact__r.Name) for the same reason listed in (3). For example:
[code lang="html"]<!--{{!
<lineitemsSOQL>
<class>none</class>
<queryname>myDistinctQuery</queryname>
<soql>
SELECT Count_DISTINCT(ID) cid, Account.Name, Account.Industry, Account.Type
FROM Opportunity
GROUP BY Account.Name, Account.Industry, Account.Type
LIMIT 1
</soql>
</lineitemsSOQL>
}}-->

{{!myDistinctQuery.cid}} <br />
{{!myDistinctQuery.Name}} <br />
{{!myDistinctQuery.Type}} <br />[/code]

Return Distinct Records Per Field Value

If you would like your LineItemsSOQL statement to only return one record per field value, you can do so using <distinct> tags.

For example, let's say the following Product records are related to an Opportunity:

Note that GenWatt Diesel 1000kW appears twice. Adding <distinct>productcode</distinct> to your LineItemsSOQL statement will return this record only once, since the product code is the same. In other words, this related list statement:
[code lang="html"]<style type="text/css">table { border: collapse; }
table, tr, td, th { border: 1px solid black; }
th { font-weight: bold; }
</style>
<strong>Unique Products From This Opportunity</strong>
<table cellpadding="4" cellspacing="0">
<thead>
<tr>
<th>Name</th>
<th>Quantity</th>
<th>List Price</th>
<th>Total Price</th>
<th>Product Code</th>
</tr>
</thead>
<tbody><!--{{!
<LineItemsSOQL>
<class>table151</class>
<listname>opportunitylineitem</listname>
<soql>
SELECT name, quantity, listprice, totalprice, productcode
FROM opportunitylineitem
WHERE opportunityid='{{!Opportunity.id}}'
</soql>
<distinct>productcode</distinct>
<column>name</column>
<column>quantity</column>
<column>listprice</column>
<column>totalprice</column>
<column>productcode</column>
</LineItemsSOQL>
}}-->
</tbody>
</table>[/code]
Would output the following table:

You can also use the sum attribute in your <distinct> tags to sum specified columns in records that are considered duplicates based on your <distinct> field, and roll the results up in each column. For example, you could modify the <distinct> tags from the example above like so:
[code lang="html"]<distinct sum="quantity,listprice,totalprice">productcode</distinct>[/code]
This would output the following table, with the quantity, list price, and total price of the duplicate product summed.

The Named Query Feature: Assigning SOQL Queries To Merge Fields

In S-Docs, related lists and direct SOQL lists have a massive amount of flexibility in how they are displayed when you leverage advanced template features, such as using HTML table markup in your related list's prefix and postfix attributes. However, there are rare occasions where this flexibility just might not cut it, as well as times where you might just want to use our direct SOQL feature to query fields from just a single object, and then use these fields over and over again in your template. Simply copying and pasting your direct SOQL code over and over is a messy, difficult-to-maintain solution that might even cause performance issues. However, there's no need to distress in times like these, because the S-Docs named query feature's got your back:

[code lang="html" highlight="25,30,35,39"]<!--{{!<LineItemsSOQL>
<class>none</class>
<queryname>myQuery1</queryname>
<soql>
SELECT quantity, listprice, totalprice, productcode
FROM opportunitylineitem
WHERE opportunity.id='{{!opportunity.id}}'
AND description='A Unique Description'
LIMIT 1
</soql>
</LineItemsSOQL>}}-->

<!--{{!<LineItemsSOQL>
<class>none</class>
<queryname>myQuery2</queryname>
<soql>
SELECT quantity, listprice, totalprice, productcode
FROM opportunitylineitem
WHERE opportunity.id='{{!opportunity.id}}'
AND description='Another Unique Description'
LIMIT 1
</soql>
</LineItemsSOQL>}}-->

Data for opportunity line item with description "A Unique Description":
Quantity - {{!myQuery1.quantity}}
List Price - ${{!myQuery1.listprice #,###.##}}}
Total Price - ${{!myQuery1.totalprice #,###.##}}}

Data for opportunity line item with description "Another Unique Description":
Quantity - {{!myQuery2.quantity}}
List Price - ${{!myQuery2.listprice #,###.##}}
Total Price - ${{!myQuery2.totalprice #,###.##}}}

Product codes of products ordered:
{{!myQuery1.productcode}}
{{!myQuery2.productcode}}

And let's just put the quantities and product codes here again, just because we can:
{{!myQuery1.quantity}} | {{!myQuery1.productcode}}
{{!myQuery2.quantity}} | {{!myQuery2.productcode}}[/code]
If you were to use the above code as your template source, then when you generated an S-Doc, the result would look something like the following:

Data for opportunity line item with description "A Unique Description": Quantity - 100 List Price - $20.00 Total Price - $2,000.00 Data for opportunity line item with description "Another Unique Description": Quantity - 300 List Price - $40 Total Price - $12,000.00 Product codes of products ordered: GC1050 GC1140 And let's just put the quantities and product codes here again, just because we can: 100 | GC1050 300 | GC1140

Notice how the LineItemsSOQL statements themselves don't display any results like you'd normally expect; when S-Docs sees that you used the named query feature in a LineItemsSOQL statement, it knows to hide the data that would normally be there, and instead opens the door to reference the data elsewhere as merge fields in your document.

On a technical note, we know in advance that each item we've queried in this example will only return a single result - you can assume that in our imaginary database, we only have one opportunity line item with description "A Unique Description" and only one opportunity line item with description "Another Unique Description."

You can additionally create named queries that return multiple records. You can filter them and access different records like so: {{!myQuery.Name filter="1" offset="2"}}. This would return the third record in the list that matches the criteria defined in filter 1.

[code lang="html"]<!--{{!<LineItemsSOQL>
<class>none</class>
<queryname>myQuery</queryname>
<filter id="1">StageName='Closed' AND Name LIKE '%Test%'</filter>
<filter id="2">StageName!='Closed' AND (NOT Name LIKE '%Test%')</filter>
<soql>SELECT Name, StageName FROM Opportunity</soql>
</LineItemsSOQL>}}-->{{!myQuery.Name}}<br />
{{!myQuery.Name filter="1" offset="1"}}<br />
{{!myQuery.Name filter="2" offset="2"}}<br />
{{!myQuery.Name filter="1" offset="3"}}<br />[/code]
Note that the filters use SOQL filter syntax, not S-Docs RENDER syntax. Each filter is added to the base query you defined between the <soql> tags, and one query is run per filter. For example, two queries will be run in the above sample since two <filter>'s are defined.

Aggregate Queries

The named query feature also supports aggregate queries, such as COUNT and SUM. To reference an aggregate function result in a merge field, you would simply use the field alias corresponding to that aggregate function result. For example:

[code lang="html"]<!--{{!
<lineitemsSOQL>
<class>none</class>
<queryname>numAccounts</queryname>
<soql>SELECT COUNT(id) cid, SUM(Amount)asum FROM Opportunity</soql>
</lineitemsSOQL>
}}-->

This org has {{!numAccounts.cid}} Opportunities with a total Amount of ${{!numAccounts.asum #,###.##}}.[/code]
By now, you've probably noticed that what's great about this feature is that you only have to run one query per child record to be able to use a given child record's fields like you would any ordinary merge field; the fields support attributes like format-number, and the fields can be used over and over again wherever you'd like in the document.