×

URL

A URL (Uniform Resource Locator) is a string of text-characters used to identify a file or resource, either locally on the computing device, or on a network or the internet.

An essential component of HTML links, a URL is composed of text segments separated by forward-slash characters, like this URL that references an image file on an internet server:

https://omni-automation.com/wind/18207.JPG

In Omni Automation, URLs are used to reference local or networked files, often for importing into documents.

String to URL

You can create an instance of a URL object by calling the fromString() method on the URL class. This function takes the URL string as its direct parameter. In the example below, a URL string is converted into a URL object stored in the variable: aURL

URL Object from String


urlA = URL.fromString("https://omni-automation.com/wind/18207.JPG") //--> [object URL: https://omni-automation.com/wind/18207.JPG] {string: "https://omni-automation.com/wind/18207.JPG", toObject: [object URL: https://omni-automation.com/wind/18207.JPG]}

Incorporating the relativeToURL property:

Derive URL from Base URL


baseURL = URL.fromString("https://www.omnigroup.com") linkURL = URL.fromString("/blog", baseURL) linkURL.string //--> https://www.omnigroup.com/blog

Here’s a script that use the documentsDirectory property to generate a URL to the user’s Pictures folder (macOS):

Derive URL from Path


homeName = URL.documentsDirectory.pathComponents[2] URL.fromPath(`/Users/${homeName}/Pictures/`, true)

Class Properties

Instance Properties

The string instance property of the URL class can be used to extract a URL string from the URL object:

URL String from URL Object


aURL.string //--> "https://omni-automation.com/gfx/18207.jpg"

See documentation on the URL.QueryItem class for more information regarding URL components.

URL Instance Functions

Here's an example of using URL editing functions to generate a second URL instance that uses the same directory as the first URL instance:

URL Edit Functions


urlA = URL.fromString("https://omni-automation.com/wind/18207.JPG") //--> [object URL: https://omni-automation.com/wind/18207.JPG] {string: "https://omni-automation.com/wind/18207.JPG", toObject: [object URL: https://omni-automation.com/wind/18207.JPG]} containingDirectoryURL = urlA.deletingLastPathComponent() urlB = containingDirectoryURL.appendingPathComponent("16704.JPG") //--> [object URL: https://omni-automation.com/wind/16704.JPG] {string: "https://omni-automation.com/wind/16704.JPG", toObject: [object URL: https://omni-automation.com/wind/16704.JPG]}

The open( ) Instance Function

The open( ) function of the URL class is used to open the specified URL object.

Using the open( ) function to display a webpage:

Open Webpage


var aURL = URL.fromString('https://omni-automation.com') aURL.open()

Here’s the open( ) function used to pass text to a new BBEdit document. Note that the open( ) function may be appended to URL creation statement since the result of the statement is an instance of the URL class:

New BBEdit Text Document


var textToPass = encodeURIComponent("How Now Brown Cow") URL.fromString('x-bbedit://new-document/?text=' + textToPass).open()

And here’s the open() function used to pass text to a new Textastic document:

New Textastic Document


var textToPass = encodeURIComponent("How Now Brown Cow") URL.fromString('textastic://x-callback-url/new?text=' + textToPass).open()

And here’s an example of using the call() function to pass text to a new Drafts document:

New Drafts Document


var urlStr = "drafts5://x-callback-url/create?text=" var textToPass = encodeURIComponent("How now brown cow.") URL.fromString(urlStr + textToPass).open()

NOTE: Because of the security protocols in iOS, iPadOS, and macOS, the open( ) function may be blocked from use with files not directly under control of the hosting application.

A URL for triggering a new entry dialog in the Contacts app (macOS):

New Address Book Entry


URL.fromString("addressbook://Omni%20Automation?edit").open()

URL to String

When working with URLs in your scripts, you may wish to extract the name of the file or resource from the URL object. This is accomplished by extracting the URL string from the URL object by accessing the value of its “string” property.

Once you retrieved the URL string from the URL object, you can use standard JavaScript tools for deriving the name, as shown in this example:

