Snippets
Last updated
Last updated
Snippets are ways of making writing new clauses more efficient and/or more readable. They are re-usable pieces of text that can either be used inside one clause (internal snippets) or as part of all clauses (external snippets).
Snippets work similar to variables in mathematics or programming languages. They are referenced by a name and represent a piece of text.
Internal snippets are pieces of text that can be used multiple times inside the same clause. They will not be available outside the clause where they are defined.
Internal snippets are defined at the bottom of a clause as follows: NAME-SNIPPET = content snippet. Insert the name by which you want to refer to the snippet in all caps, e.g. NAME-SNIPPET. Then, after the equals symbol (=), insert the text you want to be inserted in all places where the snippet is referenced.
Referring to an internal snippet (i.e. showing Clause9 where the snippet text should be placed) is done by taking the name of the snippet and adding an “at” symbol @. For example:
Will result in the following:
Snippets may contain all types of text, datafields or conditions. They can even refer to other (internal or external) snippets, making multi-tiered snippets possible.
Always leave at least one blank line between each definition of an internal snippet.
External snippets are similar to internal snippets. They are, however, defined and referenced differently.
Because an external snippet should be made available to all clauses inside your library, it should be defined outside a normal clause. It is defined by creating a normal clause which will be used as a kind of special purpose vehicle.
Naming an external snippet follows the same rules as the naming of a concept. The file name of the clause that will serve as an external snippet may, e.g., not contain any spaces as that would make referring to the external snippet impossible (see below). It is not necessary to use all caps when naming an external snippet.
Enter the text for your snippet as the clause’s content body.
While internal snippets are referenced by simply adding a @-prefix, external snippets are referenced differently. After the @, a hashtag has to be added as well: @#. For example: @#external-snippet.
Snippets can make writing clauses more efficient and consistent. Using snippets, you can easily create a piece of text that is used in many spots at once. This also saves time when that piece of text must be changed or updated: just change the snippet and all places where that snippet is referenced will automatically incorporate that change (which is much the same way a library clause functions).
A snippet can also make reading clause grammar more easy. For example, conditional text may become very complex if multiple conditions have to be evaluated at the same time. Long/complex grammar may make the structure of the clause grammar difficult to read. Replacing the most complex bits of grammar with snippets will improve readability.
This may not be obvious at first sight, but you can actually use snippets within snippets, any level deep. For example, you can write:
From a mental point of view, all these snippets facilitate easier reading, because you don’t have to nest conditions and curly braces, which becomes difficult to keep track of as from the second level deep.
Although you can go any level deep, you should be aware not to introduce circular references between snippets — e.g., snippet @A incorporating snippet @B, while snippet @B incorporates @C, and @C on its turn incorporates @A. This last part would cause an endless cycle that will cause an error.
The following grammar is rather difficult to read:
Using internal snippets, we can improve this grammar:
Alternatively, using external snippets, we would have the following three clauses:
A snippet called cps-seller:
And a snippet called cps-purchaser:
These final two external snippets can be used in other clauses as well by using the references @#cps-seller and @#cps-purchaser.
While most snippets will contain text, it is also possible to use snippets as containers for data-values and calculations. For example:
Instead of repeating the fairly complex interest-calculation all over the contract, you can store it in an (internal or external) snippet and reuse it.
Note: When storing a value or calculation in an external snippet, you should wrap it in curly braces { ... } to avoid that the contents of the snippet would be treated as clause text. (As explained in Mixing Data Types, clause text cannot be used to perform calculations.)
The underlying reason is that Clause9 will first to treat internal snippets as a calculation or condition. Only when that fails, it will treat the internal snippet as mere text. Accordingly, in an internal snippet, it is not necessary to wrap a value or calculation in curly braces.
The reverse is true for the main body of a clause, where Clause9 will treat contents as text, except when put between curly brackets.
Internal snippets cannot only store values and expressions, but also conditions. For example, instead of repeating the same logic over and over again:
…. you can store the condition in an internal snippet, and reuse it everywhere, thereby increasing readability and consistency:
It is not possible to use external snippets for storing conditions. If you want to reuse conditions across clauses, you can however use data-expressions.
Sometimes it is useful to switch between values in the middle of a calculation.
For example, assume that in a certain contract the price of the tomatoes that are sold, depends on the country, the weather and the volume:
price = base-price * country-factor * weather-factor * volume
If, for example, there are 4 possible countries (NL / FR / DE / UK) and 3 possible weather-conditions (dry / humid / stormy), you would end up with a huge number of if/then/else parts:
In such situations, it is much cleaner to use the following:
Note that you have to wrap the numbers within curly braces, otherwise they would be treated as text (see the Mixing Data Types page for an explanation), so that an error would be produced.
Another possibility is to use the @switch special function. However, when the amount of cases gets high, it is probably cleaner to split calculations in several parts, using the if/then/else constructs above.
For even greater reuse of text blocks, you can optionally use placeholders in (internal or external) snippets.
For legal experts who are first confronted with this idea, this will seem like a far-fetched idea. However, its usefulness should quickly become clear with the use of some examples.
Assume that you have a datafield #employee^gender that can either contain "female" or "male" as a value. In your paragraphs, you want to alternate between “Mr.” and “Mrs.”, depending on the gender. This is of course very easy:
Let’s make this a little bit more complex. Assume that you not only have #employee^gender, but also #manager^gender and #consultant^gender, and you also want to alternate between “Mr”. and “Mrs.” for these datafields:
This is still easy, but quickly becomes quite verbose, with a lot of repetition. The structure of the three conditions is actually identical, the only difference is the datafield that is being referenced.
To avoid this repetitiveness, you can use placeholders within a snippet:
As you know by now, the software will replace each reference to @MR-MRS, by the contents of the snippet. If you also specify one or more placeholders between parentheses, then the software will additionally replace each placeholder with the specified content.
For example, @MR-MRS(?GENDER := #employee^gender) will be converted into {#employee^gender = "female": Mrs. | else: Mr.}, because the ?GENDER placeholder within the snippet is being replaced with the value #employee^gender.
As a result, you can use the very same snippet for three different datafields, by having the software swap the placeholder.
You can also use multiple placeholders for snippets. For example, let’s also include the last name in the snippet:
In this short paragraph, this may not seem like a huge advantage. However, from a maintenance perspective — particularly when using external snippets — this is a significant improvement, because the way that a person’s title and name are being represented, can then be centrally organised. If ever you want to change the way persons are inserted in the documents (e.g., a new corporate policy would require to say “MR. SMITH” instead of “Mr. Smith”) then you only have to change one small piece of text, instead of having to “hunt” in many different files for potentially hundreds of instances.
To reduce the amount of text you have to insert, Clause9 allows you to omit ?PLACEHOLDER :=
The example above can thus be shortened to:
When no explicitly named placeholders are being used, Clause9 will assume that your placeholders are being named ?A, ?B, ?C, … corresponding to the first, second, third, … parameter in the invocation of the snippet.
When this short-hand method is being used, snippets look like invocations of special functions (such as @count and the many others). And that is exactly the idea — short pieces of “code” that allow you to avoid repetition. (Software developers call them “functions” or “methods”.)
