[prev] [up] [next]

The ST/X HTML Viewer

Index

Introduction

The ST/X HTML-viewer has been written to allow easy access to the online documentation. It provides some of the functionality and look & feel of popular HTML browsers (or WWW browsers), such as Netscape, Mosaic, Chimera etc.

Although the HTML viewer is typically used as a top view to display an HTML document, it can also be used as a widget and embedded in an application. ST/X itself uses this to display help texts for dialogs (try some dialog from the Launcher's settings menu).

In addition to most standard features, additional functionality has been built in, to allow some interaction with your current Smalltalk system.

Notice, that this browser has not been written to compete with existing browsers - we do not claim it to be a replacement for any real WWW browser. It has some major rendering features missing or only partially implemented; especially tables, box model and style sheets are completely unusable for today's web pages.
Its main purpose is to provide a powerful tool for interactive online documentation AND at the same time use a widely used, industry standard document format. Additional features are implemented as add-on tags and tag-parameters, which are ignored by other browsers - thus, all documentation can also be viewed using any other browser. However, the interaction features will not be available with other browsers.

Documents may be located on local files or be accessed from remote machines via the HTTP protocol. This is especially useful in development groups or with larger projects, since the documentation can be located and managed on one central machine - thus reducing maintenance costs.

Beside its use as an ST/X document viewer, it may also be useful for application writers, to provide non-ST/X online documentation for their users.

By the way, due to its build in SmalltalkScript and applet support, it may also be useful as a tool to build nice intraNet applications - a very simple database application is found in ``html/applications/phoneBook''.

Features

Ampersand Escapes

To see the special characters as listed below, your system's font should be iso-latin1 encoded and contain the full character set. (Which is not the case for some of the older XWindow fonts).

National characters:

ø ø Ø Ø
å å Å Å
ã ã Ã Ã
ñ ñ Ñ Ñ
õ õ Õ Ø
ä ä Ä Ä
ü ü Ü Ü
ö ö Ö Ö
ë ë Ë Ë
ï ï Ï Ï
ÿ ÿ ß ß
æ æ Æ Æ
â â Â Â
î î Î Î
ê ê Ê Ê
û û Û Û
ô ô Ô Ô
à à À À
ì ì Ì Ì
è è È È
ù ù Ù Ù
ò ò Ò Ò
á á Á Á
í í Í Í
é é É É
ú ú Ú Ú
ó ó Ó Ó
ç ç Ç Ç

Special characters:

< &lt; > &gt; & &amp;
" &quot; © &copy; ® &reg;
¢ &cent; £ &pound; ¥ &yen;
¦ &brvbar; § &sect; · &middot;
« &laquo; » &raquo; ± &plusmn;
¼ &frac14; ½ &frac12; ¾ &frac34;
µ &micro; ¿ &iquest; ÷ &div;
¹ &sup1; ² &sup2; ³ &sup3;
° &deg;
  &nbsp; (no-break space)

Extended Ampersand Escapes

For the HTML-3.0 Greek character set, your display & printer must provide a full symbol font.

Lower case greek:

α &alpha; ι &iota; ρ &rho;
β &beta; κ &kappa; σ &sigma;
γ &gamma; λ &lambda; τ &tau;
δ &delta; μ &mu; υ &upsilon;
ε &epsilon; ν &nu; φ &phi;
ζ &zeta; ξ &xi; χ &chi;
η &eta; ο &omicron; ψ &psi;
θ &theta; π &pi; ω &omega;

Variants:

ϖ &varpi;
&vsigma; &vsigma;
ϕ &varphi;

Upper case greek:

Γ &Gamma; Ξ &Xi; Φ &Phi;
Δ &Delta; Π &Pi; Ψ &Psi;
Θ &Theta; Σ &Sigma; Ω &Omega;
Λ &Lambda; Υ &Upsilon; Χ &Chi;

The (not yet standard) Latex Math character set:
Since those character names are not yet defined in the HTML-3.2 standard, the Latex names were used (we hope, those will make it at the end...)
Notice, that the entity names may be changed, once a common standard exists.

&ldots; 3dots on baseline &ldots;
forall &forall;
&exists; exists &exists;
&aleph;
R fraktur &Re;
I fraktur &Im;
&infty; infinity &infty;
less-equal &le;
greater-equal &ge;
not equal &ne;
equivalent &equiv;
approximate &approx;
congruent &cong;
± plus-minus &plusmn;
× times &times;
÷ div &div;
ring-plus &oplus;
ring-times &otimes;
ø ring-slash &oslash;
summation &sum;
product &prod;
logOr (vee) &vee;
logAnd (wedge) &wedge;
&neg; negation &neg;
uparrow &uparrow;
downarrow &downarrow;
leftarrow &leftarrow;
rightarrow &rightarrow;
leftrightarrow &leftrightarrow;
Uparrow &Uparrow;
Downarrow &Downarrow;
Leftarrow &Leftarrow;
Rightarrow &Rightarrow;
Leftrightarrow &Leftrightarrow;
Element-of &isin;
Not an element-of &notin;
subset &subset;
subset-eq &subseteq;
superset &supset;
superset-eq &supseteq;
left floor &lfloor;
right floor &rfloor;
left ceiling &lceil;
right ceiling &rceil;

Additional dynamic bindings:

escapeexpands toexample
&userName;your full user name"&userName;"
&userFirstName;your first name"&userFirstName;"
&loginName;your login name"&loginName;"
&userID;your user id"&userID;"
&groupID;your group id"&groupID;"
&hostName;your machine's hostname"&hostName;"
&domainName;your machine's domainname"&domainName;"
&date;todays date"&date;"
&time;right now"&time;"
&url;the URL of the current document
"&url;"
&urlBaseName;its baseName"&urlBaseName;"
&urlDirName;its directory name
"&urlDirName;"
&stxVersion;the ST/X version"&stxVersion;"

Image formats

All image formats which are understood by your Smalltalk system are also supported by the document viewer. In particular, these are PNG, GIF, JPEG, TIFF, BMP, XBM and XPM.
We recommend using PNG for new documents.

Color Names

Color parameters (for example, the Text= parameter in the BODY tag) can be specified both by RGB-value and by name.
To ensure compatibility with other HTML viewers, we recommend not using colorNames - or at least only use the names of the basic colors (which are also supported by other browsers, such as MS internet explorer).

Here are a few examples:

red green blue
olive navy purple
teal gray silver
lime maroon yellow
fuchsia aqua white

New Parameters

The following additional (w.r.t. HTML-1) parameters are supported:
<APPLET>
Creates an applet. For now, only Smalltalk applets are supported; Java applet support will be added in a future version (an experimental version of the Java bytecode interpreter, written in Smalltalk, is already running).
Applets are ignored when a document is printed.

CLASS=aClassName
Specify the applets className. This class must be already present in the Smalltalk system (i.e. this is for an internal applet).
CODE="filename.cls"
Specify the applets code file. This file must contain the applets classCode in binary fileOut format. If this tag is present, the applet is considered an external applet, for which the classes code is loaded first. In this case, the CLASS-tag is not required.
Additional security checks (code authentication) are performed. The applet will only be loaded and executed, if those checks pass.
If this tag is not present or the class is not loadable from the codeFile, and a CLASS-tag is present, the applet will be created as an internal applet.
WIDTH=aNumber
Specify the applets width. The applet may override this, by resizing itself.
If followed by a percent (%), the width is defined relative to the browserViews width.
HEIGHT=aNumber
Specify the applets height. The applet may override this, by resizing itself.
If followed by a percent (%), the height is defined relative to the browserViews height.
NAME=appletsName
Defines the applets name - a script can refer to the applet using the expression:
"document window applets appletsName".

<PARAM>
Passes additional arguments to an applet. Each PARAM-tag must contain NAME= and VALUE= parameters. A parameters string-values can be obtained by the applets via #getParameter:-messages.

NAME=aParameterName
Specify the parameters name.
VALUE="something"
Specify the parameters value.

<INPUT>
TYPE=button ONCLICK=aScriptMethodName
Arranges for a scripts method to be evaluated when the button is pressed.
If aScriptMethodName ends in a colon, the name of the button which was clicked is passed as argument.

<FORM>
ONSUBMIT=aScriptMethodName
Arranges for a scripts method to be evaluated when the form is submitted. Forms which consist of textFields only will submit when the last field is left (via tabbing).
If aScriptMethodName ends in a colon, the name of the form which was submitted is passed as argument.

<BODY>
BGCOLOR=aColor
Specify the background color of the page. (this is ignored when the page is printed on paper).
BACKGROUND=aColor
Specify a background image
TEXT=aColor
Specify the text color of the page.
LINK=aColor
Specify the anchor color of the page.
VLINK=aColor
Specify the visited anchor color of the page.
LEFTMARGIN=pixels
Specify the leftMargin.
RIGHTMARGIN=pixels
Specify the rightMargin.
TOPMARGIN=pixels
Specify the topMargin.

<A>
TYPE="example" [SHOWRESULT]
The special anchorType "example" installs the anchor text as a clickable example. When clicked upon, it is interpreted as Smalltalk code. The example's text is visible.
If the optional 'SHOWRESULT' parameter is present, the example's return value is shown in the infoView.
TYPE="copyexample" [SHOWRESULT]
The special anchorType "copyexample" marks the anchor text as non-clickable example. It does not evaluate when clicked upon, but provides a popup menu which allows for the example's text to be copied into a workspace.
ACTION="doit:smalltalk expression"
The anchors action is to execute the given expression. This is much like an example, but allows a different action from what is shown as text.
ACTION="plainText:smalltalk expression"
The Smalltalk expression is assumed to return some text string. This is shown as plainText.
ACTION="htmlText:smalltalk expression"
The Smalltalk expression is assumed to return some html text string. This is formatted and shown.
HREF="plainFile:URL"
The files text will be shown as plainText - even if it contains html text.
INFO=string
If the html-viewer was opened with an info-subview, show this string there, when the cursor moves over the anchor. Without an INFO-parameter, the anchors HREF is shown.

<P>
INDENT=aNumber
Indent the next paragraph. The argument bay also be preceeded by a ``+'' or ``-'', to specify a relative indent.
NEWPAGE
Force a page break when printing; ignored in the viewer.
NEED=aNumber
Force a page break when printing, if the current page does not have at least aNumber pixels of space. Can be used to prevent some text from being splitted. When printed, headline TAGs automatically imply a need of a few lines. Ignored in the viewer.

<UL>
TYPE=markerType
Specify the type of marker; the argument should be one of: ``disc'', ``arrow'', ``square'', ``filledSquare'', ``circle'', ``filledCircle'' or ``none''. The default taken by the viewer depends on the lists nesting level.

<OL>
TYPE=numberingType
Specify the numbering ; it should be one of: A: (for uppercase letters), a: (for lowercase letters), I: (for uppercase roman numbers), i: (for lowercase roman numbers), The default is to use digits.
START=initialNumber
Specify the starting value for sequence numbering. The default is 1.

<LI>
VALUE=number
Only within OL-lists: specify an explicit sequence number

<IMG>
NOPRINT
The image is shown in the viewer, but suppressed when printed. Typically, this is used with the next/up/prev buttons as seen on this page (which are not wanted when the document is printed as a book).
BORDER=aNumber
Specifies the imageBorders thickness.
HSPACE=aNumber
Specifies additional horizontal spacing.
VSPACE=aNumber
Specifies additional vertical spacing.

<Hx>
NOINDEX
Only affects printing: this header is not to be included in the Table-of-Contents.
NEWPAGE
Force a page break; ignored in the viewer.
NEED=aNumber
see description of NEED in P-Tag.

<HR>
SIZE=aNumber
Specify the thickness of the horizontal rule (in pixels)
NOSHADE
Force no shading (no 3D effect)
SHADE
Force shading (with 3D effect)
WIDTH=aNumber
Specify the width (in pixels). If followed by a percent (%), the width is defined relative to the views (or printPages) width.

Smalltalk Action HREFs

You can assign a Smalltalk action to be invoked when an anchor is clicked. This is done by adding an "action=" attribute to the anchor element, as in:
    <A HREF="../../misc/onlyInSTX.html" ACTION="doit: Transcript showCR:10 factorial">
	click to see 10 factorial on the Transcript
    </A>
which results in the following link: click to see 10 factorial on the Transcript
Notice the "onlyInSTX.html" fallback-link; this will be used by non-ST/X browsers (IE, firefox, etc.) as they do not know or care for the action-doIt attribute.

Such action links can be used to open example applications right from within the help document.
For example: Click here to open a browser on the SmallInteger class .

SmalltalkScript

Smalltalk is supported as a script language - later versions will also support javaScript. In contrast to javaScript, Smalltalk scripts provide the full functionality of the language - it is not a Smalltalk subset. Any feature (such as opening new views, starting new threads etc.) is at the script writers hand. It is therefore much more powerful and expressive - but also opens the door to doing harm to your Smalltalk system.

For this reason, a strict security check is performed, before any script is allowed to execute.
Since it is very hard (if not impossible) to provide a limited execution environment (as is done with Java), the security mechanism is based on trusted documents - instead of a protected environment.
Documents which are considered secure are allowed to execute - without limitations.

Methods can be defined between <SCRIPT> ... </SCRIPT> in Smalltalk code (fileOut format). These are installed as methods of an anonymous class, of which a single instance is created when a script-page is loaded.

Messages can be sent to this object interactively (for example, via the ONCLICK="some message" button parameter).

It is also possible, to execute Smalltalk code automatically, when the document is loaded.

Future enhancements will add additional interaction possibilities.

The script itself must consist of Smalltalk expression in a restricted chunk format. The script must consist of:

The main purpose of the script is to provide methods which are evaluated via "ONCLICK=" parameters. Typically, these are associated with form-buttons.
Two special methods may be defined additionally:

Access to browser resources is via messages to the window object; the access path has been setup to be similar to javaScript.

window
a pseudo object; provided as a container for the following objects.

location
the URL of the current document (as a string)

history
the browser's URL-history. A collection of URL-strings.

document
a pseudo object; provided as a container for the following objects.

applets
a collection of applets (access using #at: messages). Named applets can also be accessed byName, by sending corresponding messages to the applets collection.

applet-by-name
all named applets (i.e. those with a NAME= parameter) can be accessed here.
at:index
any applet can be accessed via a numeric index here.

forms
a collection of forms (access using #at: messages). Named forms can also be accessed byName, by sending corresponding messages to the forms collection.
Every form consists of a collection of its elements (i.e. input fields, buttons etc.). Those are accessed via a numeric index, or (if the element has a NAME= parameter) vi the elements name.

form-by-name
all named forms (i.e. those with a NAME= parameter) can be accessed here.
at:index
any form can be accessed via a numeric index here.

images
a collection of images (access using #at: messages)

links
a collection of links contained in the document.

anchors
a collection of anchors contained in the document.

frames
a collection of frames (access using #at: messages).
Frames are not yet supported.

view
the main html browsers view. Any of the browser's internal attributes is accessible via messages to this object (an instance of HTMLDocumentView).

visitedURLs
a collection of visited URL-strings
For example, to access an applet named "fooApplet", use the following message path:
    window document applets fooApplet

Notice, that this resembles the corresponding javaScript expression, which would be:

    window.document.applets.fooApplet

Script examples are found in "doc/html/testDocs" or the index page "doc/html/testDocs/TOP.html".

Smalltalk Applets

Applet classes may be derived from either the View class or the Applet class. However, applet specific functionality (such as accessing the parameters) is only possible, if the applet inherits from Applet.
Applet itself has been defined as a subclass of View, and defines some simple-protocol, which was created to look Java-applet like.
See the classes documentation for more details.

Java Applets

Starting with release 3.5, the ST/X VM allows for Java code to be executed. This feature is also used to allow for Java applets to be embedded in the ST/X HTML viewer.
Any standard 1.1.x JDK-Applet should be able to execute in the HTML browser.
See the classes documentation for more details.

Missing Features & Bugs

Some features are not yet fully implemented, or missing. These may or may not be added in future versions.

Further reading

Appendix - List of Tags & Parameters

Sorry, this chapter is not complete.
Nonstandard tags or parameters are highlighted with a green color.

Element Attribute Possible Values Description
A HREF= "url" hyperlink of anchor
"man:command" hyperlink to a commands UNIX manual page
NAME= "string" name of anchor
ONCLICK= "scriptMethodName" name of script method
TYPE= "example" a clickable example
"plainFile" show as plain file - even if it contains HTML
SHOWRESULT for above: show result in info area
ACTION= "doit:ST-expr" Smalltalk expression evaluation
"plainText:ST-expr" expression provides plainText page
"htmlText:ST-expr" expression provides html page
INFO= "string" show info when mouse is over anchor
APPLET WIDTH= number width of applet space
HEIGHT= number height of applet space
LEVEL= number 3D level of applets view
CLASS= "className" name of applets class
CODE= "url.cls" binary code file (ST/X bytecode)
"url.class" binary code file (JAVA bytecode)
BODY LEFTMARGIN= number set the overall leftmargin
TOPMARGIN= number set the overall topmargin
RIGHTMARGIN= number set the overall rightmargin
BACKGROUND= "url" define a background image
BGCOLOR= color background color
TEXT= color color for text
LINK= color color for links
VLINK= color color for visited links
ALINK= color color for active (pressed) links
H<i> ALIGN= center center the headers text
right rightAdjust the headers text
default: leftAdjust
NOINDEX ignore in table of contents when printing
NEWPAGE force page break when printing
NEED= number conditional page break when printing
IMG SRC= "url" URL of the image.
ALT= "text" text to display if image file is unloadable.
BORDER= number border width. Default is 0.
WIDTH= number width of image space
HEIGHT= number height of image space
HSPACE= number horizontal space around image
VSPACE= number vertical space around image
NOPRINT ignore this image when printing
LI VALUE= number set the items sequence number
OL SEQNUM= number define the start number
START= number alternative for above
TYPE= "A" uppercase alpha numbering
"a" lowercase alpha numbering
"I" uppercase roman numbering
"i" lowercase roman numbering
default: decimal numbering
LIST-STYLE= "upper-alpha" uppercase alpha numbering
"lower-alpha" lowercase alpha numbering
"upper-roman" uppercase roman numbering
"lower-roman" lowercase roman numbering
"decimal" decimal numbering
"none" suppress numbering
default: as specified by TYPE attribute
P INDENT= number set indent
+number more indent
-number less indent
default: indent unchanged
NEWPAGE force page break when printing
NEED= number conditional page break when printing
S strikeout (3.0)
STRIKE strikeout (3.2)
UL TYPE= "arrow" draw an arrow as marker
"circle" draw a circle marker
"filledcircle" draw a filled circle marker
"square" draw a square marker
"filledsquare" draw a filled square marker
"disc" draw a disc-bitmap marker
default: depends on nesting level
PLAIN suppress any marker


[stx logo] Copyright © eXept Software AG, all rights reserved

<info@exept.de>

Doc $Revision: 1.56 $ $Date: 2020/08/19 19:02:15 $