Document

A Document is the top-level object in Omni Automation. For security reasons, scripts can only address the frontmost document, they cannot query for or address other documents that may be open.

Unlike other classes of objects, such as items or columns, that can be addressed by index, the “current document” is simply referenced as document instead of app.documents[0] in your scripts.

The following documentation describes how open, create, save, and close documents, as well as how to access a document’s properties.

Class Functions

Here are the class functions of the Document class. They can be used to create new outline documents.

makeNew(resultFunction: Function(document: Document or Error) or null) → (Promise of Document) • Create a new document, which can be populated with data and then presented. On iOS, if the document is not presented by the time the resultFunction returns, it will be closed. On macOS, the document will be left around and accessible to the running script. resultFunction is executed before any functions tethered to the result Promise are executed. Returns a Promise that will yield the new document or an error.
makeNewAndShow(resultFunction: Function(document: Document or Error) or null) → (Promise of Document) • Create a new document and presents it. Returns a Promise that will yield the new document or an error.

omnioutliner://localhost/omnijs-run?script=Document%2EmakeNewAndShow%28newDoc%20%3D%3E%20%7B%0D%09baseItem%20%3D%20newDoc%2Eeditors%5B0%5D%2ErootNode%2Eobject%0D%09baseItem%2EaddChild%28null%2Citem%20%3D%3E%20%7Bitem%2Etopic%20%3D%20%27HELLO%20WORLD%27%7D%29%0D%09newDoc%2Eoutline%2EbaseStyle%2Eclear%28%29%0D%09newDoc%2Eoutline%2EbaseStyle%2Eset%28Style%2EAttribute%2EFontFillColor%2C%20Color%2Ered%29%0D%7D%29

Create a New Document
 

Document.makeNewAndShow(newDoc => {
	baseItem = newDoc.editors[0].rootNode.object
	baseItem.addChild(null,item => {item.topic = 'HELLO WORLD'})
	newDoc.outline.baseStyle.clear()
	newDoc.outline.baseStyle.set(Style.Attribute.FontFillColor, Color.red)
})

NOTE: the above example uses methods from the Style class

New document with a row displaying “Hello World” in red text.

A similar version of the previous script but calling the makeNewAndShow( ) method asynchronously from within an asynchronous function wrapper:

Create a New Document (asynchronous wrapper)


(async () => {
	try {
		newDoc = await Document.makeNewAndShow()
		baseItem = newDoc.editors[0].rootNode.object
		baseItem.addChild(null,item => {item.topic = 'HELLO WORLD'})
		newDoc.outline.baseStyle.clear()
		newDoc.outline.baseStyle.set(Style.Attribute.FontFillColor, Color.red)
	}
	catch(err){
		new Alert(err.name, err.message).show()
	}
})();

The following script uses functions of the Editor and Pasteboard classes to create a new document containing the contents of the selected rows of the current document:

omnioutliner://localhost/omnijs-run?script=%28async%20%28%29%20%3D%3E%20%7B%0D%09try%20%7B%0D%09%09nodes%20%3D%20document%2Eeditors%5B0%5D%2EselectedNodes%0D%09%09pb%20%3D%20Pasteboard%2EmakeUnique%28%29%0D%09%09document%2Eeditors%5B0%5D%2EcopyNodes%28nodes%2C%20pb%29%0D%09%09newDoc%20%3D%20await%20Document%2EmakeNewAndShow%28%29%0D%09%09newDoc%2Eeditors%5B0%5D%2Epaste%28pb%29%0D%09%7D%0D%09catch%28err%29%7B%0D%09%09new%20Alert%28err%2Ename%2C%20err%2Emessage%29%2Eshow%28%29%0D%09%7D%0D%7D%29%28%29%3B

New Document with Content of Selected Rows
 

(async () => {
	try {
		nodes = document.editors[0].selectedNodes
		pb = Pasteboard.makeUnique()
		document.editors[0].copyNodes(nodes, pb)
		newDoc = await Document.makeNewAndShow()
		newDoc.editors[0].paste(pb)
	}
	catch(err){
		new Alert(err.name, err.message).show()
	}
})();

Instance Functions

The following functions can be applied to instances of the Document class.

