Export Code Type:
Export Code Scope of Action:
Export Code First Added:
Export Code Last Altered:
^include( ^value(item|group)^ )^
A more generalised way to understand this operator is:
^include( which note(s), optionally using which template )^
The first argument resolves to telling Tinderbox where it should look for the note(s) to process. The second argument uses that note's assigned export template or the optionally suppled template is used instead. It thus allows a different export template to be used to render the data returned via ^include^.
This can be a useful method to export (parts of) a note in different ways via different template - but all from the same source note.
^include( ^value(item|group)^ )^
Includes a single item or a group (i.e. list) of notes, using their default export template(s), in the web page for the current note. Note the requirement for the argument to be placed within a ^value()^ code, or else only incorrect.
The item or group scope may also be set from an attribute holding a list of paths, a list-based variable or the returned value of a function.
^include( ^value(item)^, ^value(template)^ )^
The item behaviour is as above but now Tinderbox uses the specified export template passed via template rather than each item's assigned/inherited export template.
^include( ^value(group)^, ^value(template)^ )^
The same applies for group scope, but the same template is applied separately to each group list item.
An example of using a template argument is given further below.
Syntax for single item
A quoted string literal can be used to specify a single item:
^include(^value("a note")^)^
If the item is being assembled via a simple expressions such as string concatenation, an additional ^value()^ wrapper is needed to ensure the value passed to ^include()^ is an actual string or list:
^include(^value("Some"+" note")^)^ → include calls the note "Some note"
If a stored attribute value is used :
^include(^value($MyString)^)^
^include^value(($MyString("Some note"))^)^
In both cases above, $MyString must hold a single note's $Name or its full $Path value, oo $IDString (a Number-type could hold an $ID). Or else, here using a string-type variable 'vString':
^include(^value(vString)^)^
Syntax for multi-item group
A literal group reference via a literal list:
^include(^value([a note;another note])^)^
If using an attribute with group scope:
^include(^value($MyList)^)^
^include(^value($MyList("Another note"))^)^
Expressions that resolve to either item or group scope must also use a ^value()^ wrapper. The most common use with an expression is a find():
^include(^value(find(inside(Some note)))^)^
^include(^value(find($Text.contains("Nelson")))^)^
Using the Template optional argument
The optional second argument specifies the export template to use when including is evaluated. Why might this be needed? In the basic form above, the operator tells the HTML export process to include data from other note(s) into the data being created for the currently-processed note.
By default the nature of the included data is set via the target's export template (or the Tinderbox document's default export template). However, the most common use of an include is that only some data, e.g. just a few attributes or the text, are actually required. The template argument allows the user to specify a different, specific template for the inclusion task. template must be a valid template note in the current TBX document.
The template argument is evaluated. So, as with the item/group input, template can be specified as a literal string, a string value stored in an attribute or an expression that resolves to a literal string holding a template $Name or $Path. For example:
^include(/colophon,^value($MyTemplate)^)^
would export the top-level note named "colophon" using the template named in $MyTemplate for the note currently being processed. (not 'colophon'!). In other words, $MyTemplate is referenced for the context of the note calling the ^include()^ and not the note referenced by item (i.e. the note at path '/colophon').
Thus it is possible to have both arguments parameterised, as in the following:
^include(^value($StringAttribute(ItemNameOrPath))^,^value($TemplateName)^)^
Examples of template use
An example to include attribute data: to get and include values of 3 attributes for 'a note', the process could call:
^include("a note", "3_attributes")^
Where the template "3_attributes" has the template code:
^value($FirstName)^ ^value($LastName)^. Tel: ^value($Phone)^
Of course, the same values could also be called as ^value($FirstName("a note"))^, etc., instead of using ^include()^. Choosing between the methods is a matter of style and the nature of the task.
An example of embedding only a note's text. If the TBX's default export template generates a complete HTML page for note, then this code in Note A's text:
^include(^value("Note B"))^)^ WRONG!
…would nest a complete HTML page's coding inside the <body> content of note A. A browser might cope, but this in not valid HTML use! Instead, it is necessary to specify a template that simply returns the relevant inline content markup: in this case ^text^ in a template called 'text-only'. The corrected include is:
^include(^value("Note B"))^,^value("text-only")^)^
Note: the value of template must resolve to a single template note. template may note be 'raw' export code (as some other operators may allow):
WRONG! ^include(^value("Note B"))^,^value("^text^")^)^
Export and links into included (transcluded) content
In is important to understand that Tinderbox will not generate HTML links for internal links that point to notes that are only exported via the ^include()^ method; consider linking to the note's (exported) parent note instead. The same implies to other forms of transclusive operator: e.g. ^children()^. Such links will not generate #in-page-anchor URLs. In other words, it is not possible, for exported pages to link to include-embedded content in other pages.
Legacy Usage
Although above it stipulates use of ^value()^ for both arguments in all cases, this is not strictly needed. The documentation is like this as it is very difficult for the novice or occasional user to guess if such an argument wrapper is truly needed. The default above will work regardless. Existing code that does not use ^value()^ will continue to work. Expert users who know where ^value()^ is not strictly necessary may continue to omit it. But canonical use is for ^value()^ enclosing each argument.