Special items

@black-hole

  • 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 data dashboard, 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 explanation about the advanced use of the! within the datafield).

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.)

@comment

  • 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.

@email

  • 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.

@highlight, @highlight-red, @highlight-green, @highlight-yellow

  • 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.

@image

See How to insert images

@insert-document

  • 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).

@link

  • 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”.

@lorem

  • parameter: a number between 1 and 5

  • returns a paragraph with the relative length indicated by its parameter

This function can help to quickly create a paragraph with dummy-text. It results in a paragraph with the famous lorem ipsum text that is either very short (nr. 1) or very long (nr. 5).

@merge-tables

  • 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:

@msword-pages, @msword-pages-own-nrs and @msword-fragment

  • 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

This is an advanced function, described separately.

@open-qa

  • 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).

@pagecount

  • 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.)

@pagenr

  • 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.

Note that @pagenr cannot be calculated in the browser (i.e., will only export in Word or PDF). Within MS Word, the page number 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.)

@para

  • 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 ...

@paras

  • 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 ...

@placeholder

  • 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.

@reporting

  • no parameters

  • will return true when the document is currently shown in the reporting mode

For example, @reporting — no parameters or parentheses necessary — would return true if the document is currently shown in the reporting mode.

As described in the overview of the reporting mode, 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.

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.

@tab

  • 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.

Do not use tabs in table columns with automatic widths, because the results are unpredictable. Make sure that the table alignment is set to fill the entire width, and that the width of the columns is not automatically calculated.

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.

@void

  • 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).

PreviousRepeating (looping)NextText structure

Last updated