HTML

From RFO-BASIC! Manual
Jump to: navigation, search

HTML (HyperText Markup Language) is the language in which web pages are coded. The HTML unit of RFO-BASIC! lets a BASIC program present a web-page interface to the user. The BASIC program can obtain or generate HTML code in a string variable and have it treated as a web page, or can specify the address (URL) of a page on the web for display to the user.

However the HTML code is obtained, the web page is displayed under the control of the current version of Android WebView installed on the device. However, the BASIC program is in control of major user operations, such as following a hyperlink to a new page. The BASIC program can modify a web page before presenting it to the user. The web page can use JavaScript to send a message (a datalink) to the BASIC program.

Browsing occurs on a screen called the web screen, independent of the graphics screen and the text console.

Examples

The program Sample_Programs/f37_html_demo.bas included in the RFO-BASIC! distribution is an example of a program that manages display of web pages. Two sample web pages used in this example, htmlDemo1.html and htmlDemo2.html, are placed in BASIC's data directory during installation. It is instructive to read the code of this sample program, try it, and understand how the code produces the effects.

The program Sample_Programs/f38_html_edit.bas included in the RFO-BASIC! distribution is a convenient text editor for the two demonstration web pages, or for other local web pages you may write.

Managing the unit[edit]

Like many other RFO-BASIC! units, the HTML. unit has initialization and termination statements.

HTML.OPEN[edit]

Initialize the HTML interface

Synopsis
HTML.OPEN {<status_lexp> {, <orientation_nexp>}}
Description

The HTML.OPEN statement initializes the HTML. unit. The BASIC program must execute it before any other HTML. statements, and not do so a second time while the HTML. unit is active.

If <status_lexp> is TRUE (nonzero), then the status bar appears on the web screen. If <status_lexp> is zero or omitted, there is no status bar.

If the statement includes <status_lexp>, then it may also specify <orientation_nexp>. If <orientation_lexp> is omitted, orientation of the web screen follows the general rules in effect for the Android device. This setting can be overridden later with HTML.ORIENTATION. Valid values for <orientation_nexp> are as follows:

Value Meaning
-1 The Android device changes the orientation of the web screen as the user rotates the device, so that the top of the web screen is always up.
0 The orientation is always Landscape.
1 The orientation is always Portrait.
2 The orientation is always Reverse Landscape.
3 The orientation is always Reverse Portrait.

HTML.CLOSE[edit]

Releases the HTML interface

Synopsis
HTML.CLOSE
Description

The HTML.CLOSE statement releases all resources used by the HTML. unit. Resources are released automatically when the BASIC program stops executing.

Displaying HTML[edit]

HTML code can be displayed, obtained from a string expression inside the BASIC program using HTML.LOAD.STRING, or from the web using HTML.LOAD.URL.

HTML.LOAD.STRING[edit]

Display HTML from a BASIC string

Synopsis
HTML.LOAD.STRING <html_sexp>
Description

The HTML.LOAD.STRING statement takes HTML code from the specified string expression and displays it as a web page.

Examples

This code generates a trivial web page and displays it.

HtmlCode$ = "<HTML><HEAD><TITLE>Sample page</TITLE></HEAD><BODY>This is the text of my tiny web page.</BODY></HTML>"
HTML.LOAD.STRING HtmlCode$

More realistically, a program could download a web page into a string variable, make any desired changes to it — This example assumes you have written a user-defined function FN.DEF ModifyWebPage(page$) to do so — and display the modified page:

GRABURL Page$,"https://rfobasic.miraheze.org"
ModifyWebPage(&Page$)   ! Your user-defined function makes any desired changes
HTML.LOAD.STRING(Page$) ! and display the modified web page

HTML.LOAD.URL[edit]

Display HTML from a web page

Synopsis
HTML.LOAD.URL <file_sexp>
Description

Instead of taking HTML code out of a string expression, HTML.LOAD.URL interprets its string expression <file_sexp> as the name of the place where the code resides.

  • If it begins with a protocol, such as http: or https:, then the string expression is interpreted as an Internet URL (Universal Resource Locator) and BASIC obtains the web page from that location on the web. The statement gives a run-time error if there is no way (WiFi, cellphone data, or other) to get pages from the web. For example:
HTML.LOAD.URL "https://rfobasic.miraheze.org"
  • If it is an ordinary filename, then BASIC obtains the web page from a file on your Android device. BASIC assumes the file is in the rfobasic/data directory where RFO-BASIC was installed (normally, the SD card). The demonstration program executes:
