createAdornment([containerStr, ] nameStr)

Operator Type:

Operator Scope of Action:

Operator Purpose:

Data Type Returned:

Operator First Added:

Operator in Current Baseline:

Operator Last Altered:

Operator Has Optional Arguments:

Function [other Function type actions]

Item [operators of similar scope]

Document configuration [other Document configuration operators]

String [about String data type]

v9.5.0

Baseline

As at baseline

[More on optional operator arguments]

createAdornment([containerStr, ] nameStr)

The operator createAdornment(), creates an adornment at the designated path. If an adornment already exists with that path, no new adornment is created.

createAdornment(nameStr)

This creates a new adornment called nameStr at the designated location, and returns the full path to that adornment. If the designated adornment already exists, no new adornment is created and the operator returns the empty string.

The createAdornment() operator always returns the path to the new (or pre-existing) adornment. Previously, if the adornment already existed, the operator returned false.

This function needs no left-side expression argument, i.e. '$SomeAttribute=', to invoke it.

nameStr is typically actually a complete path:

create("/hardware/taps");

but if nameStr is a unique note $Name, a new adornment is created as a child of the current note. For example:

createAdornment("taps");

createAdornment(containerStr, nameStr)

A two-argument variant is also offered that allows the container for a new item to be specified, and the new item's $Name. This may be useful if you need to create several adornments in the same container, for example is iterating a list with .each(). For example:

createAdornment("/hardware","taps");

Or, more pertinently, using a loop variable 'aPlace':

	$SomeList.each(aPlace){
		createAdornment(aPlace,"urgentTasks");
	};

Essentially, the two-input form allows 3 forms of variation:

different path, different name (via two nested loops—one for paths, one for names)
different path, same name (loop with path variants)
same path, different name (loop with name variants)

The createAdornment() operator evaluates its first argument, permitting use of an expression to compute a value. Note that this means that paths should be quoted: createAdornment("/Containers/People/Mark") , as otherwise parts of paths may be evaluated as expressions.

Designators and evaluation

Paths like that below, which mix literal and computed values are not evaluated, nor are inline designators:

createAdornment(/Resources/Test/$MyString)

Instead use code like this:

	var path="/Resources/Test/"+$MyString;
	createAdornment(path);