×

Forecast

Forecast helps you keep an eye on the progress of your projects, check upcoming due dates, and schedule OmniFocus “to-dos” alongside important events in your calendar.

The Forecast Sidebar displays a range of dates in a grid spanning the next month, letting you know at a glance what’s on your plate in the coming weeks. Each date button displays the number of actions associated with that date. For due items, the count is color-coded according to the most urgent item: amber indicates that an item is due soon, and red indicates an item is due or past due.

The Forecast Outline displays a chronological list of items due each day (across a selection of days, if you have multiple selected in the sidebar), interleaved with events from any calendars you’ve chosen to display in OmniFocus.

ForecastDay Class

The ForecastDay class represents the individual days of your OmniFocus calendar.

Class Properties for the ForecastDay class:

Instance properties for an instance of the ForecastDay class:

Instance functions for the ForecastDay class:

ForecastDay.Kind Class

Each of the instances of the ForecastDay class is classified as specific kind of Forecast day based upon its position relative to the current date.

Class properties of the ForecastDay.Kind class:

ForecastDay.Status Class

Each Forecast days has a status that is based upon the status of the tasks occurring during that forecast day.

Class properties of the ForecastDay.Status class:

Forecast-Related Window Instance Functions

IMPORTANT: Since the use these functions require a specific perspective be displayed, the scripts may incorporate the use a of Timer function to allow the window time to change views.

Here’s a function that creates and displays a forecast day for the provided date object:

omnifocus://localhost/omnijs-run?script=try%7Bfunction%20showForecastDayForDate%28targetDate%29%7B%0A%09document%2Ewindows%5B0%5D%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EForecast%0A%09Timer%2Eonce%281%2Cfunction%28timer%29%7B%0A%09%09var%20fday%20%3D%20document%2Ewindows%5B0%5D%2EforecastDayForDate%28targetDate%29%0A%09%09document%2Ewindows%5B0%5D%2EselectForecastDays%28%5Bfday%5D%29%0A%09%09return%20fday%0A%09%7D%29%0A%7D%0AshowForecastDayForDate%28new%20Date%28%29%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
Show Forecast Day for Date
 

function showForecastDayForDate(targetDate){ var win = document.windows[0] win.perspective = Perspective.BuiltIn.Forecast var fday = win.forecastDayForDate(targetDate) win.selectForecastDays([fday]) return fday }

Script for showing today’s forecast:

Show Today’s Forecast


var win = document.windows[0] win.perspective = Perspective.BuiltIn.Forecast var date = new Date().setHours(0, 0, 0) var fday = win.forecastDayForDate(new Date(date)) win.selectForecastDays([fday])

Here’s an example script that adds a new window (or tab on macOS) showing the forecast view for the current day:

omnifocus://localhost/omnijs-run?script=try%7Bvar%20targetDate%20%3D%20new%20Date%28%29%0Aif%28app%2EplatformName%20%3D%3D%20%27macOS%27%29%7B%0A%09var%20windowPromise%20%3D%20document%2EnewTabOnWindow%28document%2Ewindows%5B0%5D%29%0A%7D%20else%20%7B%0A%09var%20windowPromise%20%3D%20document%2EnewWindow%28%29%0A%7D%0AwindowPromise%2Ethen%28function%28win%29%7B%0A%09win%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EForecast%0A%09Timer%2Eonce%281%2Cfunction%28timer%29%7B%0A%09%09var%20fday%20%3D%20win%2EforecastDayForDate%28targetDate%29%0A%09%09win%2EselectForecastDays%28%5Bfday%5D%29%0A%09%7D%29%09%0A%7D%29%0AwindowPromise%2Ecatch%28function%28error%29%7B%0A%09console%2Eerror%28error%2Emessage%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
New Window (Tab) for Today’s Forecast
  

var targetDate = new Date() var win = document.windows[0] if(app.platformName == 'macOS'){ var windowPromise = document.newTabOnWindow(win) } else { var windowPromise = document.newWindow() } windowPromise.then(win => { win.perspective = Perspective.BuiltIn.Forecast var fday = win.forecastDayForDate(targetDate) win.selectForecastDays([fday]) }) windowPromise.catch(err => { console.error(err.message) })

TIP: For the previous example, use properties and functions of the shared Calendar class to derive a target date relative to today, such as tomorrow:

Deriving Date Relative to Today (tomorrow)


var now = new Date() var today = Calendar.current.startOfDay(now) var dc = new DateComponents() dc.day = 1 var targetDate = Calendar.current.dateByAddingDateComponents(today,dc)

…or for seven days from today:

omnifocus://localhost/omnijs-run?script=try%7Bdocument%2Ewindows%5B0%5D%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EForecast%0ATimer%2Eonce%281%2Cfunction%28timer%29%7B%0A%09var%20now%20%3D%20new%20Date%28%29%0A%09var%20today%20%3D%20Calendar%2Ecurrent%2EstartOfDay%28now%29%0A%09var%20dc%20%3D%20new%20DateComponents%28%29%0A%09dc%2Eday%20%3D%207%0A%09var%20targetDate%20%3D%20Calendar%2Ecurrent%2EdateByAddingDateComponents%28today%2Cdc%29%0A%09var%20fday%20%3D%20document%2Ewindows%5B0%5D%2EforecastDayForDate%28targetDate%29%0A%09document%2Ewindows%5B0%5D%2EselectForecastDays%28%5Bfday%5D%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
Select Forecast for 7th Day from Today
 