Get Resource Name from URL (Old Way)


var aURL = URL.fromString('https://omni-automation.com/gfx/18207.jpg') var urlString = aURL.string var resourceName = urlString.substr(urlString.lastIndexOf('/') + 1) //--> "18207.jpg"

A better mechanism for deriving the name of a resource from its url is to use the lastPathComponent property of the URL class:

Get Resource Name from URL (Best Way)


var aURL = URL.fromString('https://omni-automation.com/gfx/18207.jpg') var resourceName = aURL.lastPathComponent //--> "18207.jpg"

The currentAppScheme Property

Omni Automation script links begin with a schema that identifies the target Omni application. For example, here is a link that targets a task in OmniFocus:

omnifocus:///task/ieEZbhmwQLk

However, should you have multiple copies of an Omni application installed, such as both the standard and enterprise editions, you can use the currentAppScheme property of the URL class to derive the exact schema targeting the current running Omni application, as in this example script that generates a link to the selected OmniFocus task:

Generating a URL Link to a Task


var selectedTask = document.windows[0].selection.tasks[0] var taskID = selectedTask.id.primaryKey var appSchema = URL.currentAppScheme var taskLinkStr = appSchema + "://localhost/task/" + taskID //-> "com.omnigroup.OmniFocus3://localhost/task/ieEZbhmwQLk"

The value of the currentAppScheme property is the identifier string for current Omni application.

URL of a Plug-In Resource

Resource files place within Omni plugins are referenced using URLs. To derive the URL of a plugin resource file, use the following technique of identifying the host plugin by its identifier string, and then calling the resourceNamed() method on the plugin object:

URL of a Plug-In Resource


var plugin = PlugIn.find("com.omni-automation.og.example-plug-in") var resourceName = "Australia.png" var aURL = plugin.resourceNamed(resourceName)

Accessing the value of the returned URL object’s “string” property will be a file URL string pointing to the indicating file on disk:

file:///Users/sal/Library/Containers/com.omnigroup.OmniGraffle7/Data/Library/Application%20Support/PlugIns/SalsSnippets.omnigrafflejs/Resources/Australia.png

 

Storing and Retrieving Data

Using the documentsDirectory property, data can be written to and retrieved from the Omni app’s documents folder without the need for user interaction. This provides an excellent mechanism for sharing data between plug-ins.

Here are functions for reading and writing data in JSON format:

Storing JSON Data in App Directory

function storeDataInAppFolder(dataObj, fileName, shouldOpenFolder){
	try {
		dataObjStr = JSON.stringify(dataObj)
		data = Data.fromString(dataObjStr)
		folderURL = URL.documentsDirectory
		fileURL = folderURL.appendingPathComponent(fileName)
		wrapper = FileWrapper.withContents(fileName, data)
		wrapper.write(fileURL, [FileWrapper.WritingOptions.Atomic], null)
		if(shouldOpenFolder && app.platformName === "macOS"){
			folderURL.open()
		}
	}
	catch(err){
		new Alert(err.name, err.message).show()
	}
}
Calling the Function


dataObj = {"name":"Samantha", "id":"com.apple.speech.synthesis.voice.samantha.premium", "rate":0.45} storeDataInAppFolder(dataObj, "voice-data.json", true)
Retrieving Data from App Directory


async function retrieveDataInAppFolder(fileName){ try { folderURL = URL.documentsDirectory fileURL = folderURL.appendingPathComponent(fileName) request = URL.FetchRequest.fromString(fileURL.string) request.method = 'GET' request.cache = "no-cache" response = await request.fetch() responseCode = response.statusCode if (responseCode >= 200 && responseCode < 300){ dataObj = JSON.parse(response.bodyString) return dataObj } else { throw { name: "Retrieval Error", message: `The request responded with ${responseCode} error.` } } } catch(err){ new Alert(err.name, err.message).show() } }
Calling the Function


dataObj = retrieveDataInAppFolder("voice-data.json") console.log(JSON.stringify(dataObj))