Perspective

A Perspective is a view into your OmniFocus database that appears in the perspective list (left-side of window) and whose contents are detailed in the outline (right-side of window).

OmniFocus comes with built-in perspectives (Perspective.BuiltIn class): Flagged, Forecast, Inbox, Nearby, Projects, Review, and Tags; and two transient reference perspectives: Completed and Changed. Custom perspectives (Perspective.Custom class) can be created in OmniFocus Pro.

Perspective Properties

Here are the properties of both the built-in and custom perspective classes:

The Class Properties of the Perspective.BuiltIn class:

• Flagged (Perspective.BuiltIn r/o) • The flagged items.

• Forecast (Perspective.BuiltIn r/o) • The upcoming due items.

• Inbox (Perspective.BuiltIn r/o) • The inbox of tasks.

• Nearby (Perspective.BuiltIn r/o) • Nearby items on a map (iOS only).

• Projects (Perspective.BuiltIn r/o) • The library of projects.

• Review (Perspective.BuiltIn r/o) • The projects needing review.

• Search (Perspective.BuiltIn r/o) • A search of the database. This perspective cannot be set, but might be reported if the user is searching.

• Tags (Perspective.BuiltIn r/o) • The hierarchy of tags.

• all (Array of Perspective.BuiltIn) • An array of all items of this enumeration. THis property is sometimes used when creating Action Forms.

The Instance Properties of the Perspective.BuiltIn class:

• name (String r/o) • The localized name of the built in perspective.

The Instance Properties of the Perspective.Custom class:

• identifier (String r/o) • The unique identifier for this custom perspective.

• name (String r/o) • The name of this custom perspective.

• all (Array of Perspective.Custom) • An array of all items of this enumeration. This property is sometimes used when creating Action Forms.

An instance of either the built-in or custom Perspective class is the value of the perspective property of the Window class.

The Perspective Property of a Window
Copy

document.windows[0].perspective
//--> [object Perspective.BuiltIn: Inbox]

Get the name of the current perspective:

Name of the Current Perspective
Copy

document.windows[0].perspective.name
//--> "Projects"

Change window view to show Inbox perspective:

Change Window to Inbox Perspective
Copy Run Script

document.windows[0].perspective = Perspective.BuiltIn.Inbox
//--> [object Perspective.BuiltIn: Inbox]

Perspectives can also be shown using the OmniFocus URL schema:

• omnifocus:///inbox
• omnifocus:///flagged
• omnifocus:///projects
• omnifocus:///tags

Show Projects Perspective
Copy Run Script

URL.fromString("omnifocus:///projects").open()

Custom Perspectives

Custom Perspectives are created by you to display items based upon the filtering parameters you define.

The properties of the Perspective.Custom class:

• identifier (String r/o) • A unique identifying string assigned to the perspective instance. For example: “aS3jYumRtrm”

• name (String r/o) • The name of the custom perspective.

• all (Array of Perspective.Custom) • An array of all items of this enumeration. THis property is sometimes used when creating Action Forms.

The Class Functions of the Perspective.Custom class:

• byName(name:String) → (Perspective.Custom or null) • A custom perspective with the given name, if one exists. If there are multiple perspectives with the same name, it is not defined which will be returned.

• byIdentifier(uuid:String) → (Perspective.Custom or null) • The custom perspective with this identifier, if it exists. There is guaranteed to be at most one perspective with a given identifier.

The Instance Functions of the Perspective.Custom class:

• fileWrapper( ) → (FileWrapper) • Returns an archived file wrapper for the custom perspective. The file wrapper’s preferred filename will be the name of the perspective with an appropriate file extension applied. Its contents will include a plist representing the perspective’s settings, along with any image attachments needed to display its icon.

• writeFileRepresentationIntoDirectory(parentURL: URL) → (URL) • Writes the perspective’s fileWrapper() within a given parent directory URL, returning the URL of the saved FileWrapper. This function requires sandboxed access to the parent folder; it may be easier to work with the perspective’s fileWrapper(), which can be accessed directly or saved to disk using FileSaver.

Show a Custom Perspective
Copy

var p = Perspective.Custom.byName("Fairfield Project")
if(p){document.windows[0].perspective = p}

Showing Custom Perspective using a URL

To display a custom perspective, you may optionally incorporate the built-in URL support of OmniFocus in the script:

Show Custom Perspective
Copy

var name = "Fairfield Project"
var urlStr = "omnifocus:///perspective/" + encodeURIComponent(name)
URL.fromString(urlStr).open()

