This function is primarily used to open a URL in a browser. It can also be used to communicate with other applications via URL callbacks and it can download data from a URL.
The supplied URL may contain any of the escape sequences described in Escape Sequences.
An attempt is made to automatically % escape the URL. You do not have to worry about spaces in the URL. However, URLs consist of various components and only a single text field is supplied. Further, via the inclusion of named and track variables, portions of the URL can be inserted. There is no way of determining which components are query components which may contain characters which must be additionally escaped. For that reason the URL field is treated as a list of components separated by the default list delimiter (\~). Any list component which might contain characters such as & which must be escaped are prefixed by a % character. The prefixing % character is a token and is not included in the final text. for example the following wikipedia URL passes an artist name as a parameter. Artist names may contain any characters:
https://en.wikipedia.org/w/api.php?format=json&action=query&prop=extracts&exintro=&explaintext=&titles=\~%\<name>\~&redirects
The list contains three components:
https://en.wikipedia.org/w/api.php?format=json&action=query&prop=extracts&exintro=&explaintext=&titles=
and
%\<name>
and
&redirects
The first and third list components are static. Normal URL escaping is applied. The second list component is a named variable called name. It is entirely possible that the named variable would contain characters which must be escaped. By prefixing the list component with a % character, the list component will have characters invalid in a query % escaped.
Note that it may be possible that the escaping may go too far. For example many sites do not accept a URL fragment indicator (#) that is escaped for security reasons. If a list component is prefixed by %%, no escaping will take place on the list item. Careful here!. Example:
https://2manyrobots.com/actionstmt.html\~%%#\~fragment
For total control over the escaping process you can always use the Re-encode statement to escape each component of the URL and then disable escaping completely on the Open URL statement. example:
\~%%\<manually escaped URL in named variable>
The function is only executed once per set of files while executing stepwise.
This is the typical usage. The Get data option must not be set and the specified URL must not contain a \?ou escape sequence.
By default, if there are any errors constructing the properly escaped URL or in launching the URL, they will be displayed via the UI. If you want to disable the reporting select the Silent option. The action test state is always set to true if the URL was successfully launched. Otherwise it will be set to false. Note, it is possible that the OS will issue its own error message even if Silent is set.
If the action being run is an action downloaded from the resources web page, a url specified as ? will open the action's resource documentation. The following form is also accepted ?addon#name. addon if present is appended to the primary page name. #name, if present, is treated as a page fragment identifier.
You can process URLs with callbacks. To process a URL with a callback specify a \?ou escape sequence in the URL. The sequence is on the Insert Yate Escape Sequences>Character Sequences context menu. The sequence will automatically be substituted for an appropriate callback descriptor.
If for any reason the callback is not called, you will have to cancel the action. If the callback is called, all properly escaped parameters will be stored as a key value list in named variable Open URL Callback Data. The default delimiters are used. \~ for item delimiters and \k to separate keys from values.
The action test state cannot be used to determine the success of the callback. You must examine the data in named variable Open URL Callback Data.
The following is an example used to convert a single file whose path is in named variable Loc to AIFF by the Permute 3 media converter.
Open URL 'permute://\<Loc>?action=convert&preset=AIFF&source=Yate&callback=\?ou', silent
Set named variable 'status' to the value of key 'success'
in the list in named variable 'Open URL Callback Data' (delimiter "⏎" separator "≔")
Test if named variable 'status' is equal to "true" (Set result)
Set named variable 'status' to "\a1"
if true
Set named variable 'path' to the value of key 'file'
in the list in named variable 'Open URL Callback Data' (delimiter "⏎" separator "≔")
else
Set named variable 'path' to empty
endif
...
Test if named variable 'status' is true (Set result)
if true
' The converted file's location is contained in name variable Path
else
' Failure
endif
For a variety of purposes you might want to extract the data returned by a URL. You can do so by setting the Get data option. Note that this option is ignored if the URL contains a callback marker (\?ou).
The data downloaded by the URL can be saved to the Open URL Callback Data named variable or to a file. If named variable Open URL Data File is empty, the downloaded data will be saved to named variable Open URL Callback Data. If named variable Open URL Data File is not empty, it must be an absolute path to a file which must have a filename extension. When writing the file intermediate path components will be created.
If you want to set HTTP headers you can do so by storing them in named variable Open URL Headers and by setting the headers popup to Open URL Headers. The headers must be specified as a key value list where keys are separated from values with the List Key-Value delimiter (\k). Headers are separated from each other by the Default List delimiter (\~). Any malformed header is silently tossed.
Six header schemes are reserved for use by 2ManyRobots. These schemes may generate or fetch custom information. If a scheme is not implemented it will be ignored.
The action test state cannot be used to determine the success of the function. Named variable Data Source Access Error will be empty (or 0 depending on how you test), if no errors occurred.
If you set Get data and As artwork, the expectation is that the downloaded data defines an artwork item. The artwork item will be added to all active files (if not already present).
The downloaded artwork will have a picture type of Cover Front and it's description will be the contents of the description field. The description field may contain any of the escape sequences described in Escape Sequences. Note that the field is unescaped for every file receiving the artwork.
The action test state cannot be used to determine the success of the function. Named variable Data Source Access Error will be empty (or 0 depending on how you test), if no errors occurred.