How to insert merge fields in the document.
ScopeStack templates are Word documents (.docx) with MailMerge Merge Fields added in key ways to perform operations.
To add a merge field, click the ‘Insert’ menu item, and then select ‘Field’ from the drop-down menu.
In ribbon-based Word navigation, you can find it in the text grouping of the Insert tab
A new dialog box will open like the one shown below. Select “Mail Merge” from the Categories list on the left side of the dialog box and then “MergeField” from the Field Name list on the right.
In our example, we want to insert the Price of a project into the SOW Frame. The end resulting merge tag looks like this once it has been placed in the document:
<<=price>>
MailMerge fields direct the platform on how to access and insert relevant information from the data objects available on ScopeStack. You can learn more about viewing a raw view of the merge data information.
Learn about the Merge Data View
There are two broad types of merge fields that ScopeStack can utilize in your document.
-
The first type of merge field is a key-pair value field. This type of field uses a "key" (in our example =price) to insert a value into a project in its place. The value that's inserted inherits the formatting of the key. A key-pair value field is easy to spot – its name begins with an equal sign =.
-
The second type of merge field that ScopeStack will use is called a flow-control field. As the name suggests, this type of merge field controls the flow of data being added to the customer document when it is built.
Flow control fields always come in groups of two or more. The first item in the group lets the merge process know that a flow control block is starting. The second one closes the group. This works like open and close tags in most modern programming languages.
The most basic flow control field is a conditional field. It performs a test with the key-pair value and then proceeds to add the text inside the block only if the test returns ‘true.’ Here’s an example of a ‘conditional’ flow control pair:
This pair of merge fields tests to see if the SOW price is present. The merge process will add whatever text is between the price:if(present) and price:endIf fields if the price exists and will skip the text if it does not exist. You can include almost anything you want between the flow control elements, including additional merge fields. A complete conditional flow control merge field block could look like this when it’s complete:
Another important type of flow control is the each control. This element allows you to insert items that have multiple parts and deal with each item individually. For example, if you have a task that has Prepare Phase language assembled as a list of sentences, each sentence can be added to the document one at a time using an ‘each’ flow control. It would look like this:
The ‘each’ block allows you to provide a name for the value that you want to work with by providing the name inside the parentheses (you are in essence creating a temporary variable to hold the data for that element of the whole while you do whatever is between the eaches).
In the example above, we call each item in "phases_with_tasks" a "phase" – "each(phase)" – and then move on to output attributes of the phase, in this case, the phase's name in the data object is itself called phase, hence "=phase.phase". The block above would list all available phases in the data object "phases_with_tasks".
You can additionally use conditional, and each flow controls together. For example, this block:
Here, we've added a conditional inside the each statement to test the key-pair value "has_tasks?". This value displays true if the phase has tasks in it in a particular project, and false if the phase doesn't have tasks. The rendered list in the Word document would then only list out the names of phases that have tasks in the project.
You can embed as many eaches and conditionals as necessary to create the desired flow in your document.
Did this answer your question?