Vision Interfaces: Sample Html Access

Overview

Web browsers such as Netscape and Internet Explorer offer an excellent mechanism for delivering documents that can be dynamically generated by Vision. The Interface and FormatTools ToolKits provide a means for standardizing your requests for information and returning the results in a form that can be displayed by a browser.

In general, you can use Html and its numerous extensions such as JavaScript and Java applets to design interfaces that request specific inputs from a user. These inputs can be submitted to Vision via a cgi or alternative interface program to access the appropriate information from Vision, dynamically generated based on the inputs supplied and formatted correctly for the browser. The returned documents can have embedded links to other documents, including requests for additional information from your Vision database.

The basic mechanism for navigating from one Html document to another is by embedding the URL of a target document in the source document. In addition to referencing specific pre-formatted documents, this URL can be used to specify a program that communicates inputs from the document to Vision and returns a new document to the browser. The URL can be associated with the HREF attribute of an anchor. It can also be used as the value of the ACTION attribute of a form. In the latter case, the values of the controls in the form are also shipped.

---

The Interface HtmlAccess Class

The class Interface HtmlAccess supplies the protocol needed to parse inputs from Html forms and links and produce a document that can be interpretted by an Html browser:

  Interface HtmlAccess
     get: "PATH_INFO"
     usingQuery: "QUERY_STRING"
     for: "REMOTE_HOST"
     at: "REMOTE_ADDR" ;

The method get:usingQuery:for:at: parses the PATH_INFO and QUERY_STRING strings and generates an HTTP response containing an HTML document as its content. The following steps are executed:

1. Parse the PATH_INFO and QUERY_STRING parameters to determine the name of the application to run and any parameter values.
2. Set the application name and parameter values in the ApplicationWS associated with this Vision session.
3. Display Html page header information.
4. Run the requested application with the supplied inputs and display the results.
5. Display Html page footer information.

Parsing the Strings

The get:usingQuery:for:at: method assumes that the PATH_INFO string is supplied in the format:

  ApplicationName@Parameter1@Parameter2@...@ParameterN

where any number of parameters can be supplied, separated by the @ character. For example, if the URL in your HREF statement contains:

  http://www.myserver.com/.../Profile@Company@IBM

the PATH_INFO would contain: /Profile@Company@IBM. The method strips off the leading "/", then breaks this string into substrings using the @ character as its delimiter. The first substring (i.e., Profile ) represents the name of the application to run. The remaining strings represent the parameter list for this application. The messages setApplicationTo: and setParameterListTo: are executed to store these values in the current ApplicationWS.

The get:usingQuery:for:at: method assumes that the QUERY_STRING string is supplied in the format:

  control1=value1&control2=value2&control3=value3&...

where the control strings represent the names of controls on the Html form submitted and the value strings are the corresponding values supplied for these controls. For example, the submitted form could supply the following name/value pairs:

Name	Value
appName	Profile
classId	Company
id	IBM

This information would be supplied to Vision as the string appName=Profile&classId=Company&id=IBM. The get:usingQuery:for:at: method breaks this string into name/value pairs. The input named appName is assumed to be the application to run. The remaining inputs represent parameter values for this application. The messages setApplicationTo: and set:to: are executed to stored these values in the current ApplicationWS. If the query string includes a control id named globalDate, its value is used to set the value of the global date for the Interface class. If the query string includes a control id named globalCurrency, its value is used to set the value of the global currency for the Interface class.

If both the PATH_INFO and QUERY_STRING are present, the application associated with the PATH_INFO string is the one that is executed.

Preparing the Output

When the application is run, a document in the following format is generated:

  Content-Type: text/html

  <HTML>
  <HEAD>
  <TITLE> title based on inputs goes here </TITLE>
  </HEAD>
  <BODY>
  <H2> standard title goes here </H2><HR>

      output from ApplicationWS formatted with HTML tags

  </BODY></HTML>

An appropriate Html header and footer is created to surround the output from the application. The application itself is executed within a FormatTools Html evaluate: block so that any display tags are generated for Html.

Passing Information to Vision: Summary

1. HREFs used with anchors should be formed using:

     http://servername/.../appName@p1@p2@p3...
   

   The form should contain a control (hidden or visible) named appName that specifies the name of the application to run.

2. If the query string includes the name globalDate, it is used to set the value of the Global date for the Interface class.

3. If the query string includes the name globalCurrency, it is used to set the value of the Global currency for the Interface class.

---

The FormatTools Html Class

The class FormatTools Html redefines various formatting messages to include the appropriate Html tags. Recall that the FormatTools class can be used to provide a modular approach to output generation. The various formatting messages have a default mode and an Html version. For example the expression:

  FormatTools bold: "this string" . print ;

displays the supplied string with no special formatting. The expression:

  FormatTools Html
       evaluate: [ FormatTools bold: "this string" . print ] ;

displays the supplied string within <b> and </b> tags. A description of the various FormatTools messages and their default and Html behavior is presented in the document Vision ToolKit Class: Interface.

Embedding Links in Vision Documents

The general format for an Html link is:

  <a HREF=URL> label </a>

where URL is the name of the server that connects to Vision plus any additional information you wish to send. For example:

  http://www.myserver.com/.../Profile@Company@IBM

If you want to define a link within the Profile method that runs Profile2, you could include the following print statements in your Vision code:

  "<a HREF='http://myserver/.../" print ;
  "Profile2@IBM'>" print ;
  "IBM Profile 2 Link" print ;
  "</a>" printNL ;

When this report is displayed in your Web Browser, the text IBM Profile 2 Link will be represented as an anchor. If you click on this link, your server should ship the string Profile2@IBM to Vision . When Vision receives this information, it sets the current application to Profile2 with the parameter IBM and returns the document created. The Profile2 method must be defined at the ApplicationWS class. For example:

  Interface ApplicationWS defineMethod: [ | Profile2 | 
       !id <- parameterList at: 1 ;     #- IBM
       id as: ^global Company .
       do: [ "This is Profile 2 for: " print ; 
             displayInfo ;
           ] ;
  ] ;

FormatTools: Link Creation Messages

A number of messages have been defined for the FormatTools class that aid in producing the links:

---

buildLinkForApp: app withLabel: label andParams: plist

This message creates an Html anchor. The server URL is formed using current session settings followed by the application name and any parameters, separated by the @ character. This message formats an Html anchor statement in the form:

  <a href=
     "http://server/.../app@p1@p2@p3/?globalDate=yyyymmdd"
  >label</a>

---

buildLinkForApp: app withLabel: label

This message creates an Html anchor. The server URL is formed using current session settings followed by the application name. This message formats an Html anchor statement in the form:

  <a href=
     "http://server/.../app/?globalDate=yyyymmdd"
  >label</a>

---

buildLink: link withLabel: label

This message creates an Html anchor. The link parameter is displayed as the URL of the HRef attribute. This string is displayed inside double quotes. This message formats an Html anchor statement in the form:

  <a href="link">label</a>

---

buildLink: link withPath: path withLabel: label

This message creates an Html anchor. The path and link values are used to generate the URL for the HRef attribute.

---

buildImage: file withPath: path withAlt: alt

This message creates an Html image statement in the form:

  <img src="imageFile" alt="alt" >

where the string imageFile is generated using the file and path parameters.