This document discusses how to use NewtonScript in the context of HTML and Newt's Cape. Though eventually it may contain more introductory/tutorial information, currently it assumes at least some NewtonScript experience (via NTK or Newt Development Environment).
If you need to do some run-time initialization of a form, e.g., set a field to a different default value for the current user, you can include a :form_init method in your META definitions.
For example:
<META NAME="DATA.form_init" CONTENT="func(fdata,action) ...">
Note: this is subject to change as we understand CGI scripts better.
When you tap a SUBMIT (tag description) button, Newt's Cape checks/interprets the ACTION URL defined earlier in FORM (tag description) with the following precedence:
Similar to IMG and HREF, this can be used to map to something else, e.g., a soup name. For document to work on non-Newtons, you should use this rather than specifying a soup name directly.
<META NAME="DATA.someURL" CONTENT=""Notes""> ... <FORM ACTION="someURL">
The SUBMIT button invokes your method with four parameters:
During form entry, values are added to a special frame that is stored
(temporarily) in a global frame (you can access this at run-time in your
form object via :AllData(true). This frame is reinitialized when the Newton
is rebooted, when the user performs a RESET, or normally after SUBMIT.
Your method is invoked in the context of the :BookData() frame, so has access to other information and methods that you may have stored there via DATA.. When your method completes, it should return TRUE if the form data should be RESET, i.e., restored to defaults; NIL if not.
For example, to just Print the info, assuming you have Newt, Sloup or NTK Inspector):
<META NAME="DATA.printIt" CONTENT="func(submit,title,url,data) begin Print(URL); Print(title); Print(data); /* print 3 values */ TRUE; /* reset the data */ end"> ... <FORM ACTION="printIt">
Other methods available in Submit context:
Here is a more complicated example in which your form decides what to do based
on which SUBMIT button was tapped. Note: a Submit button first sets
the value of the slot referred to by NAME -- here submitMeth --
before calling your method. The button object has several convenient methods
e.g., postNotes and postMail (described above).
<META NAME="DATA.decide" CONTENT="func(submitobj,title,action,data) begin /* Mail button? */ if StrEqual(data.submitMeth,"Mail") then submitobj:PostMail(title,action,data) /* Notes button? */ else if StrEqual(data.submitMeth,"Notes") then submitobj:PostNotes(title,self.form_printnames.(Intern(action)),data) /* otherwise... */ else begin Print(action); Print(title); Print(data); end; TRUE; /* reset the data */ end"> ... <FORM ACTION="decide@foo.com"> ... <INPUT TYPE=SUBMIT NAME=submitMeth VALUE="Mail"> <INPUT TYPE=SUBMIT NAME=submitMeth VALUE="Notes"> <INPUT TYPE=SUBMIT NAME=submitMeth VALUE="Inspector">
If an application (with appSymbol) exists and has a method defined (methSym), it is invoked with a single (frame) parameter which is the data frame. You could use this, for example, to create a control panel or input form for another Newton application.
If the ACTION is "Notes" (or mapped to Notes), the data is written to the Notepad, as follows:
FORM: book title slot1: value(s) slot2: value(s)
If the ACTION begins with "Print()", the data frame is passed to the Newton's Print function. This can be useful for testing. If you have the NTK Inspector connected, the result will appear there. If you have Sloup connected, the result will appear in your terminal emulator. If NewtDevEnv is open (with Print? checked), the result should appear in EvalLog (close the book to see it). If you had multiple ACTIONs in a document, you could use Print()1, Print()2, etc.
Puts data as text with values delimited for http servers, e.g.,
?x=1&y=2 into an email message in your Outbox..
If the ACTION begins with http: (or the current document has a BASE to resolve the relative URL), the data will be sent either via NIE or WebMail.
Finally, if preceded by "soup/", Newt's Cape interprets the remainder of the URL as a soup name and adds the data frame to the soup. This assumes you would use Sloup to later "DUMP" the data as tab-delimited text, or use another soup or synchronization utility.
Note about Data frame values. Generally, HIDDEN values should be defined early in the form so that they are available to later fields (possibly for initialization). If a user quits a book (saved package) without RESETting data, the data is preserved until the next system reset.
The DATA. mechanism provides a flexible, reasonably transparent, mechanism for customizing IMG, HREF, and FORM(SUBMIT) behavior. We would also like to allow customization of individual Newton form objects such as input fields, checkboxes, etc. At the time of this writing, you can add a SCRIPT attribute to individual objects (basically a method that is invoked whenever the field value changes). However, since this is a non-standard HTML extension, we are exploring how this (and other attributes) such as viewFlags can be added using DATA.
When you double-tap a TEXT field, a alphanumeric keyboard normally pops up. If you specify a VALUE_TYPE attribute that begins with DATE, INT (or NUM), PHONE, TIME, FAX, ADDRESS, NAME, COUNTRY, CITY, STATE, PROVINCE, this provides different recognition defaults for handwriting, and a different, value-specific keyboard may appear when you double-tap. (This assumes that there wasn't a more specific type defined via a prototype). It does no other value checking. In summary, if the VALUE_TYPE equals or begins with
VALUE_TYPE can also access a user prototype defined earlier via META. There are detailed examples in nformobj.htm. This discusses the implementation, with examples of AZ-picker, date and time pickers/fields, country, city, state, province, latitude&longitude pickers/fields, character edit field, integer picker, name, fax, phone, email, meeting place picker/fields. For example, you could use a new type, e.g., "INTSLIDER" in a standard INPUT object:
<P> <INPUT TYPE="TEXT" VALUE_TYPE="INTSLIDER" NAME="slider1">
The reason for starting the name with "INT" is that if the object were not created, either because the user did not enable NewtonScript: Compile or the object was based on a undefined prototype (e.g., 2.x proto on 1.x system, it would at least default to using a numeric recognition and keyboard.
Here's how INTSLIDER would have been defined earlier (see nformobj.htm)
<META NAME="DATA.INTSLIDER" CONTENT="{
_proto: @212, /*protoSlider*/
NAME: nil,
VALUE: "0",
viewSetupFormScript: func()
begin
local val := :GetData(NAME);
viewValue := Floor(StringToNumber(if StrFilled(val) then val else VALUE));
end,
changedSlider: func()
begin
:SetData(NAME, SPrintObject(viewValue));
end,
/*copy these attributes (if present) directly to the view object and convert to integers*/
copy_Attributes: {MINVALUE: 'INT, MAXVALUE: 'INT},
}">
This frame (and its values) are evaluated at the time the document is processed (not later at run-time). If you have access to Newton Toolkit or NewtDevEnv and can develop and test your prototypes there, you will have the most success and least frustration. You need to be especially careful about HTML vs. NewtonScript quoting conventions. Some slot-by-slot notes:
For example:
<P> <INPUT VALUE_TYPE="INTSLIDER" NAME="slider2" VALUE="20" HEIGHT="12" MINVALUE="0" MAXVALUE="200">
Some additional notes. A normal TEXT field may have a non-standard LABEL attribute (which corresponds to the preceding string in the paragraph) added by Newt's Cape. Since a slider does not have a label, in the examples above, the INPUT statements are preceded by <P>. However, there are cases, such as protoDateNTimeTextPicker that do allow a LABEL, in which case it can automatically take advantage of any "label" that Newt's Cape provides.
The HEIGHT of a normal TEXT field defaults to 20 (or to the height of the LABEL). If you want to specify a different height, you can include a HEIGHT attribute (as in the earlier example), though this will be ignored if the object defaults back to a regular TEXT field.
Other fields (unused in this example):
This is new functionality; feedback/suggestions appreciated. Take a look at the examples available -- currently, there are three, but there will be more as time permits, especially if users ask questions or donate source.
This document (in all its formats) is © 1995-99. Steve Weyer, Greg Simon. All Rights Reserved Worldwide
Version 2.0. Last updated: Feb 1999