close(didCancel: Function(document: Document) or null) → ( ) • Close this document. If for some reason the document cannot be closed, the didCancel function may be called at some point in the future, with the original document as the single argument. For example, on the Mac the user may review unsaved changes and may cancel the close operation. If the document is closed, the didCancel function will not be called at all.
save() → ( ) • Save this document. Will summon a FileSaver dialog if the document has not been previously saved.
makeFileWrapper(baseName: String, type: String or null) → (Promise of FileWrapper) • Generates a FileWrapper representing the contents of the document formatted as the specified type, or its current fileType if a null is passed for the type. Returns a Promise that will yield the file wrapper or an error. The returned file wrapper will have a name based off the given baseName and the default path extension for the requested file type. [See Document Export section for detailed examples]
undo() → ( ) • Undo the last done action.
redo() → ( ) • Redo the last undone action.
show(completed: Function( ) or null) → ( ) • Presents the document, ordering the window forward on macOS, and possibly closing the existing document and opening the new on on iOS. Calls the completion function once the document is shown.

Document Properties

The document class has a small set of properties:

canRedo (boolean r/o) • Whether there are currently any actions that can be redone.
canUndo (boolean r/o) • Whether there are currently any actions that can be undone.
fileType (String or nil r/o see FileType) • The file type identifier the document uses when saving, if set.
name (String r/o) • Name of the document.
writableTypes (Array of String r/o) • A list of all of the file types that this document can be written as.

Name

The read-only name property has a value that is the name of the OmniOutiner document as it appears in the title bar of the document window. On macOS, this value will reflect the value of the Finder’s file extension visibility setting, set in the file’s Information window.

The following script statement will return the name of the current document without any file extension:

omnioutliner://localhost/omnijs-run?script=documentName%20%3D%20document%2Ename%2Ereplace%28%2F%5C%2E%5B%5E%2F%2E%5D%2B%24%2F%2C%20%22%22%29%0Dconsole%2Elog%28%22DOCUMENT%20NAME%3A%22%2C%20documentName%29

Document Name
 

documentName = document.name.replace(/\.[^/.]+$/, "")
console.log("DOCUMENT NAME:", documentName)

Document Undo

If the value of the document’s canUndo property is true, then the undo() method can be used to undo the previous user or script action.

canUndo -> undo


if(document.canUndo){document.undo()}

Document Redo

If the value of the document’s canRedo property is true, then the redo() method can be used to re-apply the previous user or script action.

canRedo -> redo


if(document.canRedo){document.redo()}

Document Close

Close this document.

Close Current Document


document.close()

When attempting to close the current document, a crash may occur if the close() function is called within the script being executed by the current document:

New Document Closing Previous One (Unsafe)


(async () => {
	try {
		newDoc = await Document.makeNewAndShow()
		document.close()
	}
	catch(err){
		new Alert(err.name, err.message).show()
	}
})();

Instead, place the close() function targeting the current document inside the handler being run in the new document’s context:

New Document Closing Previous One (Safe)


currentDoc = document
Document.makeNewAndShow(newDoc => {
	currentDoc.close()
})

Document Save

The save() method performs the standard save action with the document.

Save


document.save()

FileType

The FileType class properties are the value for the fileType property of the Document class:

readableTypes (Array of FileType r/o) • The list of FileTypes that can be read by this application.
writableTypes (Array of FileType r/o) • The list of FileTypes that can be written by this application (though some documents may be exportable only in a subset of these types).

The FileType instance properties:

displayName (String r/o) • Returns a human-readable description of the file type.
identifier (String r/o) • Returns a unique identifier for a file type, suitable for archiving or encoding in scripts.
pathExtensions (Array of String r/o) • The list of filesystem path extensions used by this file type.

And scripts for gathering information about each file type:

omnioutliner://localhost/omnijs-run?script=FileType%2EreadableTypes%2EforEach%28fType%20%3D%3E%20%7B%0D%09console%2Elog%28%27NAME%3A%20%27%20%2B%20fType%2EdisplayName%29%0D%09console%2Elog%28%27IDENTIFIER%3A%20%27%20%2B%20fType%2Eidentifier%29%0D%09console%2Elog%28%27EXTENSIONS%3A%20%27%20%2B%20fType%2EpathExtensions%29%0D%09console%2Elog%28%27%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%27%29%0D%7D%29

Readable File Types Info
 

FileType.readableTypes.forEach(fType => {
	console.log('NAME: ' + fType.displayName)
	console.log('IDENTIFIER: ' + fType.identifier)
	console.log('EXTENSIONS: ' + fType.pathExtensions)
	console.log('----------------------------')
})

Readable File Types Info


