The _browser.ss_ library in the "browser" collection provides the following procedures and classes for parsing and viewing _HTML_ files. The "htmltext.ss" library (described further below) provides a simplified interface for rendering to a subclass of the MrEd text% class. The "external.ss" library (described even further below) provides utilities for launching an external browser (such as Mozilla). The browser (and htmltext) supports basic HTML commands, plus special Scheme hyperlinks of the form .... When the user clicks on such a link, the string `sexpr' is parsed as a Scheme program and evaluated. Since `sexpr' is likely to contain Scheme strings, and since escape characters are difficult for people to read, a vertical bar (|) character in sexpr is converted to a double-quote (") character before it is parsed. Thus, Nowhere creates a "Nowhere" hyperlink, which executes the Scheme program "This goes nowhere." The value of that program is a string. When a Scheme hyperlink returns a string, it is parsed as a new HTML document. Thus, where the use clicks on "Nowhere", the result is a new page that says "This goes nowhere." The browser also treats comment forms containing MZSCHEME=sexpr specially. Whereas the ... form executes the expression when the user clicks, the MZSCHEME expression in a comment is executed immediately during HTML rendering. If the result is a string, the comment is replaced in the input HTML stream with the content of the string. Thus, inserts the path of the current working directory into the containing document (and "Here" is boldfaced). If the result is a snip instead of a string, it replaces the comment in the document. Other types of return values are ignored. If the html file is being accessed as a "file:" url, the current-load-relative-directory parameter is set to the directory during the evaluation of the mzscheme code (in both examples). The Scheme code is executed through `eval'. The MZSCHEME forms are disabled unless the web page is a file: url that points into the `doc' collection. ---------------------------------------- > (open-url url) - Opens the given url (either a string, url record, or port) in a vanilla browser frame and returns the frame. The frame is an instance of hyper-frame%. ----------------------------------------- The html-img-ok parameter controls image rendering for the browser. > (html-img-ok on?) - Sets the value of the parameter to on? > (html-img-ok) - Returns the current value of the parameter The html-eval-ok parameter controls the evaluation of `MZSCHEME=' tags. If the parameter is #f, they are disabled. > (html-eval-ok on?) - Sets the value of the parameter to on? > (html-eval-ok) - Returns the current value of the parameter ------------------------------------------------------------ > (hyper-frame-mixin frame%) - Extends the given frame% class. The result of this mixin takes one argument, a url string. During the initialization of objects created from this mixin, the code shows the frame and visits the url. > get-hyper-panel% :: (send hyper-frame get-hyper-panel%) returns the class that is instantiated with the frame is created. Must be a panel with hyper-panel-mixin mixed in. Defaults to just returning hyper-panel%. > get-hyper-panel :: (send hyper-frame get-hyper-panel) - returns the hyper panel in this frame ---------------------------------------- > hyper-frame% = (hyper-frame-mixin frame%) ------------------------------------------------------------ > (hyper-no-show-frame-mixin frame%) - Extends the given frame% class. This is the same as the hyper-frame-mixin, except that it doesn't show the frame and the initialization arguments are unchanged. ---------------------------------------- > hyper-no-show-frame% = (hyper-frame-no-show-mixin frame%) ---------------------------------------- > (hyper-text-mixin text%) - Extends the given text% class. The initialization arguments are extended with a four new first arguments: a url or a port to be loaded into the text% object, a top-level-window or #f to use as a parent for status dialogs, a progress procedure used as for `get-url', and either #f or a post string to be sent to a web server (technically changing the GET to a POST). Sets the autowrap-bitmap to #f. An instance of a (hyper-text-mixin text%) class should be displayed only in an instance of a class created with `hyper-canvas-mixin' (described below). The mixin adds the following methods: > map-shift-style :: (send o map-shift-style start end shift-style) Maps the given style over the given range > make-link-style :: (send o make-link-style start end) Changes the style for the given range to the link style > get-url :: (send o get-url) Returns the URL displayed by the editor, or #f if there is none. > get-title :: (send o get-title) > set-title :: (send o set-title string) Gets or sets the page's title > hyper-delta A style-delta% object; override it to set the link style > add-tag ::(send o add-tag name-string pos) Installs a tag. > find-tag :: (send o find-tag name-string/number) Finds the location of a tag in the buffer (where tags are installed in HTML with ) and returns its position. If `name' is a number, the number is returned (assumed to be an offset rather than a tag). Otherwise, if the tag is not found, #f is returned. > remove-tag :: (send o remove-tag name) Removes a tag. > post-url :: (send o post-url string[url] post-data-bytes) Follows the link in the string. post-data-bytes defaults to #f > add-link :: (send o add-link start end url-string) Installs a hyperlink. > add-scheme-callback :: (send o add-scheme-callback start end scheme-string) Installs a Scheme evaluation hyperlink. > add-scheme-callback :: (send o add-thunk-callback start end thunk) Installs a thunk-based hyperlink. > eval-scheme-string :: (send o eval-scheme-string string) Called to handle the ... tag and comments (see above). Evaluates the string; if the result is a string, it is opened as an HTML page. > reload :: (send o reload) Reloads the current page. > remap-url :: (send o remap-url url) -> url or string or #f When visiting a new page, this method is called to remap the url. The remapped url is used in place of the original url. If this method returns #f, the page doesn't go anywhere. This method may be killed (if the user clicks the ``stop'' button) ---------------------------------------- > hyper-text% = (hyper-text-mixin text:keymap%) This is an extension of the keymap class, to support standard key bindings in the browser window. It adds the following method: > get-hyper-keymap :: (send o get-hyper-keymap) -> keymap% object Returns a keymap suitable for frame-level handling of events to redirect page-up, etc. to the browser canvas. ---------------------------------------- > (hyper-canvas-mixin editor-canvas%) - Extends the given editor-canvas% class. The initialization arguments are unchanged. The canvas's parent should be an instance of a class derived with `hyper-panel-mixin' (described below). The mixin adds the following methods: > get-editor% :: (send o get-editor%) Returns the class used to implement the editor in the browser window. It should be derived from hyper-text% and should pass on the initialization arguments to hyper-text% The dynamic extent of the initialization of this editor is called on a thread that may be killed (via a custodian shutdown) In that case, the editor in the browser's editor-canvas may not be an instance of this class. > current-page :: (send o current-page) Returns a representation of the currently displayed page, which includes a particular editor and a visible range within the editor. > goto-url :: (send o goto-url url relative-to-url [progress-proc] [post-data-bytes #f]) Changes to the given url, loading it by calling the `make-editor' method. If `relative-to-url' is not #f, it must be a URL for resolving `url' as a relative URL. `url' may also be a port, in which case, `relative-to-url' must be #f. The `progress-proc' procedure is called with a boolean at the point where the URL has been resolved and enough progress has been made to dismiss any message that the URL is being resolved. The procedure is called with #t if the URL will be loaded into a browser window, #f otherwise (e.g., the user will save the URL content to a file). If `post-data-bytes' is a byte string instead of false, the URL GET is changed to a POST with the given data. > set-page :: (send o set-page page notify?) Changes to the given page. If `notify?' is not #f, the canvas's parent is notified about the change by calling its `leaving-page' method. > after-set-page :: (send o after-set-page) Called during `set-page'. Defaultly does nothing. ---------------------------------------- > hyper-canvas% = (hyper-canvas-mixin editor-canvas%) ---------------------------------------- > (hyper-panel-mixin area-container%) - Extends the given area container class. The initialization arguments are unchanged, but initialization creates controls and a hyper text canvas. The controls permit a user to move back and forth in the hypertext history. The mixin adds a initialization argument, info-line?, which is a boolean indicating whether the browser should contain a line to display special "DOCNOTE" tags in a page. Such tags are used primarily by the PLT documentation. The mixin adds the following instance variables: > make-canvas :: (send o make-canvas container) Creates the panel's hypertext canvas, an instance of a class derived using `hyper-canvas-mixin' (described above). This method is called during initialization. > get-canvas% :: (send o get-canvas%) Returns the class instantiated by make-canvas. It must be derived from hyper-canvas% > make-control-bar-panel :: (send o make-control-bar-panel container) Creates the panel's sub-container for the control bar containing the navigation buttons. If #f is returned, the panel will have no control bar. The default method instantiates horizontal-panel%. > rewind :: (send o rewind) Goes back one page, if possible. > forward :: (send o forward) Goes forward one page, if possible. > get-canvas :: (send o get-canvas) Gets the hypertext canvas. > on-navigate :: (send o on-navigate) Callback that is invoked any time the displayed hypertext page changes (either by clicking on a link in the canvas or by `rewind' or `forward' calls). > leaving-page :: (send o leaving-page page new-page) This method is called by the hypertext canvas to notify the panel that the hypertext page changed. The `page' is #f if `new-page' is the first page for the canvas. See also `page->editor' (described below). > filter-notes :: (send o filter-notes list-of-strings) Given the notes from a page as a list of strings (where each string is a note), returns a single string to print above the page. > reload :: (send o reload) Reloads the currently visible page by calling the reload method of the currently displayed hyper-text. ---------------------------------------- > hyper-panel% = (hyper-panel-mixin vertical-panel%) ---------------------------------------- > (editor->page editor) - Creates a page record for the given editor, suitable for use with the `set-page' method of hyper-canvas-mixin. > (page->editor page) - Extracts the editor from a page record. > (on-installer-run [proc]) - Parameter for a procedure to be invoked after the installer is run on a .plt file > (bullet-size [n]) - Parameter controlling the point size of a bullet ----------------------------------------- > image-map-snip% extends image-snip% init: html-text : (is-a?/c html-text<%>) Instances of this class behave like image-snip% objects, except they have a ... associated with them and when clicking on them (in the map) they will cause their init arg text to follow the corresponding link. > (send an-image-map-snip set-key key-string) Sets the key for the image map (eg, "#key"). > (send an-image-map-snip get-key) Returns the current key. > (send an-image-map-snip add-area shape-string list-of-numbers href-string) Registers the shape named by the shape-string whose coordinates are specified by the list-of-numbers to go to the href named href-string when that region of the image is clicked on. ----------------------------------------- The _browser-unit.ss_ library in the "browser" collection is a unitized version of the code documented above. It imports unit matching the following signatures: setup:plt-installer^ mred^ net:tcp^ (see "tcp-sig.ss" in the "net" collection) net:url^ (see "url-sig.ss" in the "url" collection) It exports the browser^ signature. ----------------------------------------- The _browser-sig.ss_ library in the "browser" collection defines the browser^ signature with all of the names listed above. ======================================== _htmltext.ss_ ======================================== > html-text<%> An interface that extends text% with the following methods: > get-url :: (send t get-url) --- returns a base URL used for building relative URLs, or #f if no base is available > set-title :: (send t set-title str) --- registers the title `str' for the rendered page > add-link :: (send t add-link start-pos end-pos url-string) --- registers a hyperlink for the given region in rendered page > add-tag :: (send t label pos) --- registers a tag at the given position in the rendered page > make-link-style :: (send t make-link-style start-pos end-pos) --- modifies the style of the rendered page from start-pos to end-pos to look like a hyperlink > add-scheme-callback :: (send t add-scheme-callback pos endpos code-string) --- registers a code-evaluating hyperlink for the given region > add-thunk-callback :: (send t add-scheme-callback pos endpos thunk) --- registers a thunk-invoking hyperlink for the given region > post-url :: (send t post-url url post-data-bytes) --- performs a post to the given `url' with the given post data ---------------------------------------- > (html-text-mixin text%-subclass) -> html-text<%> implementation Extends the given text% class with implementations of the html-text<%> methods. Hyperlinks are attached to clickbacks that use `send-url' (from the "sendurl.ss" library of the "net" collection). > (render-html-to-text input-port html-text<%>-obj load-img? eval-mz?) Reads HTML from `input-port' and renders it to `html-text<%>-obj'. If `load-img?' is false, then images are rendered as Xed-out boxes. If `eval-mz?' is false, then MZSCHEME hyperlink expressions and comments are not evaluated. ======================================== _external.ss_ ======================================== > (send-url str [separate-window? #t]) Like 'send-url' in (lib "sendurl.ss" "net"), but under Unix, the user is prompted for a browser to use if none is recorded in the preferences file. > (browser-preference? v) Returns #t if v is a valid browser preference > (update-browser-preference url-or-#f) Under Unix, prompts the user for a browser preference and records the user choice as a framework preference (even if one is already recorded). If `url-or-#f' is not #f, it is used in the dialog to explain which URL is to be opened; if it is #f, the 'internal will be one of the options for the user. > (install-help-browser-preference-panel) Installs a framework preference panel for "Browser" options. > (add-to-browser-prefs-panel proc) The `proc' must be a procedure that takes a panel% argument. It will be called when the "Browser" panel is constructed for preferences. The supplied argument is the panel, so `proc' can add additional option controls. If the panel is already created, `proc' is called immediately. > tool@ A unit that implements a DrScheme tool to add the "Browser" preference panel.