Development:Camino AppleScript Guide

DRAFT

This page is not complete.

The following page is a guide to the AppleScript features available in Camino 1.6, Camino 2.0, and Camino 2.1.

Camino 1.6 introduced significant improvements in AppleScript support over previous versions of Camino. Some of these improvements required incompatible changes to commands and properties. Many scripts will continue to work correctly in Camino 1.6 and later; however, scripts that use certain commands and properties, and text scripts (.applescript), will need changes in order to continue functioning.

New in Camino 2.1.3

• Bookmarks IDs
  • The id property is now supported for normal bookmarks and bookmark folders; the id is the bookmark item’s internal UUID, which is a string. Bookmarks and folders can now be referenced by their id and parent collection instead of their complete parent hierarchy. The Address Book, Bonjour, and Top Ten List collections do not have ids, nor do bookmarks contained by the Address Book or Bonjour collections (bookmarks in the Top Ten List collection return the same id as they do in whichever collection they normally appear). These bookmarks and bookmark folders without ids return the missing value keyword.

New in Camino 2.1.1

• Open URLs in background windows or tabs
  • The open location command now has an optional boolean loading in background parameter. When setting this parameter to true, Camino will open the URL in a tab after the current tab or a window behind the current window (if at least one tab or browser window is open), leaving focus on the current tab or window. Camino honors the user’s tab or window preference (the “Links opened by other applications” Tabs preference) when determining whether to open a tab or a window (if the user has specified the hidden-by-default “reuse current tab” setting for this preference, Camino will ignore that preference and always open new background tabs, if at least one tab is open, when using this parameter). The default behavior of open location remains opening URLs in foreground windows or tabs.
• Send a referrer when opening URLs
  • The open location command now has an optional using referrer parameter. If the URL to be opened is already displayed in a tab or window and a referrer URL is specified, Camino will not reload the existing tab but will instead open a new tab or window to load the requested URL using the supplied referrer URL.
• New error message for missing or empty direct parameter when opening URLs
  • When the open location command’s direct parameter (the URL to open) is missing or zero-length, Camino will now send an error message to the script. The direct parameter is no longer marked as optional in Camino’s AppleScript dictionary, but if one is not specified, Script Editor may attempt to substitute an implied “current application” direct parameter, which will also trigger the new error message.
• Reload browser windows and tabs
  • browser windows and tabs now respond to the reload command. If the tab or browser window’s current page can be reloaded, this command will reload the page. reload supports an optional boolean ignoring cache parameter; if true, Camino will “force reload” the page, ignoring the browser cache, just as the ⇧⌘R keyboard shortcut does. The default value of this parameter is false (just perform a normal reload).
• Online state (“offline mode”) is now scriptable
  • Camino’s application object now has an online property, which can be queried to determine if Camino is online or is operating in “offline mode”. Scripts can also take Camino online and offline by setting the value of the online property. (Note: No amount of setting online to true will allow Camino to load pages if there is no network connection!)

New in Camino 2.1

• Tabs
  • The non-standard title property has been deprecated and is no longer visible in the dictionary. Scripts should switch to the standard name property (which works consistently for application, window, browser window, and tab). The name property is backwards-compatible with Camino 2.0, so scripts targeting both Camino 2.1 and 2.0 can still safely migrate from the deprecated title property.

New in Camino 2.0

• Web page source and text
  • It is now possible to fetch the HTML source and displayed text of a browser window or tab using the source and text commands.
  • If a web page has a selection, it is also possible to return the HTML source and displayed text of just the selection using the selected source and selected text commands.
• Tabs
  • It is now possible to set the current tab property of each browser window in order to change the active tab in that browser window.
  • Tabs now support name as an alias for the title property. It is our intention to deprecate the non-standard title property in a future release.

New in Camino 1.6

• Browser Windows and Tabs
  • Browser windows can now be referenced specifically. Previously, Camino only exposed windows in general, including the Preferences window and the Downloads window in the same collection as browser windows.
  • Browser windows contain tabs.
  • Tabs can be addressed individually, exposing the title and URL of each page the user has open.
• Bookmarks
  • Bookmarks and bookmark folders can be read, added, and modified by AppleScripts. (But see the important note below.)
