Introduction
If your S-Docs template needs to render different contents based on different conditions, render statements can satisfy a majority of your conditional logic requirements.
However, S-Docs also supports using switch statements to replace repeating render statements that conditionally output contents based on a single field's value. Instead of writing multiple render statements to check each possible field value, you can simply create a switch map and reference it in a switch statement to do the work for you. Switch statements can greatly simplify the logic within your template into just a few lines. Let's take a look at how they work.
Example Use Case
To better understand how switch statements work, we will begin with an example.
Let's say we have an internal Opportunity summary template that needs to include different instructions based on the value of the Opportunity's Stage field. Since there are 10 standard values for this field, we could write 10 render statements that each output different instructions for each possible field value.
However, we could also use the switch feature to simplify this logic. We will set this up now.
Create The Switch Map
To use switch statements in your S-Docs templates, you need to first create a separate switch map template. The switch map template will contain switch keys and switch values that will be referenced by the switch statement in your main template.
Add JSON as a Template Format Value
Switch map templates need to use the JSON template format, which isn't enabled for S-Docs templates by default. You will need to add it as a Template Format value on the SDoc Template object. From the Setup menu, navigate to the Object Manager and find the SDoc Template object.
Next, navigate to the Fields and Relationships tab, and click on the Template Format field.
Scroll down to the Values section and click New.
Type "JSON" into the text field, then click Save.
Create the Switch Map Template
To create your switch map template, create a new template and set the Template Format field to JSON.
Navigate to the template editor to write your switch map. The basic syntax for switch maps is as follows:
{
"SwitchKey1" : "SwitchValue1",
"SwitchKey2" : "SwitchValue2",
"SwitchKey3" : "SwitchValue3"
}
Let's take a look at a switch map in the context of our example use case.
In this scenario, [1] the Stage field values for the Opportunity object represent the switch keys. [2] The custom instructions for each field value represent the switch values; these are the conditionally rendered contents that will appear in our Opportunity summary based on the value of the Stage field. The entire map needs to be enclosed in curly braces.
Write The Switch Statement
Now that the switch map is created, navigate to your main template to write the switch statement. The basic syntax for switch statements is as follows:
<!--{{!
<switch>
<switchMap>Switch Map Template Name</switchMap>
<formula>{{!Object.Field}} == '{{!SWITCH_KEY}}'</formula>
<outputForEachMatch>{{!SWITCH_VALUE}}</outputForEachMatch>
</switch>
}}-->
Let's take a look at the switch statement in the context of our example use case.
[1] Switch statements are opened like related list LineItems or LineItemsSOQL statements, followed by the <switch> tag.
[2] The name of the switch map template is enclosed in <switchMap> tags. This line must include the exact same name that's listed in the Template Name field for your switch map template, with no extra characters or spaces.
[3] The render conditions are enclosed in <formula> tags. The example above will check the switch map for the switch key that matches the Stage field of the opportunity that this template is generated from. This accepts the same syntax as the S-Docs Conditional Logic feature. Although we use "equals" in this example, you can use any of the operators accepted by S-Docs Render statements.
[4] The conditionally rendered contents are enclosed in <outputForEachMatch> tags. The example above uses the {{!SWITCH_VALUE}} merge field, which means it will render the switch value that matches the switch key (e.g. the custom instructions that match the Opportunity Stage field). You can also include static text within these tags.
[5] Switch statements are closed with the closing switch tag, followed by the syntax used for closing related list LineItems and LineItemsSOQL statements.
Let's See it in Action!
Now that we've seen how to create a switch map and write a switch statement, let's go back to our example use case and see the switch feature in action. Since we want to create an Opportunity summary template that includes different instructions based on the Opportunity's Stage field, we insert the switch statement at the bottom of the Source of our Opportunity summary template.
We then navigate to an Opportunity record to generate the document. Take note of the Opportunity's Stage field.
When we generate the document, the correct custom instructions appear where we inserted the switch statement. The switch map has been superimposed for reference.
As you can see, the Switch feature greatly simplified our template logic into just 7 lines of code.
Use Template Components in Switch Statements
The Switch feature also supports using template components as switch values (dynamically rendered contents). This can be useful if your switch values are very long, or require formatting that's not available in the JSON switch map template. There are only a few differences to consider when using components as switch values instead of static text.
In the switch map, input template component names into the switch value column instead of static text.
When you write the switch statement, simply enclose the {{!SWITCH_VALUE}} merge field within <template> tags.
<!--{{!
<switch>
<switchMap>Switch Map Template Name</switchMap>
<formula>{{!Object.field}} == '{{!SWITCH_KEY}}'</formula>
<outputForEachMatch><template>{{!SWITCH_VALUE}}</template></outputForEachMatch>
</switch>
}}-->
In the context of our example use case, a switch statement using the switch map above would look like this:
You can also include additional template tags to merge in other component templates as well.
Tags: Conditional Logic