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.

Create a New Document
Copy Try It!

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

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)
Copy

(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:

New Document with Content of Selected Rows
Copy Try It!

(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 Property

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:

name Property
Copy Try It!

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

writableTypes Property

The following script statement will return a list of the available writable file types. [See Document Export section for detailed examples]

writableTypes Property
Copy

document.writableTypes.join("\n")
//--> "com.omnigroup.omnioutliner.xmlooutline
com.omnigroup.omnioutliner.ooutline
com.omnigroup.omnioutliner.oooutline
com.omnigroup.omnioutliner.xmlooutline-package
com.omnigroup.omnioutliner.otemplate
com.omnigroup.omnioutliner.otemplate-package
com.omnigroup.omnioutliner.oo3
com.omnigroup.omnioutliner.oo3-package
com.omnigroup.omnioutliner.oo3template
com.omnigroup.omnioutliner.oo3template-package
org.opml.opml
org.opml.opmltemplate
public.rtf
com.symantec.MORE.text
public.plain-text
com.apple.rtfd
com.omnigroup.word.openxml.indented
com.omnigroup.word.openxml.outline
com.omnigroup.OmniOutliner.SimpleHTMLExport.HTML
com.microsoft.powerpoint.openxml.presentation
com.omnigroup.OmniOutliner.OO3HTMLExport.OO3HTMLDynamic
com.omnigroup.OmniOutliner.HTMLExport.HTMLDynamic
com.microsoft.excel.openxml.document
public.comma-separated-values-text"

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
Copy

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
Copy

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

Document Close

Close this document.

Close Current Document
Copy

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)
Copy

(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)
Copy

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

Document Save

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

Save
Copy

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.

Scripts for logging type information in the Console window:

readableTypes
Copy

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

readableTypes
Copy

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

writableTypes
Copy

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

writableTypes
Copy

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