This documentation applies to version 20 or higher.
Office content templates require additional license "Office output" that is not part of the Dynamo Online standard edition. Please contact dynamo.support@documill.com to get trial license.
Dynamo allows the use of files of all three primary Microsoft Office document formats - Word (DOCX), PowerPoint (PPTX) and Excel (XLSX) - as content templates alongside HTML templates. These templates can contain content commands, with each of the three document formats having its own set of commands, but no other kind of logic. No Flow, no element logic, only content commands. Unlike with Dynamo's legacy Office templates, creating an Office content template of this kind doesn't require an Office Add-in - all the content commands are defined through document components editable through the Office applications' own UI.
Content command containers
At its core, the way in which Office content commands are defined in the templates of different kinds is the same: type the commands and their attribute values into a text field. But what to write, and what is the text field? Let's start with the latter question, the answer to which varies between the three different document formats.
Content commands in Word documents: Content controls
The Word content commands of a template reside within the titles of content controls (standard Word feature). The title is one of a content control's properties and is basically a text field without any particular character or length limitations. Besides the title, a content control also has a tag - to mark the control as something with Word content commands in it, the tag should be "dynamo". Below is an example of the properties of a content control with Dynamo logic in it.
Content controls can be added through Word's developer tab. The developer tab is not visible by default but it can be made visible from options: File -> Options -> Customize Ribbon -> Main Tabs -> Developer.
Please note that the developer tab is available only in Word Windows desktop version. Other Word versions can display content controls but adding and editing them is not possible.
The example content control displayed above contains the Word content command out, and it is there to print out the value of the variable "opp.Name". When evaluated, it would place the value of that variable inside the content control. The content control defines the area in the document that a content command can affect - the only way these commands can affect any content outside the content controls is by modifying the space taken by the control's contents and changing the document's layout in this way. Once the content commands in a content control are evaluated, the content control is removed unless this is specifically prevented by one of the content commands.
Further reading
Content commands in PowerPoint presentations: Alt text
PowerPoint content commands appear in the Alt Text field, a feature of all shapes within the presentation. Any shape's Alt Text that starts with "dynamo " will be inspected by Dynamo when the content is evaluated - other Alt Text fields in the presentation will remain unaffected, so Dynamo will not harm any Alt Text doing its originally intended purpose of assisting blind people.
Alt Text can be defined for any shape by right-clicking the shape and selecting "Edit Alt Text..." from the menu, or alternatively by clicking Alt Text in the ribbon's Format tab when a shape is selected.
The example Alt text displayed above contains the PowerPoint content command out that is bringing the value of the variable "opp.Name" into the shape's text body. All the PowerPoint content commands only affect the shape whose Alt Text they're in, and since shapes cannot structurally - only visually - exist inside each other, that shape is always the only shape that is affected.
Content commands in Excel workbooks: Name comments
The content commands of Excel templates are written into the comments of defined Names. All Names have the fields Name and Comment - if the Name starts with "dyn_", then the contents of the Comment field are interpreted as content commands.
Names can be defined by either right-clicking the worksheet and selecting "Define Name..." or by clicking "Define Name" in the ribbon's Formulas tab. The Formulas tab also contains the Name Manager, which allows you to easily see and modify all the names in the workbook.
The Excel content commands can affect the cells within the Name's area ("Refers to"), but also other cells outside the area as content commands that add or remove content can cause surrounding content to be moved. Note that while there can be multiple Names referring to the same cells, the content commands do not accept this and therefore all "dyn_"-prefixed Names must not have overlapping areas.
Content command syntax
Whether the container for content commands is a content control, a shape or a defined name, the way in which the commands for the container are set is the same. The commands are typed into a text field using a specific syntax that must be followed precisely in order for Dynamo to understand it. The syntax is of this format is as follows:
commandName(attributeValue1,attributeValue2,...)The "commandName" is the name of the command, such as "out", "table" or "if". Within the parenthesis following the name are the attribute values for this command, separated with commas. These attribute values are typically EL-expressions like with other commands, but similar to the notation in HTML Logic, the ${ and } are not required to wrap the expressions. So "opp.Name" for example is equivalent to "${opp.Name}". Using the brackets is not an error though, and may also be needed if you'd like to combine a variable with static text in the expression, like "Opportunity name: ${opp.Name}".
As this syntax doesn't define attribute names anywhere, the system will assign the values to different attributes based on their order. For example, the Word content command repeat requires at least two attributes to be defined, value and var, the first and second attributes. So repeat(products,product) would set "products" as the value for value, and "product" as the value for var. The documentation of each Word, PowerPoint and Excel content command specifies the order of the attributes.
Any attributes that you wish to leave undefined may be simply left out - the aforementioned repeat for instance has third and fourth attributes as well, but they are optional and their values and the separating commas may therefore be left out. However, if you wish to define an optional attribute but not define the optional attribute before it, the separating commas are required as Dynamo uses the commas to calculate which attributes the values belong to. For example, the Word content command out command has color as its fourth attribute. Setting a value for this attribute while ignoring the second and third attributes format and parser would look like this out(product.name,,,'RED'). The commas are needed, but the actual value expressions for undefined attributes can be left out entirely.
A single text field may also contain more than one content command. If doing this, the commands only a need a space between them. Like this:
if(showName) out(name) Any amount of commands can be placed into a single content control/shape/name like this, but only one of a particular kind of command. Some commands will also clash, such as the Word commands table and reportTable, which both are doing a very similar task and therefore won't do much good together.
Inline EL-expressions
All of the Office templates can contain inline EL expressions, which are EL-expressions written directly into the document content. These are evaluated along with the content commands and are replaced with the text representations of their resolved values. For example, putting "Hello ${UserInfo.FullName}" into any paragraph, text area, cell or some other document element into which text can be typed in would cause something like "Hello Dynamo User" to appear in its stead when the template is evaluated.
Inline EL expressions do pretty much the same thing as the out content commands, but the out commands provide more control over the output, such as allowing a specific Format to be used. The output of inline EL expressions is formatted as well, but always using the default Format for the value type. If the resolved value of the expression is undefined (null), the expression is replaced with nothing, so the previous example expression would resolve into just "Hello " in that case.
Use of inline EL expressions is very much required in certain cases with PowerPoint and Excel templates, as they cannot have content commands within other content commands like Word templates. For example, if using the Excel content command repeat, inline EL is required to produce output into the repeated area.