Summary

This article talks about Agile Documents Conditional Content functionality and builds on what we learned in Word Basics - Start Here, Word Basics - Templates and Word Basics - Find and Insert. That is why this article starts with Example 11. If you are completely new to Agile Documents, you should start with Example 1. After that, you can generally skip around as needed.

Conditional Content is a way to create different versions of the same document. For instance, consider two documents that are essentially the same, but one has gray-scale figures as it is printed and another with full-color figures that is designated as a web downloadable version. You can create one Agile Document that has conditional logic to output gray-scale figures or full-color figures. Of course, the Conditional Content construct can be expanded beyond this gray-scale and full-color figures example.

Please note that the examples described here are easily installed onto your SharePoint site. That installation procedure is described in Installing Examples.

Example 11: Introduction to Conditional Content

As you might imagine, tenants at a mall have pretty similarly worded leases. Of course, the terms of those leases could vary greatly, but generally, the lease of all the tenants look very similar. From the property managers' perspective, they don't want to reinvent the proverbial wheel everytime they have to lease to a new tenant. Generally, the property managers have a generic lease that they add and/or subtract key points to on a lease by lease basis. In our case, we start with the lowest common lease agreement and then conditionally add content to it. Because this is an example, we want to simplify this as much as possible.

We created a template shown in Figure 1. The Agile Document conditionally includes certain paragraphs that specify the allowable use for the mall space being rented. Those three paragraphs correspond to Clothing, Electronics and Food are shown in Figure 2, 3 and 4 respectively.

Just like the previous examples, ensure that the folder Word/EX11 exists within your document library. Then create a new Agile Document through SharePoint Explorer. Go back into SharePoint and rename it EX11.AgileDocument.xml. Copy the Word files shown above (Figures 2, 3 and 4) to the EX11 folder. Edit the Agile Document so that it looks like Figure 5, 6 and 7. Note the Conditional Content Keys listed in each of those figures. Also, ensure you've specified a DOCX output for the Agile Document. Save, build and then review Figure 8.

So, we did this extra work to add conditional content keys to the various extra paragraphs and it didn't affect the output? Yes, that is correct. Conditional content keys are compared between an item (content and/or insertion point) and its parent Agile Document. Since no conditional content keys were placed on the Agile Document, the default behavior is to include everything. Therefore, the output shown in Figure 8 includes all the content in the Agile Document.

However, if an Agile Document has its conditional content keys specified, then only content or insertion points with matching conditional content keys are included. Modify the conditional content keys for the Agile Document as shown in Figure 9. Save, build and then review Figure 10.

Now, that's more like it! This caused only the clothing paragraph to be included in the lease agreement and thereby excluding the electronics and restaurant paragraphs.

Lets close this example with some important notes about conditional content.

1. Conditional content keys are specified as comma separated lists.
2. Conditional content keys of the parent Agile Document are compared to conditional content keys of insertion points and content.
3. If either the conditional content keys of the parent Agile Document or insertion point is blank, the insertion point is processed.
4. If either the conditional content keys of the parent Agile Document or content is blank, the content is inserted.
5. If one of the conditional content keys [in the comma separated list] of the parent Agile Document matches one of the conditional content keys for the insertion point, the insertion point is processed.
6. If one of the conditional content keys [in the comma separated list] of the parent Agile Document matches one of the conditional content keys for the content, the content is inserted.
7. If none of the conditional content keys [in the comma separated list] of the parent Agile Document matches one of the conditional content keys for the insertion point, the insertion point is skipped. No content will be inserted into that insertion point.
8. If none of the conditional content keys [in the comma separated list] of the parent Agile Document matches one of the conditional content keys for the content, the content will be excluded (not inserted).

Example 12: Find and Insert Impacting Conditional Content

This example showcases how a find and insert item can impact the conditional content keys. If you recall, Find and Insert injects data from a SharePoint list item, Adobe Acrobat file or Excel spreadsheet into an Agile Document. In this particular case we will use a SharePoint list item to represent a particular tenant. That list item will inject customized data into the lease agreement shown in Example 11 and is reminiscent of the concepts illustrated in Example 7. In addition to populating Word Mail Merge fields from the list item, it will also inject conditional content keys into the parent Agile Document. This will then control whether clothing, electronics or restaurant provisions are conditionally included into the lease.

Let's revist/reuse our work from Example 11. However, this time, lets add a list item to populate the conditional content keys for the Agile Document. We will erase any conditional content keys we specified for the parent Agile Document, but keep the conditional content keys for the clothing, electronics and restaurant provisions.

Our SharePoint list definition and list item are shown in Figures 11 and 12 respectively. In Figure 11, you see we have three different field (column) names that correspond to the conditional content keys placed on our three content item. You could use any column type you wish as long as it can hold a value True, Yes or On. Specifically, if the list item has been configured to add to the parent Agile Document's conditional content keys, only column names whose value is True, Yes or On will be added to the conditional content keys list. As detailed in Figure 12, Clothing and Electronics are set to Yes and True respectively whereas Restaurant was set to No. Therefore, only Clothing and Electronics will be added to the conditional content keys list.

Ensure that the folder Word/EX12 exists within your document library. Then create a new Agile Document through SharePoint Explorer. Go back into SharePoint and rename it EX12.AgileDocument.xml. Copy the Word files shown above (Figures 2, 3 and 4) to the EX12 folder. Edit the Agile Document so that it looks like Figure 5, 6 and 7. Note the Conditional Content Keys listed in each of those figures. Create the SharePoint list and list item specified in Figures 11 and 12. Your Agile Document should look like the one shown in Figure 13. Note that Add to Condtional Content is selected for the SharePoint list item. Also, ensure you've specified a DOCX output for the Agile Document. Save, build and then review Figure 14.

As you see in Figure 14, the clothing and electronics provisions are added to the built document. This is expected.

Keep in mind that there may be hidden elements of a SharePoint list that are added to your SharePoint list. This is especially the case if your administrator has created a custom list template. In the general list template created by Microsoft, you can expect to see _iscurrentversion (a hidden column in the list) as a true value, and if you have configured your list item to add to conditional content items you should expect that to be added. Remember, as discussed in Example 11, if there is at least one conditional content key specified for the parent Agile Document, any content items that have a set of keys that don't match the parent Agile Document will not be inserted into the document. Thus, if you are expecting you list item to inject no conditional content keys because you've set eveything to false, be aware it probably will add at least _istcurrentversion.