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:

• badgeCountsIncludeDeferredItems (Boolean) • Determines whether or not badges on Forecast days include items that are not yet available.

Instance properties for an instance of the ForecastDay class:

• badgeCount (Number r/o) • The number of available tasks on this forecast day.

• date (Date r/o) • The date this forecast day represents. If this day’s kind is Past or DistantFuture the date returned will be years from the current time.

• deferredCount (Number r/o) • The number of remaining deferred tasks on this forecast day.

• kind (ForecastDay.Kind r/o) • XXXXX

• name (String r/o) • XXXXX

Instance functions for the ForecastDay class:

• badgeKind() → (ForecastDay.Status) • The status of the badge on this forecast day.

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:

• Day (ForecastDay.Kind r/o) • The node represents a specific day in the Forecast week or month grid.

• DistantFuture (ForecastDay.Kind r/o) • The node represents all days more than a year from now.

• FutureMonth (ForecastDay.Kind r/o) • The node represents a month within the next year.

• Past (ForecastDay.Kind r/o) • The node represents all days in the past.

• Today (ForecastDay.Kind r/o) • The node represents today.

• all (Array of ForecastDay.Kind r/o) • An array of all items of this enumeration. Used in the creation of plug-in forms.

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:

• Available (ForecastDay.Status r/o) • There is at least one available task on the node’s day, but no task is due soon or overdue. The node’s badgeCount is the number of available tasks.

• DueSoon (ForecastDay.Status r/o) • There is at least one available task on the node’s day, and at least one task due that day is due soon, but no tasks due that day are overdue. The node’s badgeCount is the number of available tasks.

• NoneAvailable (ForecastDay.Status r/o) • There are no available tasks on the node’s day. The node’s badgeCount is guaranteed to be zero.

• Overdue (ForecastDay.Status r/o) • There is at least one available task on the node’s day, and at least one task due that day is overdue. The node’s badgeCount is the number of available tasks.

• all (Array of ForecastDay.Status r/o) • An array of all items of this enumeration. Used in the creation of plug-in forms.

Forecast-Related Window Instance Functions

• forecastDayForDate(date:Date) → (ForecastDay) • Returns a ForecastDay object that encompasses date. This will throw an error if Forecast is not the current perspective in this window.

• selectForecastDays(days:Array of ForecastDay) → ( ) • Selects the days in the Forecast picker represented by days. On iOS, only the first day is selected, and the rest are ignored. This will throw an error if Forecast is not the current perspective in this window.

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:

Show Forecast Day for Date
Copy Run Script

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

Script for showing today’s forecast:

Show Today’s Forecast
Copy

win = document.windows[0]
win.perspective = Perspective.BuiltIn.Forecast
date = new Date().setHours(0, 0, 0)
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:

New Window (Tab) for Today’s Forecast
Copy Run Script Install Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.new-window-for-today-forecast",
	"version": "1.1",
	"description": "Creates a new window (tab on macOS) displaying the forecast for the current day.",
	"label": "Add Today’s Forecast",
	"shortLabel": "Add Today’s Forecast",
	"paletteLabel": "Add Today’s Forecast",
	"image": "calendar"
}*/
(() => {
	const action = new PlugIn.Action(async function(selection, sender){
		targetDate = new Date()
		if(app.platformName == 'macOS'){
			var windowPromise = document.newTabOnWindow(document.windows[0])
		} else {
			var windowPromise = document.newWindow()
		}
		windowPromise.then(function(win){
			win.perspective = Perspective.BuiltIn.Forecast
			fday = win.forecastDayForDate(targetDate)
			win.selectForecastDays([fday])
		})
	});

	action.validate = function(selection, sender){
		return true
	};
	
	return action;
})();

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

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:

Select Forecast for 7th Day from Today
Copy Run Script

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:

Select Range of Forecast Dates
Copy Run Script Download Plug-In

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:

Display First Active Forecast Day
Copy Run Script

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
Copy Download Plug-In Install Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automator",
	"identifier": "com.omni-automation.of.show-first-active-forecast-day",
	"version": "1.1",
	"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",
	"paletteLabel": "1st Active Day",
	"image": "calendar"
}*/
(() => {
	const action = new PlugIn.Action(function(selection, sender){
		win = document.windows[0]
		win.perspective = Perspective.BuiltIn.Forecast
		now = new Date()
		today = Calendar.current.startOfDay(now)
		dc = new DateComponents()
		fdays = new Array()
		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){
		return true
	};
	
	return action;
})();

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