NAME: com.omnigroup.omnioutliner.otemplate
IDENTIFIER: com.omnigroup.omnioutliner.otemplate
EXTENSIONS: otemplate
----------------------------
NAME: com.apple.property-list
IDENTIFIER: com.apple.property-list
EXTENSIONS: plist
----------------------------
NAME: com.omnigroup.omnioutliner.oo3template
IDENTIFIER: com.omnigroup.omnioutliner.oo3template
EXTENSIONS: oo3template
----------------------------
NAME: com.omnigroup.omnioutliner.xmlooutline
IDENTIFIER: com.omnigroup.omnioutliner.xmlooutline
EXTENSIONS: ooutline
----------------------------
NAME: com.omnigroup.omnioutliner.xmlooutline-package
IDENTIFIER: com.omnigroup.omnioutliner.xmlooutline-package
EXTENSIONS: ooutline
----------------------------
NAME: com.omnigroup.omnioutliner.oo3-package
IDENTIFIER: com.omnigroup.omnioutliner.oo3-package
EXTENSIONS: oo3
----------------------------
NAME: com.symantec.more
IDENTIFIER: com.symantec.more
EXTENSIONS: more
----------------------------
NAME: org.opml.opmltemplate
IDENTIFIER: org.opml.opmltemplate
EXTENSIONS: opmltemplate
----------------------------
NAME: com.omnigroup.omnioutliner.otemplate-package
IDENTIFIER: com.omnigroup.omnioutliner.otemplate-package
EXTENSIONS: otemplate
----------------------------
NAME: com.omnigroup.omnioutliner.oo3
IDENTIFIER: com.omnigroup.omnioutliner.oo3
EXTENSIONS: oo3
----------------------------
NAME: com.omnigroup.omnioutliner.oo3template-package
IDENTIFIER: com.omnigroup.omnioutliner.oo3template-package
EXTENSIONS: oo3template
----------------------------
NAME: com.apple.xcode.strings-text
IDENTIFIER: com.apple.xcode.strings-text
EXTENSIONS: strings
----------------------------
NAME: org.opml.opml
IDENTIFIER: org.opml.opml
EXTENSIONS: opml
----------------------------

omnioutliner://localhost/omnijs-run?script=FileType%2EwritableTypes%2EforEach%28function%28fType%29%7B%0D%09console%2Elog%28%27NAME%3A%20%27%20%2B%20fType%2EdisplayName%29%0D%09console%2Elog%28%27IDENTIFIER%3A%20%27%20%2B%20fType%2Eidentifier%29%0D%09console%2Elog%28%27EXTENSIONS%3A%20%27%20%2B%20fType%2EpathExtensions%29%0D%09console%2Elog%28%27%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%2D%27%29%0D%7D%29

Writable File Types Info
 

FileType.writableTypes.forEach(function(fType){
	console.log('NAME: ' + fType.displayName)
	console.log('IDENTIFIER: ' + fType.identifier)
	console.log('EXTENSIONS: ' + fType.pathExtensions)
	console.log('----------------------------')
})

Writable File Types Info


NAME: com.omnigroup.omnioutliner.otemplate-package
IDENTIFIER: com.omnigroup.omnioutliner.otemplate-package
EXTENSIONS: otemplate
----------------------------
NAME: org.opml.opmltemplate
IDENTIFIER: org.opml.opmltemplate
EXTENSIONS: opmltemplate
----------------------------
NAME: com.omnigroup.omnioutliner.oo3template
IDENTIFIER: com.omnigroup.omnioutliner.oo3template
EXTENSIONS: oo3template
----------------------------
NAME: com.omnigroup.omnioutliner.xmlooutline-package
IDENTIFIER: com.omnigroup.omnioutliner.xmlooutline-package
EXTENSIONS: ooutline
----------------------------
NAME: com.omnigroup.omnioutliner.oo3template-package
IDENTIFIER: com.omnigroup.omnioutliner.oo3template-package
EXTENSIONS: oo3template
----------------------------
NAME: com.omnigroup.omnioutliner.oo3-package
IDENTIFIER: com.omnigroup.omnioutliner.oo3-package
EXTENSIONS: oo3
----------------------------
NAME: com.omnigroup.omnioutliner.oo3
IDENTIFIER: com.omnigroup.omnioutliner.oo3
EXTENSIONS: oo3
----------------------------
NAME: org.opml.opml
IDENTIFIER: org.opml.opml
EXTENSIONS: opml
----------------------------
NAME: com.omnigroup.omnioutliner.otemplate
IDENTIFIER: com.omnigroup.omnioutliner.otemplate
EXTENSIONS: otemplate
----------------------------
NAME: com.omnigroup.omnioutliner.xmlooutline
IDENTIFIER: com.omnigroup.omnioutliner.xmlooutline
EXTENSIONS: ooutline
----------------------------