Special items
Last updated
Last updated
parameters: any amount, of any type (they will get ignored)
returns: nothing
see also: @void
This special function is similar to @void, in the sense that it does not return a visual result, but can be used as a placeholder in situations where the grammar technically requires you to include something.
The difference with @void is that @black-hole takes one or more arguments, and pretends it actually uses them (even though it actually ignores them). Accordingly, any datafield that you would pass as a parameter, will be flagged as being used, so will be shown in the , and (when accompanied by !) may invite the user to specify a value, even if that value will not be used at that point.
For example, in the screenshot below, you can see that the employee’s address gets requested at the beginning of the document (through the purple box) but not within the table. (See the ).
When some address is filled in, the result will be that the address is only visible within the table. Note that in both scenarios, the data dashboard would show the datafield as effectively being used.)
sole parameter: some other special-function call
returns: that sole parameter
Background: Clause9 deliberately does not "cache" the outcome of calculations, even when exactly the same calculation is being used in multiple clauses of the same document. There are many subtle reasons for this, the primary reason being that Clause9 must exhaustively keep track of all the instances where a certain term is being used (e.g., in order to create an exhaustive definition list and to allow the user to immediately see all the clauses where a certain term is used in the document).
From a performance perspective, usually this does not matter: even when a contract is 100 pages long, Clause9 can perform a full recalculation in less than a second.
There are isolated cases where the performance does become problematic, e.g. when Clause9 ingests a very long list of records (e.g., when interacting with Excel through the @excel special function, or when ingesting data from a database). In such situation, the circumstance that every — even indirect — invocation of a special function is needless calculated again, becomes prohibitive for real-time interactions with the document. In such situation, the @cache special function can bring relief.
For example, let's suppose that you are interacting with an Excel-file called "lawyers", with all of the almost 900 lawyers in the firm. With special-functions such as @filter and @count you can count subsets (e.g., which of the lawyers are associates); but this is a fairly slow function.
In the snippet below, you can see that the same lawyer-count is used several times. This will cause Clause9 to perform the same filtering & counting over and over again. This will slow down the document significantly.
When, instead, you would add the @cache function around the calculation, then this calculation will only be done once for each recalculation of the entire document, because the @cache special function effectively "stores" the result of the calculation, so that the next time it encounters the same calculation (whether in the same clause or elsewhere in the document), it can simply grab the result of the previous calculation.
Usually it's not necessary to think about the caching, as you would barely notice its performance impact in regular situations.
first parameter: either text, or an internal snippet
This function inserts a comment (balloon) in the DOCX/PDF output; it has no visible effect within the browser.
For example, @comment("Some random comment") would create a comment balloon that contains the plain text “Some random comment”.
When you require more rich content, you should create an internal snippet and refer to that snippet as the first parameter. For example:
will result in the following comment balloon inside MS Word:
Note that, when combined with various conditions, this function allows you to dynamically show/hide comments and alter the contents. This can have interesting use cases.
Also note that the output of this function is not affected by the document or Q&A’s settings related to the export of comments & notes. If you do not want the comment to be exported in certain circumstances, you should subject the function to a condition.
parameter: an email address (between quotes)
optional second parameter with visible text (if missing, the email address will be printed)
returns: a hyperlinked email address
see also: @link
For example @email("info@clausebase.com") returns a clickable link to an email address info@clausebase.com, while @email("info@clausebase.com", "please email us") returns a clickable link to the same email address, but visibly the text “please email us” will be shown.
parameters:
the name of the Excel sheet file in the library between parentheses, e.g. "pricing-sheet".
the cell or range of cells you want to use the values from, e.g. "D3" or "B1:B8".
the third parameter is (strictly speaking) optional: here you can refer (between parentheses!) to a cell or range of cells the value of which you want to change to some other value, e.g. "D4".
the fourth parameter is linked to the third parameter, i.e. it contains the value you want to input into the cell referenced in the third parameter. Using the cell "D4" referenced above, you could input e.g. the value in the datafield #loan^number-of-payments.
The fifth (and seventh, ninth, eleventh,...) parameter is again optional and can contain another reference to a cell or range of cells the value of which you want to replace.
The sixth (and eighth, tenth, twelfth,...) parameters again refer to the values you want the cells referenced in the preceding parameters replaced with.
returns either a single value or list of value, based on whether a single cell or range of cells was referenced in the second parameter
see also Excel calculations and lookups and @cache
parameter: something that resolves into text
returns that text with a highlighted background
see also: @placeholder
This special function is similar to the @placeholder special function, in that it highlights the text in its sole argument. However, there are two important differences:
@highlight will not insert any other characters (such as square brackets) that may get inserted according to the placeholders-styling (part of the References styling)
the color of the @highlight is only equal to the color of the placeholders-styling if you use @highlight. If, instead, you use @highlight-red, the background will always be in red, irrespective of the setting of the placeholders-styling. The same for @highlight-green and @highlight-yellow and @highlight-cyan, @highlight-blue, @highlight-pink and @highlight-grey.
parameters:
#reference to another document
true/false: insert as separate pages? If set to true, then the software will insert the content on a separate page (using section breaks in MS Word, and including any header/footer of the source document).
true/false: use the layout of the “host” document for the inserted document? If set to true, then all the layout settings of the host document will get copied into the inserted document.
true/false: use the concept-labels of the host document for the inserted document? If set to true, then all the conceptlabels of the host document will get copied into the inserted document, so that the terminology will be identical. If not set to true, then the conceptlabels stored in the inserted document will get used for that document.
true/false: use the datafields of the host document for the inserted document? If set to true, then all datafields of the host document will get copied into the inserted document. If not set to true, then only the datafields for which values are stored in the inserted document itself, will be filled in in the inserted document.
true/false: ensure that the inserted document has its own numbering, separate from the host document? If set to true, then the host document and the inserted document will have different numbering lists, so that the numbering will not clash
Inserts the specified document at this point.
see also @msword-pages, which also explains how the numbering separation works
This function will insert another document into the “host” document. The different parameters allow you to specify to which extent the two documents should be similar or independent.
Note that the output of this special function will only be visible in the downloaded DOCX/PDF file (not in the browser).
parameter: URL, and optionally an alternative presentation string
returns: a clickable hyperlink
see also: @email
Returns a clickable link to the specified URL. (If http:// of https:// is not added, http:// will be added automatically.)
For example, @link("www.clausebase.com") returns a clickable link to www.clausebase.com, while @link("www.clausebase.com", "ClauseBase website") returns a hyperlink to the same URL, but with the visible text being “ClauseBase website”.
parameter: a number between 1 and 5
returns a paragraph with the relative length indicated by its parameter
parameters: two or more snippets that contain tables
result: a new table in which the rows of the individual tables are glued together
As shown in the example below, the individual columns do not even have to be identical between the various sub-tables. For very complex tables, this function can therefore facilitate readability for the clause editor.
Another use case for this function, is to glue together repetitive rows that were created using the @for special function:
first parameter: a #file reference
other parameters: a list of snippets
inserts one or more pages or paragraphs from an external MS Word file into the document
See also @insert-document
parameters: a #filename pointing to some Q&A file, and a caption
returns a hyperlink
see also @link
Creates a hyperlink to an existing Q&A, with the caption set to the second parameter. When clicked, that Q&A will open (assuming the user has sufficient rights).
For example, when you would insert @open-qa(#license-agreement, "License Agreement"), the software will show a hyperlink entitled “License Agreement” (shown in blue, as a typical hyperlink). When clicked, that hyperlink will open the Q&A associated with #license-agreement.
You will most likely want to wrap this special-function within a @in-browser condition, as it only makes sense on screen (i.e., should not be shown in a DOCX or PDF file).
no parameters
inserts a page break at the location the special function is referenced
no parameters
inserts a special Word-field that contains the total number of pages in the entire Word-document
For example, @pagecount — no parameters or parentheses necessary — would return “15” if that happens to be the total number of pages.
Note that the @pagecount cannot be calculated in the browser (i.e., will only export in Word or PDF). Within MS Word, the number of pages is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)
no parameters
inserts a special Word-field that contains the current page number in the entire Word-document
For example, @pagenr — no parameters or parentheses necessary — would return “15” if that happens to be the current page.
parameter: some text
returns the specified text, preceded by the paragraph symbol (§) and a space
see also @paras
This special function allows you to easily refer to statutory articles / sections, circumventing the fact thatthe paragraph-symbol has special (cross-referencing) meaning in ClauseBase. For example, ... as stated in @para("12.3"), it is ... will be converted into ... as stated in § 12.3, it is ...
parameter: some text
returns the specified text, preceded by two paragraph symbols (§§) and a space
see also @para
This special function allows you to easily refer to statutory articles / sections, circumventing the fact thatthe paragraph-symbol has special (cross-referencing) meaning in ClauseBase. For example, ... as stated in @paras("12.3 - 12.6"), it is ... will be converted into ... as stated in §§ 12.3 - 12.6, it is ...
parameter: text (or some parameter that can be converted to text)
returns a placeholder with the specified text
see also: @highlight
The placeholder will be formatted in accordance with the placeholders-styling (part of the References styling).
Tip: if you only want the highlight, but none of the characters that may get inserted as per the References styling, then have a look at the @highlight function.
no parameters
For example, @reporting — no parameters or parentheses necessary — would return true if the document is currently shown in the reporting mode.
Tip: you can easily invert the behaviour of this special function: not(@reporting) will return true if the current mode is not the reporting mode.
parameter: the relative position (0 to 10) of the tab, as compared to
inserts a tab
see also @tab-u, @tab-d, @rtab, @rtab-u and @rtab-d
Inserts a tab at the specified position:
The r- versions insert a right-aligned tab (instead of the default left-aligned tab).
The -u versions insert a tab with preceding underscores.
The -d versions insert a tab with preceding dots.
For example, @rtab-u(5) inserts a right-aligned tab in the horizontal middle of the paragraph, preceded by dots.
Due to technical limitations, tabs cannot always be accurately shown within a browser. Combined with the fact that they are a leftover from the past, and that their use in MS Word should also be avoided where possible, we want to want to use tabs sparingly. Their most obvious use cases are to create forms where multiple elements need to be separated from each other using spaces or dotted leaders.
If you merely want to indent the first line of a paragraph, you are strongly advised to use % align left first line % or % align justified first line % at the beginning of the paragraph (or to set a custom styling with a first line indent). From an MS Word perspective, such a first-line-indented paragraph is much more desirable than a paragraph with an initial tab stop.
no parameters
results in an element that produces nothing in the printed document
see also: @black-hole
This function ultimately results in nothing, but is nevertheless useful in those situations where you technically have to insert something to comply with the technical grammar, but do not want anything to actually show up in the document.
In practice, this can for example be used to create the following structure, where you do not want anything to show up next to 1. (without the @void, the 1. would simply be ignored by ClauseBase because that paragraph is actually empty, so that the subclauses would be inadvertently moved one level up).
See
This function can help to quickly create a paragraph with dummy-text. It results in a paragraph with the famous that is either very short (nr. 1) or very long (nr. 5).
This is an advanced function, .
will return true when the document is currently shown in the
As described in the , it is sometimes useful to wrap a part of a clause with the @reporting function, so that it will only be shown when the document is (not) in the reporting-mode. This function will be particularly useful to show/hide/modify a clause’s optional title when (not) in the reporting mode.