Export the Chosen Custom Perspective

Here is an example plug-in that will display a menu of all available custom perspectives, and then the chosen perspective to file on disk.

Export Custom Perspective
Copy Download Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.export-custom-perspective",
	"version": "1.0",
	"description": "Exports the chosen custom perspective to file.",
	"label": "Export Custom Perspective",
	"shortLabel": "Export Perspective",
	"paletteLabel": "Export Perspective",
}*/
(() => {
	var action = new PlugIn.Action(function(selection, sender){
		// action code
		// selection options: tasks, projects, folders, tags
		
		var perspectives = new Array()
		perspectives = perspectives.concat(Perspective.Custom.all)
		var perspectiveNames = perspectives.map(perspective => {
			return perspective.name
		})
		var itemIndexes = new Array()
		perspectiveNames.forEach((name, index) => {
			itemIndexes.push(index)
		})
		
		var perspectiveMenu = new Form.Field.Option(
			"perspective", 
			"Perspective", 
			itemIndexes, 
			perspectiveNames, 
			0
		)
		perspectiveMenu.allowsNull = false

		var inputForm = new Form()
		inputForm.addField(perspectiveMenu)
		var formPrompt = "Choose the custom perspective to export:"
		var buttonTitle = "Continue"
		formPromise = inputForm.show(formPrompt,buttonTitle)
		
		formPromise.then(function(formObject){
			var chosenPerspective = perspectives[formObject.values['perspective']]
			var wrapper = chosenPerspective.fileWrapper()
			var filesaver = new FileSaver()
			var fileSaverPromise = filesaver.show(wrapper)
			
			fileSaverPromise.then(function(urlObj){
				console.log(urlObj.string)
			})

			fileSaverPromise.catch(function(err){
				console.log("problem saving", err.message)
			})
		})

		formPromise.catch(function(err){
			console.error("form cancelled", err.message)
		})	   
	});

	action.validate = function(selection, sender){
		return (Perspective.Custom.all.length > 0)
	};
		
	return action;
})();

eMail the Chosen Custom Perspective (3.9)

Here is an example plug-in that will display a menu of all available custom perspectives, and then add the exported perspective file to a new outgoing email message.

eMail Custom Perspective
Copy Download Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.email-custom-perspective",
	"version": "1.0",
	"description": "Creates a new outgoing mail message with the chosen custom perspective.",
	"label": "eMail Custom Perspective",
	"shortLabel": "eMail Perspective",
	"paletteLabel": "eMail Perspective",
}*/
(() => {
	var action = new PlugIn.Action(function(selection, sender){
		// action code
		// selection options: tasks, projects, folders, tags
		
		var perspectives = new Array()
		perspectives = perspectives.concat(Perspective.Custom.all)
		var perspectiveNames = perspectives.map(perspective => {
			return perspective.name
		})
		var itemIndexes = new Array()
		perspectiveNames.forEach((name, index) => {
			itemIndexes.push(index)
		})
		
		var perspectiveMenu = new Form.Field.Option(
			"perspective", 
			"Perspective", 
			itemIndexes, 
			perspectiveNames, 
			0
		)
		perspectiveMenu.allowsNull = false

		var inputForm = new Form()
		inputForm.addField(perspectiveMenu)
		var formPrompt = "Choose the custom perspective to export:"
		var buttonTitle = "Continue"
		var formPromise = inputForm.show(formPrompt,buttonTitle)
		
		formPromise.then(function(formObject){
			var chosenPerspective = perspectives[formObject.values['perspective']]
			var pName = chosenPerspective.name
			var wrapper = chosenPerspective.fileWrapper()
			var email = new Email()
			email.subject = pName + " Perspective"
			email.body = "Here is a copy of my OmniFocus perspective: “" + pName + "”\n\n"
			email.fileWrappers = [wrapper]
			email.generate()
		})

		formPromise.catch(function(err){
			console.error("form cancelled", err.message)
		})	   
	});

	action.validate = function(selection, sender){
		return (Perspective.Custom.all.length > 0)
	};
		
	return action;
})();

Add the Chosen Perspective

Here is the basic script for creating a new tab (macOS) or window (iPadOS) for a specified perspective:

New Tab/Window with Perspective
Copy

(async () => {		
	var targetPerspective = Perspective.BuiltIn.Projects
	if (Device.current.mac){
		var win = await document.newTabOnWindow(document.windows[0])
		win.perspective = targetPerspective
	} else {
		var win = await document.newWindow()
		win.perspective = targetPerspective
	}
})().catch(err => console.error(err.message))