document.windows[0].perspective = Perspective.BuiltIn.Forecast var win = document.windows[0] var now = new Date() var today = Calendar.current.startOfDay(now) var dc = new DateComponents() dc.day = 7 var targetDate = Calendar.current.dateByAddingDateComponents(today,dc) var fday = win.forecastDayForDate(targetDate) win.selectForecastDays([fday])

…or for the next seven days from today:

omnifocus://localhost/omnijs-run?script=try%7Bdocument%2Ewindows%5B0%5D%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EForecast%0ATimer%2Eonce%281%2Cfunction%28timer%29%7B%09%09%0A%09var%20now%20%3D%20new%20Date%28%29%0A%09var%20today%20%3D%20Calendar%2Ecurrent%2EstartOfDay%28now%29%0A%09var%20dc%20%3D%20new%20DateComponents%28%29%0A%09var%20fdays%20%3D%20new%20Array%28%29%0A%09var%20fday%2C%20targetDate%2C%20i%0A%09for%20%28i%20%3D%200%3B%20i%20%3C%207%3B%20i%2B%2B%29%20%7B%20%0A%09%09dc%2Eday%20%3D%20i%20%2B%201%0A%09%09targetDate%20%3D%20Calendar%2Ecurrent%2EdateByAddingDateComponents%28today%2Cdc%29%0A%09%09fday%20%3D%20document%2Ewindows%5B0%5D%2EforecastDayForDate%28targetDate%29%0A%09%09fdays%2Epush%28fday%29%0A%09%7D%0A%09document%2Ewindows%5B0%5D%2EselectForecastDays%28fdays%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
Select Range of Forecast Dates
  

var win = document.windows[0] win.perspective = Perspective.BuiltIn.Forecast var now = new Date() var today = Calendar.current.startOfDay(now) var dc = new DateComponents() var fdays = new Array() var fday, targetDate, i for (i = 0; i < 7; i++) { dc.day = i + 1 targetDate = Calendar.current.dateByAddingDateComponents(today,dc) fday = win.forecastDayForDate(targetDate) fdays.push(fday) } win.selectForecastDays(fdays)

A script for displaying the first upcoming forecast day whose badge count is positive:

omnifocus://localhost/omnijs-run?script=var%20win%20%3D%20document%2Ewindows%5B0%5D%0Awin%2Eperspective%20%3D%20Perspective%2EBuiltIn%2EForecast%0Avar%20now%20%3D%20new%20Date%28%29%0Avar%20today%20%3D%20Calendar%2Ecurrent%2EstartOfDay%28now%29%0Avar%20dc%20%3D%20new%20DateComponents%28%29%0Avar%20fdays%20%3D%20new%20Array%28%29%0Avar%20fday%2C%20targetDate%2C%20i%0Afor%20%28i%20%3D%200%3B%20i%20%3C%2030%3B%20i%2B%2B%29%20%7B%20%0A%09dc%2Eday%20%3D%20i%20%2B%201%0A%09targetDate%20%3D%20Calendar%2Ecurrent%2EdateByAddingDateComponents%28today%2Cdc%29%0A%09fday%20%3D%20win%2EforecastDayForDate%28targetDate%29%0A%09if%28fday%2EbadgeCount%20%3E%200%29%7B%0A%09%09win%2EselectForecastDays%28%5Bfday%5D%29%0A%09%09break%0A%09%7D%0A%7D
Display First Active Forecast Day
 

var win = document.windows[0] win.perspective = Perspective.BuiltIn.Forecast var now = new Date() var today = Calendar.current.startOfDay(now) var dc = new DateComponents() var fdays = new Array() var fday, targetDate, i for (i = 0; i < 90; i++){ dc.day = i + 1 targetDate = Calendar.current.dateByAddingDateComponents(today,dc) fday = win.forecastDayForDate(targetDate) if(fday.badgeCount > 0){ win.selectForecastDays([fday]) break } }

And the previous script as a plug-in:

 
Show 1st Active Forecast Day
 

/*{ "type": "action", "targets": ["omnifocus"], "author": "Otto Automator", "identifier": "com.omni-automation.of.show-first-active-forecast-day", "version": "1.0", "description": "Will select the first forecast day in the Forecast perspective that has a positive badge count.", "label": "Show 1st Active Forecast Day", "shortLabel": "1st Active Day" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ // action code // selection options: tasks, projects, folders, tags, databaseObjects, allObjects var win = document.windows[0] win.perspective = Perspective.BuiltIn.Forecast var now = new Date() var today = Calendar.current.startOfDay(now) var dc = new DateComponents() var fdays = new Array() var fday, targetDate, i for (i = 0; i < 90; i++){ dc.day = i + 1 targetDate = Calendar.current.dateByAddingDateComponents(today,dc) fday = win.forecastDayForDate(targetDate) if(fday.badgeCount > 0){ win.selectForecastDays([fday]) break } } }); action.validate = function(selection, sender){ // validation code // selection options: tasks, projects, folders, tags, databaseObjects, allObjects return true }; return action; })();

NOTE: These examples use properties and functions of the shared Calendar class to calculate dates.