create([containerStr, ]nameStr)

---

create(name)

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

The create() operator always returns the path to the new (or pre-existing) note.

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 note is created as a new (last) child of the current note, but only if nameStr does not already exist. For example:

create("taps"); 

Importantly, if nameStr is only a $Name and not a $Path, the note title nameStr it must be unique to the whole the current document. But, if nameStr is a $Path then it need only be unique within the current container.

create(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 notes in the same container, for example is iterating a list with .each(). For example:

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

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

	$SomeList.each(aPlace){
		create(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)

Designators and evaluation

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

create(/Resources/Test/$MyString) 

Instead use code like this:

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

Testing for pre-existing notes

Although create() will not re-create a note that already exists, a scenario in a big/complex document occurs where it may be necessary to run a number of action once only on newly created notes. How to test for a note already existing? Here is one possible solution:

	var:string vTestPath = "/foo/bar/baz";
	var:string vTest = $IDString(vTestPath);
	if(vTest==""){
		$Text = create(vTestPath);
		// do tasks only needed once, for new notes
	};

A non-existent note cannot have an $IDString value. So by testing the $IDString(path) for the path of the note to be created before calling create(path), it is possible to ensure create() is only called if needed and in context all the code desired to be run, once, at new note creation.