And a version where the chosen perspective is added to a new tab or window:

New View with Chosen Perspective
Copy Run Script

(async () => {
	// remove Search
	var bPerspectives = Perspective.BuiltIn.all
	idx = bPerspectives.indexOf(Perspective.BuiltIn.Search)
	if (idx > -1) {
	  bPerspectives.splice(idx, 1);
	}
	bPerspectives.sort((a, b) => {
	  var x = a.name;
	  var y = b.name;
	  if (x < y) {return -1;}
	  if (x > y) {return 1;}
	  return 0;
	})
	bpNames = bPerspectives.map(p => p.name)

	var cPerspectives = Perspective.Custom.all
	cPerspectives.sort((a, b) => {
	  var x = a.name;
	  var y = b.name;
	  if (x < y) {return -1;}
	  if (x > y) {return 1;}
	  return 0;
	})
	var cpNames = cPerspectives.map(p => p.name)
	var pNames = bpNames.concat(cpNames)
	var itemIndexes = pNames.map((item, index) => index)
	var pObjs = bPerspectives.concat(cPerspectives)

	var perspectivesMenu = new Form.Field.Option(
		"perspective", 
		"Perspective", 
		itemIndexes, 
		pNames, 
		0
	)

	var inputForm = new Form()
	inputForm.addField(perspectivesMenu)
	var formPrompt = "Choose perspective to show:"
	var buttonTitle = "Continue"
	var formObject = await inputForm.show(formPrompt,buttonTitle)
	var chosenIndex = formObject.values['perspective']
	var chosenPerspective = pNames[chosenIndex]
	var perspect = pObjs[chosenIndex]
	
	if (Device.current.mac){
		if(perspect === Perspective.BuiltIn.Nearby){
		 	throw new Error("Nearby not available on macOS")
		}
		var win = await document.newTabOnWindow(document.windows[0])
	} else {
		var win = await document.newWindow()
	}
	win.perspective = perspect
})().catch(err => new Alert(err.name, err.message).show())

Here is an example plug-in that will display a menu of all available perspectives, and then open the chosen perspective in a new tab (macOS) or a new window (iOS and iPadOS).

(⬆ see above ) The Add Chosen Perspective plug-in has no contextual selection requirements so it is available in the Share menu when no elements are selected in the app interface.

Add the Chosen Perspective
Copy Download Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.add-chosen-perspective",
	"version": "1.0",
	"description": "This action will add a new tab (macOS) or window (iPadOS) displaying the chosen perspective.",
	"label": "Add Chosen Perspective",
	"shortLabel": "Add Chosen Perspective"
}*/
(() => {
	var action = new PlugIn.Action(function(selection, sender){
		// action code
		// selection options: tasks, projects, folders, tags
		
		var perspectives = new Array()
		perspectives = perspectives.concat(Perspective.BuiltIn.all)
		perspectives = perspectives.concat(Perspective.Custom.all)
		var perspectiveNames = perspectives.map(perspective => {
			return perspective.name
		})
		var itemIndexes = new Array()
		perspectiveNames.forEach((name, index) => {
			itemIndexes.push(index)
		})
		
		var perspectiveMenu = new Form.Field.Option(
			"perspective", 
			"Perspective", 
			itemIndexes, 
			perspectiveNames, 
			0
		)

		var inputForm = new Form()
		inputForm.addField(perspectiveMenu)
		var formPrompt = "Choose the perspective:"
		var buttonTitle = "Continue"
		var formPromise = inputForm.show(formPrompt,buttonTitle)

		inputForm.validate = function(formObject){
			return true
		}

		formPromise.then(function(formObject){
			var chosenIndex = formObject.values['perspective']
			var chosenPerspective = perspectives[chosenIndex]

			if (Device.current.mac){
				var windowPromise = document.newTabOnWindow(document.windows[0])
			} else {
				var windowPromise = document.newWindow()
			}
			
			windowPromise.then(function(win){
				win.perspective = chosenPerspective
			})
			
			windowPromise.catch(function(error){
				console.error(error.message)
			})
		})

		formPromise.catch(function(err){
			console.error("form cancelled", err.message)
		})
	});

	action.validate = function(selection, sender){
		// validation code
		// selection options: tasks, projects, folders, tags
		return true
	};
	
	return action;
})();