▼Net:   Networking Libraries
On this page:
send-url
send-url/  file
send-url/  contents
send-url/  mac
external-browser
browser-preference?
unix-browser-list
  top  ← prev  up  next → 

5 Send URL: Opening a Web Browser

 (require net/sendurl) package: net-lib
Provides send-url for opening a URL in the user’s chosen web browser.

See also browser/external, which requires racket/gui, but can prompt the user for a browser if no browser preference is set.

procedure

(send-url str    
  [separate-window?    
  #:escape? escape?]) → void?
  str : string?
  separate-window? : any/c = #t
  escape? : any/c = #t
Opens str, which represents a URL, in a platform-specific manner. For some platforms and configurations, the separate-window? parameter determines if the browser creates a new window to display the URL or not.

On Windows, send-url normally uses shell-execute to launch a browser. (If the URL appears to contain a fragment, it may use an intermediate redirecting file due to a bug in IE7.)

On Mac OS, send-url calls send-url/mac.

On Unix, send-url uses a user-preference, or when none is set, it will look for a known browser. See the description of external-browser for details.

If escape? is true, then str is escaped (by UTF-8 encoding followed by “%” encoding) to avoid dangerous shell characters: single quotes, double quotes, backquotes, dollar signs, backslashes, non-ASCII characters, and non-graphic characters. Note that escaping does not affect already-encoded characters in str.

On all platforms, external-browser parameter can be set to a procedure to override the above behavior — the procedure will be called with the url string.

procedure

(send-url/file path    
  [separate-window?    
  #:fragment fragment    
  #:query query]) → void?
  path : path-string?
  separate-window? : any/c = #t
  fragment : (or/c string? false/c) = #f
  query : (or/c string? false/c) = #f
Similar to send-url (with #:escape? #t), but accepts a path to a file to be displayed by the browser, along with optional fragment (with no leading #) and query (with no leading ?) strings. Use send-url/file to display a local file, since it takes care of the peculiarities of constructing the correct file:// URL.

The path, fragment, and query arguments are all encoded in the same way as a path provided to send-url, which means that already-encoded characters are used as-is.

procedure

(send-url/contents contents    
  [separate-window?    
  #:fragment fragment    
  #:query query    
  #:delete-at seconds]) → void?
  contents : string?
  separate-window? : any/c = #t
  fragment : (or/c string? false/c) = #f
  query : (or/c string? false/c) = #f
  seconds : (or/c number? false/c) = #f
Similar to send-url/file, but it consumes the contents of a page to show and displays it from a temporary file.

When send-url/content is called, it scans old generated files (this happens randomly, not on every call) and removes them to avoid cluttering the temporary directory. If the #:delete-at argument is a number, then the temporary file is more eagerly removed after the specified number of seconds; the deletion happens in a thread, so if Racket exits earlier, the deletion will not happen. If the #:delete-at argument is #f, no eager deletion happens, but old temporary files are still deleted as described above.

procedure

(send-url/mac url [#:browser browser]) → void?

  url : string?
  browser : (or/c string? #f) = #f
Like send-url, but only for use on a Mac OS machine.

The optional browser argument, if present, should be the name of a browser installed on the system. For example,

(send-url/mac "http://www.google.com/" #:browser "Firefox")

would open the url in Firefox, even if that’s not the default browser. Passing #f means to use the default browser.

This function looks in "com.apple.launchservices.secure.plist" in the user’s home directory for a LSHandlerURLScheme key for either http or https and then, looks for a LSHandlerRoleAll key that is one of a list of known browsers. If it finds such a browser, it uses the AppleScript command tell application ... to open location to send the url to the browser. Otherwise, it uses just open location to send the url to the browser.

parameter

(external-browser) → browser-preference?

(external-browser cmd) → void?
  cmd : browser-preference?
A parameter that can hold a procedure to override how a browser is started, or #f to use the default platform-dependent command.

On Unix, the command that is used depends on the 'external-browser preference. If the preference is unset, send-url uses the first of the browsers from unix-browser-list for which the executable is found. Otherwise, the preference should hold a symbol indicating a known browser (from the unix-browser-list), or it a pair of a prefix and a suffix string that are concatenated around the url string to make up a shell command to run. In addition, the external-browser paremeter can be set to one of these values, and send-url will use it instead of the preference value.

Note that the URL is encoded to make it work inside shell double-quotes: URLs can still hold characters like #, ?, and &, so if the external-browser is set to a pair of prefix/suffix strings, they should use double quotes around the url.

If the preferred or default browser can’t be launched, send-url fails. See get-preference and put-preferences for details on setting preferences.

procedure

(browser-preference? a) → boolean?

  a : any/c
Returns #t if v is a valid browser preference, #f otherwise. See external-browser for more information.

value

unix-browser-list : (listof symbol?)

A list of symbols representing Unix executable names that may be tried in order by send-url. The send-url function internally includes information on how to launch each executable with a URL.

  top  ← prev  up  next →