Version: 5.2
Browser: Simple HTML Rendering
The browser library provides the following procedures
and classes for parsing and viewing HTML files. The
browser/htmltext library provides a simplified interface
for rendering to a subclass of the GRacket text% class. The
browser/external library provides utilities for
launching an external browser (such as Firefox).
1 Browser
The browser supports basic HTML commands, plus special Racket hyperlinks
of the form <A MZSCHEME=sexpr>...</A>. When the user clicks
on such a link, the string sexpr is parsed as a Racket program
and evaluated. Since sexpr is likely to contain Racket
strings, and since escape characters are difficult for people to read, a
| character in sexpr is converted to a "
character before it is parsed. Thus,
<A MZSCHEME="|This goes nowhere.|">Nowhere</A> |
creates a “Nowhere” hyperlink, which executes the Racket program
"This goes nowhere."
The value of that program is a string. When a Racket 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
<A MZSCHEME=sexpr>...</A> 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,
<!-- MZSCHEME="(format |<B>Here</B>: ~a| (current-directory))" --> |
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 Racket code is executed through eval.
The MZSCHEME forms are disabled unless the web page is a
file: url that points into the doc collection.
Opens the given url in a vanilla browser frame and returns the
frame. The frame is an instance of
hyper-frame%.
A parameter that determines whether the browser attempts to download
and render images.
A parameter that determines whether MZSCHEME= tags are
evaluated.
Returns the class that is instantiated when the frame is created.
Must be a panel with hyper-panel-mixin mixed in. Defaults to just
returning
hyper-panel%.
Returns the hyper panel in this frame.
Shows the frame and visits url.
The same as the
hyper-frame-mixin, except that it doesn’t
show the frame and the initialization arguments are unchanged.
Determines if MZSCHEME annotations are actually evaluated,
for a given url.
The
url is loaded into the
text% object (using the
reload method), a top-level window for
status messages and 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.
Maps the given style over the given range.
Changes the style for the given range to the link style.
Returns the URL displayed by the editor, or #f if there is
none.
Gets the page’s title.
Sets the page’s title.
Override this method to set the link style.
Installs a tag.
Finds the location of a tag in the buffer (where tags are installed
in HTML with <A NAME="name">) 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.
Removes a tag.
Follows the link, optionally with the given post data.
Installs a hyperlink.
Installs a Racket evaluation hyperlink.
Installs a thunk-based hyperlink.
Called to handle the <A MZSCHEME="expr">...</A> tag and
<! MZSCHEME="expr"> comments (see above). Evaluates the
string; if the result is a string, it is opened as an HTML page.
Reloads the current page.
By default, the text uses the basic style named
"Html Standard" in the editor (if it exists).
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).
Returns a keymap suitable for frame-level handling of events to
redirect page-up, etc. to the browser canvas.
Extends the
text:keymap% class to support standard key
bindings in the browser window.
A
hyper-can-mixin-extended canvas’s parent should be an
instance of a class derived with
hyper-panel-mixin.
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.
Returns a representation of the currently displayed page, which
includes a particular editor and a visible range within the editor.
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.
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.
Called during set-page. Does nothing by default.
Creates controls and a hyper text canvas. The controls permit a
user to move back and forth in the hypertext history.
The info-line? argument indicates whether the browser
should contain a line to display special DOCNOTE tags in a
page. Such tags are used primarily by the PLT documentation.
Creates the panel’s hypertext canvas, an instance of a class derived
using
hyper-canvas-mixin. This method is called during
initialization.
Returns the class instantiated by make-canvas. It must be derived
from
hyper-canvas-mixin.
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%.
Goes back one page, if possible.
Goes forward one page, if possible.
Gets the hypertext canvas.
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).
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.
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.
Reloads the currently visible page by calling the reload
method of the currently displayed hyper-text.
Creates a page record for the given editor, suitable for use with the
set-page method of
hyper-canvas-mixin.
Extracts the editor from a page record.
Parameter controlling the point size of a bullet.
Instances of this class behave like
image-snip% objects,
except they have a
<map> ... </map> associated with them and
when clicking on them (in the map) they will cause their init arg text
to follow the corresponding link.
Sets the key for the image map (eg, "#key").
Returns the current key.
Registers the shape named by shape whose coordinates are
specified by region to go to href when that region
of the image is clicked on.
This exception may be raised by the
reload method.
This exception may be raised by the
reload method.
2 Browser Unit
Imports
mred^,
tcp^, and
url^, and exports
browser^.
3 Browser Signature
Includes all of the bindings of the browser library.
4 HTML As Text Editor
Returns a base URL used for building relative URLs, or #f
if no base is available.
Registers the title str for the rendered page.
Registers a hyperlink for the given region in rendered page.
Installs a tag.
Changes the style for the given range to the link style.
Installs a Racket evaluation hyperlink.
Installs a thunk-based hyperlink.
Follows the link, optionally with the given post data.
Reads HTML from in and renders it to dest. If
load-img? is #f, then images are rendered as Xed-out
boxes. If eval-mz? is #f, then MZSCHEME
hyperlink expressions and comments are not evaluated.
Uses the style named "Html Standard" in the editor’s
style-list (if it exists) for all of the inserted text’s default
style.
5 Launching an External Browser
Like
send-url from
net/sendurl, but on Unix, the user
is prompted for a browser to use if none is recorded in the
preferences file.
Returns #t if v is a valid browser preference.
On 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 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.
Installs a framework preference panel for “Browser” options.
The proc is 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.
6 DrRacket Browser Preference Panel
A unit that implements a DrRacket tool to add the “Browser”
preference panel.