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

The class properties of the Perspective.BuiltIn class:

The instance properties of the Perspective.BuiltIn class:

The properties of the Perspective.Custom class:

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

Changing the currently displayed perspective:

// Get the name of the current perspective document.windows[0].perspective.name //--> "Projects" // Change window view to show Inbox perspective document.windows[0].perspective = Perspective.BuiltIn.Inbox //--> [object Perspective.BuiltIn: Inbox]
omnifocus://localhost/omnijs-run?script=try%7Bdocument%2Ewindows%5B0%5D%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EInbox%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

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:

The class functions of the Perspective.Custom class:

The instance functions of the Perspective.Custom class:

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, incorporate the built-in URL support of OmniFocus in the script:

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

 01  The name of the custom perspective to be shown.

 02  Append a percent-encoded verson of the custom perspective name to URL string targeting the current perspective in the OmniFocus application.

 03  Use the fromString(…) method of the URL class to convert the string into a URL object, and then execute the url by appending the open() function to the result.

Export the Chosen Custom Perspective (v3.9)

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.

/*{ "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.

/*{ "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 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).

Screenshot

(⬆ 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.

/*{ "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; })();

DISCLAIMER