This document discusses how to use specify additional META information (often involving NewtonScript constructs) that can be used to customize books, and the IMG and A tags. Though eventually it may contain more introductory/tutorial information, currently it assumes at least some NewtonScript experience (via NTK or Newt Development Environment).
Earlier, you saw how to use META to add extra Newton-specific slots to the book. In general, slot values are treated as literal string values, however, there are a few cases where the strings are evaluated (and this requires the NewtonScript preference to be set to Compile):
<META NAME="APPSYMBOL" CONTENT="mybook:mysig">
<META NAME="ICON" CONTENT="bitmaps/fooicon.gif">
<META NAME="PUBLICATIONDATE" CONTENT="Time()">
Note: certain names that conflict with the internal book implementation are skipped: VERSION, FLAGS, DATA, STYLES, CONTENTS, BROWSERS, TEMPLATES, RENDERING, _PACKAGE.
You can include some additional scripts on books (and others described in the BookMaker docs), if you are careful that your NewtonScript methods do not cause errors. Here are some trivial examples:
<META NAME="InstallScript" CONTENT="func(bookFrame) begin Print('BookInstallScript); Print(bookFrame); end">
<META NAME="RemoveScript" CONTENT="func(removeFrame) begin Print('BookRemoveScript); Print(removeFrame); end">
<META NAME="SCRIPTS.bookOKClose" CONTENT="func() begin Print("yes, ok to close (return nil otherwise"); true; end">
<META NAME="SCRIPTS.bookHideScript" CONTENT="func() Print("I just closed")">
<META NAME="SCRIPTS.bookShowScript" CONTENT="func() Print("I just opened")">
Most of the book attributes related to a saved package can be set via regular META slots (described earlier). You can set several additional attributes in the package frame (the values are compiled expressions). Note: _package is also recognized, although _ is apparently an illegal char in META.
For example, this document uses:
<META NAME="package.labels" CONTENT="'Books"> <META NAME="package.compressed" CONTENT="true">
An HTML document can temporarily customize Prefs for tags via META.
Any local or default preferences are restored when book processing is complete.
This mechanism will definitely change when HTML Styles are standardized.
For example,
<META NAME="pref.H1" CONTENT="{align: 2, font: {family: 'espy, face: 2, size: 24}}">.
The content frame can contain some/all of the following slots (same fields
as in user Prefs; those that you don't specify would be defaulted to Prefs,
and then to built-in):
Note: though not recommended (since it's non-standard), you can specify specific page breaks for individual tags via attribute ABOVE=TOP, e.g., <P ABOVE=TOP>this is top of page
To add Newton-specific values, user prototypes and methods, use META elements that begin with "DATA.", for example (from bodyagt.htm):
<META NAME="data.inboxIcon" CONTENT="@336"> <META NAME="data.beep" CONTENT="func(a1,a2,a3,a4) PlaySound(@102)">
Note: the "data.slot" is similar to regular NewtonScript path syntax, but only works for one level currently (to include more nesting, add your own frame in one META element).
At define-time, the expression is evaluated in a special context that includes:
Note: this additional context is useful only for non-method expressions (if an expression starts with "func(", no constant substitution is done as in NTK; "constants" would be undefined variables at run-time unless you have defined them yourself in DATA). [More explanation/examples needed; perhaps could borrow NewtDevEnv's :DefConst mechanism?]
The value from this expression is added to a special frame that is stored
(permanently) with the book -- this frame can be accessed at run-time
inside your methods or externally via
the NewtonScript expression: :BookData().
At run-time, a method is invoked in the :BookData() context.
This means that the only information available inside the method at this
point is the data frame itself (other values you set via DATA.) and any
local parameters passed by HREF or SUBMIT.
In Newt's Cape, DATA. objects are used primarily to "shadow", i.e., override, URLs. This permits the same HTML file to have one behavior in a desktop version and another behavior on the Newton. In other words, if a URL is found in DATA. in the Newton version, it takes precedence over the normal URL interpretation. This occurs in three places currently:
Each of these situations allows other forms of shadowing as well. Some examples:
Newt's Cape checks/interprets a URL for IMG (tag description) with the following precedence:
If found in DATA, a string value is used instead of the current URL -- and interpretation proceeds to the next steps. This provides a simple mechanism in case you want to remap URLs for some reason, perhaps from multiple desktop directories, to a single Newton soup.
For example (note: enclosing " since string literal is compiled as Newton expression):
<META NAME="DATA.otherdir/othername" CONTENT=""bitmaps/fooicon.gif""> ... <IMG SRC="otherdir/othername">
A bitmap or picture object is used. This would normally be used to access built-in (ROM) objects. For example:
<META NAME="data.inboxIcon" CONTENT="@336"> ... <IMG SRC="inboxIcon">
For animated graphics (examples), the bitmap frame can contain the additional slots:
Finally, the URL is interpreted directly as a reference to a local soup
whose name is the "directory", with an entry whose name (or title) slot is the
"filename". If the soup entry bitmap or icon slot does not contain a bitmap or PICT object,
either the ALT text or the "no picture" icon is displayed. For example:
<IMG SRC="bitmaps/nwscpicn.gif" ALT="Newt's Cape Icon">
When you tap on a link, Newt's Cape checks/interprets a URL for HREF (tag description), with the following precedence:
A string value is used instead of the current URL -- and interpretation proceeds to the next steps. A simple use of such mapping is when the original desktop filename is quite long (or not unique across directories) and you would like to map this to a Newton ISBN. For example,
<META NAME="DATA.somedir/averylongfilename" CONTENT=""long37.htm""> ... <A HREF="somedir/averylongfilename">a link</A>
If you would like to combine several separate HTML files, we would recommend that you use LINK REL=Includes to combine books and let Newt's Cape do the HREF mapping for you (also, see later discussion of Credits kludge). But, you can do something like this yourself. For example, here are two hypothetical files: "file1.htm" and "file2.htm":
<-- file1.htm --> <HTML> ... <META NAME="DATA.file2.htm" CONTENT=""#file2""> ... <H1><A NAME="file1">First File</A></H1> ... <A HREF="file2.htm">a link to file2</A> ... <-- no </HTML> --> <-- file2.htm --> <-- no <HTML> --> ... <META NAME="DATA.file1.htm" CONTENT=""#file1""> ... <H1><A NAME="file2">Second File</A></H1> ... <A HREF="file1.htm">a link to file1</A> ... </HTML>
The HREF code invokes your method with four parameters:
If the URL refers to a Newton application symbol,
the application is sent the :toggle() message
(which either opens or closes the application).
If you know something about the API of the application, you can provide
an alternate message and parameters, in two styles:
e.g., HREF="appSymbol/msg?param1,param2,param3", or
HREF="appSymbol/msg?slot1=val1&slot2=val2"
or HREF="function/param1,...".
You can also invoke a global function. See below for brief examples,
and exprlink.htm for more explanation and examples.
Examples from some built-in apps:
If the URL begins with "mailto:", a mail message is posted via the default mail client to the user's Outbox. mailto: supplies the destination address, the subject is the book's TITLE (or ?subject= parameter), and the user can edit the default message body: "hi, I saw this cool document in Newt's Cape".
If the URL begins with "news:", it is passed to URLcop if it is installed, or Newt's Paper (if it and NIE are installed).
If the URL begins with http: on 2.x (with NIE installed), a URL is requested via the internet. Otherwise, Newt's Cape posts an email message. The default destination address (unless set via Proxy) is the WebMail service, and the message body contains commands to fetch the HTML source for a single URL. After sending this message and receiving a reply, Newt's Cape will display the Inbox button and you can select the document to process. Not exactly a real-time web browser, but who's in a hurry?
Finally, Newt's Cape will attempt to interpret the URL as a local book reference. If there is an ISBN (and a book with that isbn is installed), Newt's Cape opens the book. It then goes to the NAME following # (if any) in the now current book. (It ignores any directories in the path).
If the current book contains a BASE, Newt's Cape will process the request as a complete http: URL (as just described).
LINK, especially its REL attribute, was described earlier. When combining books, Newt's Cape checks to see if the last page begins with an object named "Credits". If so, it assumes that this page can be removed from each included book (and that you will include a new Credits page at the end of the new document). This is the convention we have used to build Newt's Cape book collections. You can typically force a page break by using H1 (setting above to Top).
The size of a new combined book should be somewhat smaller than the sum of the original books. In addition to eliminating the last pages, the books share new code for following links and adding navigation buttons (though not for form objects). LINK also merges META information and copies FORM data (ACTIONs should be unique across books).
This document (in all its formats) is © 1995-2007. Steve Weyer, Greg Simon. All Rights Reserved Worldwide
Version 2.1. Last updated: Dec 2000