October 4, 2010

Script Feature - XpressDox

The «Script()» command enables the template author to give  a name to a chunk of text, and to use that chunk repeatedly in a template.

The chunk of text can consist of from a few words to one or more paragraphs.  This named chunk can then be inserted into the document at a number of places using the «UseScript()» command.

 

Text only

An example might be the set of commands which construct a person’s name with the correct number of spaces depending on whether the first name and middle initial are known or not:

«If(FirstName != ”)»«FirstName» «If(Initial != ”)»«Initial» «End()»«End()»«Surname»

Those few commands will insert the Surname, preceded by FirstName and Initial, each followed by a space, but the spaces are only inserted if the FirstName and Initial have a non-empty value.  That way around, when the FirstName and/or Initial are unknown (i.e. empty), you don’t end up having extra spaces in front of Surname.

This sequence of commands is likely to be needed in a number of places in the template.  This could be achieved by copy-and-paste.  But then, if there’s a mistake, or a need to change for some other reason, then all the places where the text was copied to will need to change.  The «Script()» command helps here, because when a change is needed, it is only be necessary to change the Script, and all the places where the script is used will automatically change.

Here’s how it would look:

«Script(PartyName)»«If(FirstName != '')»«FirstName» «If(Initial != '')»«Initial» «End()»«End()»«Surname»«ScriptEnd()»

The name of the party is «UseScript(PartyName)>».

«UseScript(PartyName)» is required to sign here: …

 

Paragraphs

Scripts can include one or more paragraphs.  When the script content is included into the template, the template author can specify whether the formatting of the original paragraph or that of the destination paragraph must be applied.  This is done in the second parameter of the «UseScript()» command.  This second parameter is exactly the same as the second parameter passed to «IncludeTemplate()» and «BaseTemplate()» commands, except that Source has no meaning in this context.
Here follows an example of a multi-paragraph script:

«Script(Parts)»
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.

Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci.
«ScriptEnd()»



1. Cras faucibus condimentum odio. Sed ac ligula. Aliquam at eros.
2. Etiam at ligula et tellus ullamcorper ultrices. In fermentum, lorem non cursus porttitor, diam urna accumsan lacus, sed interdum wisi nibh nec nisl. Ut tincidunt volutpat urna.
3. Mauris eleifend nulla eget mauris. Sed cursus quam id felis. Curabitur posuere quam vel nibh.
4. «UseScript(Parts,Paragraph)»

The formatting instruction Paragraph (second parameter of the «UseScript()» command) means that the paragraphs of the script content must be formatted according to the paragraph in which the «UseScript()» is coded. In this example, it means that the paragraphs of the script content must be numbered – i.e they will look like:

4. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
5. Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus.
6. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci.

 

Script with Parameters – Build Your Own Command

This feature was introduced with version 10.2.

It is best described by way of example: Suppose you have the need to add a number of days to a date and then get the last day in the month for the result. This would be something like:


«SetV(‘result1’,IncrementDate(DateOfContract,90,'D'))»
«Comment(The result of adding 90 days to the DateOfContract)»
«SetV(‘LastDay’,LastDayInMonth(GetV(‘result1’)))»
«GetV(‘LastDay’)»

Or, you could rewrite that in one fillpoint as:


«LastDayInMonth(IncrementDate(DateOfContract,90,'D'))»

But, if you need to do this operation in various places with different numbers of days and a different starting date, then a parameterized script would be the answer. It would look like this:


«Script(AddDaysAndGetLastDay,StartDate,NumberOfDays)»
«LastDayInMonth(IncrementDate(&StartDate&,&NumberOfDays&,'D'))»
«ScriptEnd()»

Then to invoke this script, achieving the same result as the above example, you would say «AddDaysAndGetLastDay(DateOfContract,90)»
In other words, the argument StartDate in the Script is replaced with the value passed to the script, i.e. “DateOfContract”, and the NumberOfDays is replaced with the value 90.
This same script could be used to add a different number of days to another date, such as:


«AddDaysAndGetLastDay(Today(),30)» 

 

Note the syntax – it looks like an XpressDox command, which is why we call this feature “Build your own command”.
The Script itself does not need to put its answer directly in the document, but could set a variable to the result and then the variable could be used elsewhere.

 

Look at this article for more examples of using parameterized scripts.