Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Last Altered:
Function [other Function type actions]
Item [operators of similar scope]
Formatting [other Formatting operators]
Baseline
As at baseline
exportedString(item[, templateStr])
The operator exportedString() applies an export template to a note, returning the result as a String.
item designates the note to be exported; and is a note name, path or item designator. An attribute may not be used as a placeholder for such information. By default, the note used is the current note, i.e. 'this'. exportedString() also binds 'current' designator to 'this' when resolving item.
The second argument, templateStr, has three forms.
- an HTML export template name; this argument is evaluated allowing use of attribute values and expressions. Full template paths should not be quotes, but enclose template names ($Name) in double-quotes.
- the name of an attribute or variable whose value is a string of actual template code (i.e. what would normally be the contents of a template), which is then applied to the referenced note. The attribute reference cannot use a path extension to refer to a different note, $ExportCode is OK but an offset address like $ExportCode(Another note) will fail.
- a literal string of export code. The most usual use of this is as '
^text^', i.e. the export encoded $Text of the note. This form is suggested only for very short code strings. For longer code, place it in a discrete template and use it via the two-argument form.
In the short, single argument, usage the template to evaluate is not supplied as the target note's inherited or locally assigned template is used. In long-lived projects, it can be useful to use the two-argument form (assuming the template assignment will not change!). Doing this makes it easier to see in code which template will be used rather than have to go and look up that value. Making such a change has no performance input.
The exportedString() operator is especially useful in conjunction with the runCommand() operator. You can use exportedString() to assemble the input an external program will require, and then pass that input to the external program.
If you simply wish to transform a string or attribute value (e.g. $Name) into a 'safe' value for use as an HTML/XML element 'id' value, a possible alternative is to use idEncode().
Examples
exportedString(item)
Use of exportedString with just the target item. If using only the (unique) note $Name, it should should be quote-enclosed.
$MyString = exportedString("Some Note");
or using a full $Path for the template, do not use quotes:
$MyString = exportedString(/Projects/X/Some Note);
exportedString(item, templateStr)
The first form using templateStr takes a reference to a note and the name of a template note and returns the result of applying the template to the note. If item is a path or title, the value requires quotes:
$MyString = exportedString(this,"tSome_Template");
$MyString = exportedString("Some note","tSome_Template");
or use the unquoted full $Path for the template:
$MyString = exportedString(this,/Templates/tSome_Template);
The second form using templateStr requires as its second argument is the template string itself which may be a reference to an attribute or action code variable:
$MyString = exportedString(this,$MyTemplateCode);
$MyString = exportedString(this,vTemplate);
The third form using templateStr requires as its second argument some literal code:
$MyString = exportedString("/Path/To/Some note","^text^");
$MyString = exportedString("/Path/To/Some note","^value($Name(parent))^");