Code Type:
Code Scope of Action:
Code First Added:
Code Altered:
^include( item|group )^
Includes a single item or group notes, using their default template(s), in the web page for the current note. The scope may also be set from an attribute holding a list of paths or a function returning such a list.
^include( item|group, template )^
Includes the item or group using the specified export template rather than each note(s)' default export template. for instance is a note is set to export a complete page, the default would be inappropriate where the note's output is to be used embedded in another page. In the later case, it is necessary to specify a template that simply returns inline content markup.
Another generalised way to understand this operator is:
^include(which object(s), what content/what form)^
The first parameter resolves to telling where Tinderbox should look to pull data in export template form. The second parameter overrides the template set for/inherited by the object(s) set via the first parameter and allows a different export template to be used to render the data returned via ^include^.
IMPORTANT: 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 (export) parent note instead. The same implies to other forms of transclusive operator: e.g. ^children()^. Put another way if you build templates where the exported (HTML) documents where one document includes content from child/other Tinderbox notes, links to the included content from other documents will not get created. Tinderbox is not able to convert those links to #in-page-addresses within the overall target document.
Syntax
A quoted string literal can be used with either a single item or a group (list). A literal item reference:
^include("a note")^
A literal group reference via a literal list:
^include("a note;another note")^
If the item or group 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, group assignments must be enclosed in a ^value()^ code whereas they are not needed for item assignments. So, for calls which return a single item:
^include($MyString)^
^include($MyString("Some note"))^
In both cases above, $MyString must hold a note's $Name or its full $Path value. This method is not used for retrieving the value of any attribute to insert into the export. For that you use ^value()^.
Examples for as group scope, where the target attribute holds a list of notes and a ^value()^ code encloses the attribute called:
^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")))^)^
Note, ^include()^ does not mind if the initial input is a list of one (item) or many (group), but the above variations ensure that the actual data passed into the operator are in the correct format.
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 tell 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, it is most often the case with include that only some data, e.g. just a few attributes, 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. In this way 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 ba 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.
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. Thus it is possible to have both inputs permits parameterised, constructions as in the following:
^include(^value($StringAttribute(ItemNameOrPath))^,^value($TemplateName)^)^