HTML.LOAD.URL "htmlDemo1.html"
  • If it is a fully-qualified filename, then BASIC obtains the web page from the named file. (This does not work if you do not have access to the root of your Android device's file system.) The following statement has the same effect as the previous example, if you have access to such a filename:
HTML.LOAD.URL "file:///sdcard/rfo-basic/data/htmlDemo1.html"

GRABURL[edit]

Obtain the text of a web page

Synopsis
GRABURL <result_svar>, <url_sexp>{, <timeout_nexp>}

The preceding statements use your device's browser to display a web page or other HTML text. The GRABURL statement gets the source text of a web page in <result_svar>.

Similar to the <file_sexp> parameter of HTML.LOAD.URL, the <url_sexp> parameter of GRABURL specifies the location of the desired page.

  • The parameter must begin with a protocol, such as http: or https:. The string expression is interpreted as an Internet URL (Universal Resource Locator) and BASIC obtains the web page from that location on the web. If the URL does not exist or if there is no way (WiFi, cellphone data, or other) to get pages from the web, then <result_svar> is set to the empty string, "", and the GETERROR$() function returns additional information.
  • If it is a fully-qualified filename, then BASIC obtains the web page from the named file. (This does not work if you do not have access to the root of your Android device's file system.)

If the <timeout_nexp> parameter is present and if its value is non-zero, it specifies a timeout in milliseconds. This is meaningful only if the URL names a resource on a remote host. If the timeout time elapses and host does not connect or does not return any data, GETERROR$() reports a socket timeout.

If the named resource is empty, the <result_svar> is empty, "", and GETERROR$() returns "No error".

The SPLIT statement can be used to split <result_svar> into an array of lines.

Examples

The following statement obtains, in A$, the main page of this wiki:

GRABURL A$, "https://rfobasic.miraheze.org"

The following statement obtains the text of a demonstration web page from the distributed samples:

GRABURL A$, "file:///sdcard/rfo-basic/data/htmlDemo1.html"

Managing a browsing session[edit]

The user can scroll through the web page, may be able to zoom in and out, and may be able to operate the user interface elements of the web page, without the participation of the BASIC program. However, every user action that implies going to a different web page, plus certain other actions, is communicated to the BASIC program and requires the support of the BASIC program to carry out the action.

The BASIC program may receive datalinks from the browser. A datalink is a string, which the BASIC program stores in a string variable. The first four characters of each datalink indicates what the user did that requires the program's attention. The BASIC program does not have to process datalinks as fast as the browsing session generates them; BASIC buffers them and presents each to the program in sequence.

HTML.GET.DATALINK[edit]

Get one datalink

Synopsis
HTML.GET.DATALINK <data_svar>
Description

The HTML.GET.DATALINK statement gets the next datalink from the datalink buffer and puts it in <data_svar>. If there are no datalinks in the buffer, <data_svar> is set to the empty string.

The BASIC program receives datalinks only when it has started a browsing session with HTML.LOAD.STRING or HTML.LOAD.URL.

The BASIC program must poll periodically for datalinks; it cannot get them with an interrupt handler.

Example

Here is a typical loop to wait for datalinks, though the loop might be modified to do additional things while waiting:

DO
HTML.GET.DATALINK dl1$
IF dl1$ <> "" THEN
 <statements to process the datalink>
 <may use D_U.BREAK to end the loop>
ENDIF
PAUSE 100
UNTIL 0

Datalinks[edit]

Here are the datalinks the BASIC program can receive. The left-hand column is the first four characters of the datalink:

Intro Meaning
BAK: The user pressed the BACK key. If the datalink is BAK:1, then the operation is valid (there is a web page to go back to). If the BASIC program elects to let the user go to that webpage, it executes HTML.GO.BACK. If the datalink is BAK:0, then there is no web page to go back to; for instance, the user may be trying to go "back" before the original web page. The browsing session ends and BASIC displays the text console, where the program can tell the user what happened, such as with PRINT statements.
DAT: The web page has sent a message to the BASIC program, as described below. The rest of the datalink is the message.
DNL: The user has clicked on a link meant to start a download. The rest of the datalink is the URL of the information to be downloaded. To carry out the user's intent to download the data, the program executes code like this:
GRABURL download$,RIGHT$(datalink$, -4)
ERR: An error has occurred that prevents the browsing session from continuing. The rest of the datalink is text describing the error. The browsing session ends and BASIC displays the text console, where the program can tell the user what happened, such as with PRINT statements.
FOR: The user has filled out a form in a web page and tapped a button the web page defines as the SUBMIT button. The rest of the datalink is name/value pairs. See below.
LNK: The user has tapped a hyperlink. The rest of the datalink is the URL of the web page it links to. The BASIC program may elect to surf to that web page (or to some other web page). To carry out the user's intent to go to a linked page, the program executes code like this:
HTML.LOAD.URL RIGHT$(datalink$, -4)
STT: The user has spoken to the web page. The BASIC program can use the STT.RESULTS statements to get Google's interpretation of the speech into a list. The most likely interpretation is in element 1 of the list. The program can interpret the user's speech as desired.

Forms in a web page[edit]

A web page can contain forms. A form is a web page element that has input elements, such as fields to fill out, check boxes, radio boxes, and buttons that can be tapped.

A BASIC program might be accompanied by a local web page that is nothing but a form, and whose only function is to be the user interface for the BASIC program (as opposed to input using the text console or graphics screen).

How this form looks when John Doe fills it out and before he presses Submit.

Here is a bare-bones form in HTML:

<FORM>
 <LABEL>First name:
  <INPUT ID="field" NAME="firstname" />
 </LABEL>
 <BR />
 <LABEL>Last name:
  <INPUT ID="field2" NAME="lastname" />
 </LABEL>
 <BR />
 <INPUT type="submit" />
 </FORM>

When the user presses the button whose type is "submit", then the web page sends a FOR: datalink to the BASIC program. The datalink contains:

  • The header FOR: indicating that it is information from a form.
  • The complete URL of the web page that sent the form.
  • The character ? followed by the name-and-value pair for the first field.
  • The character & followed by the name-and-value pair for any additional fields.

For example:

FOR:file:///storage/sdcard/rfobasic/data/tester.htm?firstname=John&lastname=Doe

If the purpose of the form was to let the user identify a person, then the BASIC program might now compose another web page that had relevant information it had on that person and restart the browsing session with that web page.

Newer browsers

In Android devices with newer Webview components, pressing the button whose type is "submit" begins a two-stage process. The web page sends a LNK: datalink to the BASIC program.

For example:

LNK:file:///storage/sdcard/rfobasic/data/tester.htm/FORM?firstname=John&lastname=Doe

When the BASIC program submits this URL (stripping off the LNK:), the web page sends the FOR: datalink. However, "Web page not available" flashes briefly, because FORM is not a valid web page. Alternatively, the BASIC program can extract the name-and-value pairs from the LNK: string and not trigger the FOR: datalink at all:

IF type$ = "LNK:" THEN
 p = IS_IN("FORM?",data$)
 IF p THEN data$=mid$(data$, p+5)
ENDIF

Sending messages to the BASIC program[edit]

In the event that a web page is invoked by a BASIC program, JavaScript code in the web page can send a text message to the BASIC program using the Android.dataLink() function. The single parameter of this function is a text string to send to the BASIC program. Calling this function sends a datalink with header DAT:. For example, the web page might contain this JavaScript:

<script type="text/javascript">
function doDataLink(data) {
Android.dataLink(data);
}
/* Follow with other JavaScript code that generates the message and
 * calls doDataLink().
 */
</script>

Miscellaneous statements[edit]

The following statements let the BASIC program take more detailed control of the browsing session:

Statement Effect
HTML.CLEAR.CACHE Clear the cache of the Android WebView application. The cache is the copy inside the device of pages that were already viewed. If the user selects a web page to view updated information, and there is no update, a solution may be for the BASIC program to execute HTML.CLEAR.CACHE so that WebView is forced to get a fresh copy from the web.
HTML.CLEAR.HISTORY Clear the entire browsing history of the Android WebView application.
HTML.GO.BACK Return to the previous web page that was displayed. If the program executes HTML.GO.BACK when the original web page is being displayed, it ends the browsing session. If the user presses the BACK key to return to a previous web page, the BASIC program receives a datalink and must execute HTML.GO.BACK to carry out the user's wishes.
HTML.GO.FORWARD Advance to the next web page that had been displayed. There is no next web page unless the program had executed HTML.GO.BACK one or more times. Otherwise, this statement has no effect.
HTML.ORIENTATION Set the rules for the orientation of the web screen. If HTML.OPEN set initial rules, this statement overrides them. The HTML.ORIENTATION statement takes a single, mandatory numeric expression, whose valid values are the same as for HTML.OPEN.

Issuing a POST to a web server[edit]

In the POST method of querying a web server, a BASIC program sends name/value pairs to the server. For example, the BASIC program might want to retrieve the employee ID number of a person. The essence of the request is as follows:

Name Value
FirstName Fred
LastName Smith
RequestedData EmployeeID

The HTML.POST statement makes such a request, provided that the BASIC program has executed HTML.OPEN, and uses the WebView capability of the Android device to display the resulting web page. The HTTP.POST statement makes a stand-alone request and captures the result into a string variable.

Both BASIC statements require that the list of name/value pairs be placed in a string list. The odd entries (starting with the first) are the names and the even entries (starting with the second) are the corresponding values.

Format of request

A Hypertext Transfer Protocol (HTTP) request sent to a server has a request header specifying a Content-Type of:

Content-Type: application/x-www-form-urlencoded

Although POST requests have many other capabilities, such as the ability to send other content-types and to send cookies, there is no way to do so in RFO-BASIC!.

The name/value pairs in the string list follow the request header; that is, they are the body of the message. In the above example, the HTTP request might look like this:

POST /foo.php HTTP/1.1
Host: ExampleServer.com
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Content-Type: application/x-www-form-urlencoded
Content-Length: 54

FirstName=Fred&LastName=Smith&RequestedData=EmployeeID

A server that allows such a request will reply with the RequestedData in some agreed-on format.

Issuing a GET

In the GET method, the name/value pairs are not the body of the message but are included in the URL, following a ? character. RFO-BASIC! has no statements to issue a GET. However, the program can do it itself. The simplest way to do so is to append the name/value pairs to the name of the desired web page. For example:

ExampleServer.com?FirstName=Fred&LastName=Smith&RequestedData=EmployeeID

The resulting string could be the parameter to a GRABURL statement. As before, the website would have to be designed to accept a request in this format.

HTML.POST[edit]

Issue a POST request to a website

Synopsis
HTML.POST <url_sexp>, <list_nexp>
Description

The HTML.POST statement submits name/value pairs contained in the string list <list_nexp> to the website named in <url_sexp>. If the website responds by providing a web page, then the user is able to view it, and can interact with it like any other web page opened by the HTML. unit.

Example

Continuing the example in the overview, we place in a string list the name/value pairs for a request to a server ExampleServer.com.

LIST.CREATE S PersonnelList     % BASIC returns a pointer to the new list
LIST.ADD PersonnelList, "FirstName", "Fred", ~
                        "LastName", "Smith", ~
                        "RequestedData", "EmployeeID"
HTML.POST "http://ExampleServer.com", PersonnelList

The result of this sequence will be that the user is taken to a web page that presumably displays the desired employee ID.

HTTP.POST[edit]

Issue a POST request to a website

Synopsis
HTTP.POST <url_sexp>, <list_nexp>, <result_svar>
Description

The HTTP.POST statement is another way of formulating a request to a web server that is independent of the HTML. unit and does not result in a user browsing session. It submits name/value pairs contained in the string list <list_nexp> to the website named in <url_sexp> and captures the result in <result_svar>.

Example

Again continuing the example in the overview, we place in a string list the name/value pairs for a request to a server ExampleServer.com.

LIST.CREATE S PersonnelList     % BASIC returns a pointer to the new list
LIST.ADD PersonnelList, "FirstName", "Fred", ~
                        "LastName", "Smith", ~
                        "RequestedData", "EmployeeID"
HTTP.POST "http://ExampleServer.com", PersonnelList, Result$

The result of this sequence will be that the web page emitted by the server is captured in Result$ for analysis by the BASIC program.

Since HTTP.POST does not depend on the HTML. unit or on an active browsing session, the name/value pairs can be submitted to a website or even to a web page that resides on the Android device:

HTTP.POST "file:///MyLookup.htm", PersonnelList, Result$

Problematic web pages[edit]

The HTML. unit may have problems displaying web pages that:

  1. Open additional windows with which to interact with the user.
  2. Use the BACK key for purposes other than returning to a previous web page.

Editor's query[edit]

Sources[edit]

Manual contents (Statement index)
Language features ArraysData structuresInterrupt routinesUser-defined functions
Interfaces Audio playerBluetoothGraphicsHTMLSocketsSQL
Programming notes Coexisting with Android