×

Folders

Folders provide a convenient mechanism for organizing your projects. Each folder may contain other folders and projects, and you copy and move their contents between folders.

Class Functions

Using the byIdentifier() method to locate a folder using the value of its primaryKey property (object ID):

Locating Folder by ID


Folder.byIdentifier('a0UDF6AROY8') //--> [object Folder: Home Renovation]

Using the flattenedFolders property of the Database class to return an object reference to the folder identified by name:

Locating 1st Instance of Folder by Name


var fldr = flattenedFolders.byName('Home Renovation') if(fldr){ console.log(fldr.id.primaryKey) //--> "a0UDF6AROY8" }

Instance Properties

Here are the properties of an instance of the Folder class:

Using the flattenedProjects property of the Folder class to iterate all projects within a specified folder:

Iterating All Projects in a Folder


var folderName = 'Home Renovation' var fldr = flattenedFolders.byName(folderName) if(fldr){ fldr.flattenedProjects.forEach(project => { // process project }) }

Folder.Status Class

The value for the status property of the Folder class:

Dropping a Folder


var folder = folderNamed("Folder A") if(folder){folder.status = Folder.Status.Dropped}

Creating Folders

New folders are created using the standard Javascript new item constructor, passing in values for the name and optinal insertion position parameters:

omnifocus://localhost/omnijs-run?script=try%7Bfldr%20%3D%20new%20Folder%28%22AAPL%22%2C%20library%2Ebeginning%29%0Atitles%20%3D%20%5B%221st%20Q%22%2C%222nd%20Q%22%2C%223rd%20Q%22%2C%224th%20Q%22%5D%0Atitles%2EforEach%28title%20%3D%3E%20new%20Folder%28title%2C%20fldr%29%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
Creating Folders within a Folder
 

var fldr = new Folder("AAPL", library.beginning) var titles = ["1st Q","2nd Q","3rd Q","4th Q"] titles.forEach(title => new Folder(title, fldr))
New Folder on iPad

An example script for creating a new top-level folder for each month of the year:

omnifocus://localhost/omnijs-run?script=try%7Bvar%20locale%20%3D%20%22en%2Dus%22%0Avar%20monthNames%20%3D%20%5B%5D%0Afor%20%28i%20%3D%200%3B%20i%20%3C%2012%3B%20i%2B%2B%29%20%7B%0A%09var%20objDate%20%3D%20new%20Date%28%29%0A%09objDate%2EsetDate%281%29%0A%09objDate%2EsetMonth%28i%29%0A%09monthName%20%3D%20objDate%2EtoLocaleString%28locale%2C%7Bmonth%3A%22long%22%7D%29%0A%09monthNames%2Epush%28monthName%29%0A%7D%0AfolderNames%20%3D%20folders%2Emap%28fldr%20%3D%3E%20%7Breturn%20fldr%2Ename%7D%29%0AmonthNames%2EforEach%28%28month%29%3D%3E%7B%0A%09if%28%21folderNames%2Eincludes%28month%29%29%7Bnew%20Folder%28month%29%7D%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
Folder for Each Month
 

var locale = "en-us" var monthNames = [] for (i = 0; i < 12; i++) { var objDate = new Date() objDate.setDate(1) objDate.setMonth(i) monthName = objDate.toLocaleString(locale,{month:"long"}) monthNames.push(monthName) } var folderNames = folders.map(fldr => {return fldr.name}) monthNames.forEach((month)=>{ if(!folderNames.includes(month)){new Folder(month)} })

Folder Instance Functions

Here are the functions that can be applied to instances of the Folder class:

Here’s a script that processes the net task of a specified project located within a specified top-level directory:

Next Task for Specified Folder Project


var project = folderNamed("Fall Festival").projectNamed("Setup To-Do List") if(project){ task = project.nextTask // processing statements }

Folder Hierarchy

Folders may contain projects and other folders. Contained folders may also contain folders and projects, and so on.

Here's a macOS-only function that will return the path string to the selected library item (folder or project), for example:

Top-Level Folder > Secondary-Level Folder > Third-Level Folder > Selected Project

Hierarchy Path for Selected Folder or Project


function pathToSelectedLibraryItem(){ if ( document.windows[0].perspective === Perspective.BuiltIn.Projects && document.windows[0].sidebar.selectedNodes.length === 1 ) { var item = document.windows[0].sidebar.selectedNodes[0].object var pathItems = [item.object.name] var lvl = item.level if(lvl > 1){ do { item = item.parent lvl = item.level pathItems.unshift(item.object.name) } while (lvl > 1) } var itemHeirarchy = pathItems.join(" > ") return itemHeirarchy } return null }