• WWW!OURL AppleEvent is deprecated
  • The old Spyglass WWW!OURL AppleEvent and its corresponding open url command have been deprecated. Scripts using these will not work in Camino 1.6, though they will work again in Camino 1.6.1. See below for a migration path.

  (Beginning with Dreamweaver CS5, Adobe no longer uses the deprecated WWW!OURL AppleEvent; see Bug 549680 Comment 10. Other applications should also cease using WWW!OURL and switch to the standard GURLGURL AppleEvent.)

Implementing Toolbar Script Items

• See Introducing Toolbar Scripts (Again) and Pimp Your Toolbar for more information.

Anomalies in the Camino AppleScript Dictionary

• Making new tabs or browser windows

  Although the make command is present, it is currently not possible to make new tab or make new browser window. For technical information about the reasons for this, see this blog post (Bug 395711, Bug 395712).

   

  If a user has “Links opened by other applications” checked (in the Tabs preference pane), it is possible to use open location "about:blank" to fake opening a new tab and then use set URL of current tab of front browser window to load the desired URL.

   

  If you do not mind using (and requiring your users to enable) UI Scripting, it is possible to use that method to create a new browser window (or new tab, but the previous workaround is simpler for the default state in Camino 2.1 and above).

  --Requires UI Scripting; use a routine to ensure UI Scripting is enabled.
  --MacTech has a good sample routine here:
  --http://www.mactech.com/articles/mactech/Vol.21/21.06/UserInterfaceScripting/index.html
  
  --Needed if the script is not run as a toolbar script
  tell application "Camino" to activate
  
  tell application "System Events"
  	tell process "Camino"
  		keystroke "n" using {command down}
  	end tell
  end tell

  Allow some time for the command to be created and processed before attempting to use the new browser window (or new tab); then use set URL of current tab of front browser window to load the desired URL.
  N.B. Generally, UI Scripting will hang Camino and/or cause script timeouts when used it toolbar scripts (see below); however, the keystroke method does not access any Camino UI objects and thus is safe to use.

• Certain items present in the Standard Suite will compile but are not implemented in Camino at this time (Bug 394581).
• browser window 0 and tab 0 resolve to a browser window/tab (browser window/tab 1) but should not (Bug 395716).
• If the user has enabled the “closing windows or quitting with multiple pages open” warnings, these alerts will also fire when AppleScripts attempt to perform these actions. There is currently no way for the script to disable these alerts on a case-by-case basis (Bug 391684).
• “Phantom” windows caused by tooltips (one phantom window per tab, so long as the tab is open) can show up in the count of windows (Bug 437802).
• Once the Preferences window has been opened during a browser session, it will show up in the list of windows, even if it is no longer open (Bug 437802 Comment 5).
• Using UI Scripting to access Camino’s UI can cause toolbar scripts to take forever, time out, or hang Camino. If you need to use UI Scripting to access Camino UI, run your script from the Script menu instead of as a toolbar script (Bug 448992).
• As of Camino 2.1.1, it now possible to reload a tab or browser window (Bug 557057). However, if your scripts still need to support Camino 2.1, 2.0.x or 1.6.x, the following script will provide similar functionality:

  tell application "Camino"
      set theURL to URL of current tab of browser window 1
      open location theURL
  end tell

• The visit count property of bookmarks was accidentally broken in Camino 2.1 (Bug 724204). Camino 2.1.1 resolved this problem.

Migrating Scripts from Camino 1.5 to Camino 1.6

• The Get URL command has been replaced by open location. Compiled scripts should handle this change automatically in most cases.
• The open url command (and its corresponding «event WWW!OURL») has been deprecated. Scripts should use open location instead. Any compiled scripts using this event will re-resolve to DeprecatedOpenURL terminology when opened in ScriptEditor with Camino 1.6.1 and later, and those instances should be changed manually to use open location to ensure compatibility with future versions of Camino. (Scripts using open url or «event WWW!OURL» will fail in Camino 1.6 but will work again in Camino 1.6.1.)
• The window class now properly refers to all open windows (including the Downloads and Preferences windows). To target a browser window, use browser window instead.