Empress Web HTML Toolkit Applications are written as collections of HTML pages and calls to a CGI program (ehsql.cgi or ehlink.cgi). HTML Forms are used to input data, and special markup tags are used to connect to the database. Information is referenced by several methods. Most of these take the form of the name of the attribute, variable or parameter in question surrounded by double or triple delimiting characters. This is similar to a UNIX operating system shell like csh, where environment variable values are obtained by the name of the variable preceded by a dollar sign, as in: $PATH.
Different kinds of information have different kinds of delimiters:
Any character can be escaped with a backslash to print out the actual character instead of the results of the evaluation. For example:
$$MSHYPERPATH$$ : displays the value of environment
variable MSHYPERPATH
\$\$MSHYPERPATHPATH\$\$ : prints the string $$MSHYPERPATH$$
The backslash itself can be printed with a double backslash.
There are a few ways to phrase a database query in the Toolkit. But when a returned data value is referenced in an HTML document, it is always referenced as the name of the attribute surrounded by double percent signs. We will sometimes call these items percent variables. For example:
<h1>The employee's first name is %%first%% </h1>
Often, queries can return many records, and usually the HTML page handling the display will organize such query results into tabular form. In this situation, a triple percent preceding the attribute name will suppress display of duplicate values of that particular attribute, so it will appear somewhat like the display of an SQL query with a GROUP By clause. For instance,
%%department%% %%employee_num%% <p>
inside a query in an HTML form might access a database table and display the following information on the browser:
sales 1526 sales 0607 sales 0984 tech 0345 tech 0645
whereas the same line with a triple percent in front of the department attribute:
%%%department%%, %%employee_num%% <p>
would display as:
sales 1526
0607
0894
tech 0345
0645
Of course it wouldn't line up nice like that on the browser unless it was inside HTML TABLE tags.
The tools ehsql:writer and ehsql:select both provide methods for querying the database, and make the results available in percent variables.
Whenever an application requires user input, an HTML form is necessary. Several tools are provided for editing database records, as well as for other database administration functions.
Within HTML forms, form fields are declared. These are objects which consist of a variable name, and a means by which to set the value. The means can be user input such as text boxes, pull down lists, and radio buttons, or default values can be set without user interaction. When the submit button of a form is pushed, the information is packaged up and sent to a CGI program, declared in the ACTION of the form, and this CGI program uses the variables and their values. ehsql:update and ehsql:writer are two such programs. They take the information and edit the specified database tables. As well as taking the form as input, they take an HTML file as input. This file becomes the next page displayed on the browser after they finish operating. The values of the form variables are available on that page as the name of the variable surrounded by double ampersands. In this way a bunch of HTML pages become connected into an application, connected to each other by ampersand variables, (and URL parameters, described later) and connected to the database by percent variables. For instance, imagine two simple HTML files:
<html>
<form method=post
action="/bin/ehsql.cgi/file2.ehtml">
Type the value of X <input type=text name="x"> <p>
<input type=hidden name="y" value = "2.5">
<input type=submit
value="push to submit these variables to file2.ehtml">
</form>
</html>
|
<html>
<hr>
the value of X is &&x&&
<hr>
the value of Y is &&y&&
</html>
|
This little example application asks the user to type in the value of one variable, then sets the value of a second variable in a hidden (undisplayed) field. Both are posted through the tool ehsql:writer, which is given a second file file2.ehtml as input as well. The form variables from file1.html are referenced as ampersand variables in file2.ehtml and displayed. No database is accessed in this application, it just demonstrates the passing around of form variables. The real trick is in the URL specified in the ACTION of the form. All paths are from the HTTP server DocumentRoot. The first path is the path to the ehsql.cgi program. This is /My-bin/ehsql.cgi. The second path is to the document file2.ehtml. The question mark specifies the first parameter of the URL, which always should contain the name of the specific tool desired. In this case it is ehsql:writer, a general purpose tool used for entering direct SQL statements. These tools are explained in their own sections.
Normally, referencing an ampersand variable with no value will generate an error. This can happen for instance if the user doesn't fill out the relevant field. Depending on the application, this can be a valuable check, or it can be annoying. If it is desired that the variable needn't have a value, place a third ampersand in front. Then, if it has no value, it will simply not display. For instance:
<hr>
the value of X is &&&x&&
It looks funny, but it works.
SELECT lastname FROM employee WHERE firstname = "&&Bob&&"
However, there are two problems with this:
SELECT lastname FROM employee WHERE firstname = "??Bob??"
For those who are interested, this binds the form data to the SQL statement. If you don't know what this means, it doesn't really matter. What's important is the effect. Basically this allows any data to be placed in the SQL.
If the form value is not filled out the Toolkit will still transmit an error back to the client. However if you use three question marks in front of the variable:
SELECT lastname FROM employee WHERE firstname = "???Bob??"
The variable will be replaced by NULL.
Note that:
The question mark notation even allows binary data to be added to the SQL statement providing that the eh-binary keyword is used in the HTML form. And you can't use binary data in a where clause
Addresses, whether on the URL line of a browser, or in the ACTION clause of a form, can take parameters. The format is a question mark at the end of the actual address, and then a list of parameters separated by plus signs (+). If posted through ehsql.cgi to another file these parameters will be available with the keyword eh-dbase-key followed by the number of the parameter in question. eh-dbase-key gets its name from the pages of history, it has nothing to do with keys or databases anymore.
One could rewrite the ampersand variable example as follows:
<html>
<form method=post
action="/bin/ehsql.cgi/file2.ehtml?bruce+2.5">
<input type=submit
value="push to submit the URL parameters to file2.ehtml">
</form>
</html>
|
<html>
<hr>
the value of parameter 1 is eh-dbase-key1
<hr>
the value of parameter 2 is eh-dbase-key2
</html>
|
Any of the system environment variables of the HTTP server, and the Common Gateway Interface, can be displayed on a HTML page, along with any resource variables set in the Toolkits resource file. These variables are referenced by adding the name of the variable to the HTML template in between pairs of double dollar signs:
<html>
the value of the environment variable MSHYPERPATH is $$MSHYPERPATH$$
</html>
For these to be available, the page they appear in must be called from an ehsql.cgi tool.
The most significant environment variables used by the Toolkit is defined in Resource Variables chapter of this manual and the most significant Common Gateway Environment Variables is defined in Appendix A of this manual.
Any text appearing between double underscores is assumed to be a string found in the directories pointed to by MSUSERPATH, and will be replaced by its corresponding language-specific string. For instance, it is possible to write a completely generic application which will change its display language simply by specifying a variable.
<html> __greeting__ </html>
can be defined to display as any of:
Hi Bonjour G'Day
depending on the setting of the MSUSERLANG variable. The mechanism works as follows:
MSUSERPATH is set in the ehtml.ini file to point to a directory. This directory must be called nls. For example, if you create your application's nls directory in /usr/joe/ehtml/apps/nls then set MSUSERPATH to /usr/joe/ehtml/apps.
Note also that the nls directory you create is for your application, it should not be the standard nls directory $MSHYPERPATH/nls which holds the Toolkit's runtime messages in various languages.
In your own nls you should create other directories, one for each language desired. For instance, to create US English language support, create a directory with a name like en_US. Within this directory create a file called html.rtm.
Within the file, use a format as follows:
labels
{
Corn_Meal: "Grits";
Football: "Soccer";
}
msg
{
CCwarning: "Warning: This application does not encrypt form information. Users providing credit-card numbers do so at own risk"
}
The labels section contains the symbols which will be referenced with the underscore variables. Each line must give a symbol ending in a colon, followed by a quoted string ending in a semi-colon. The symbol is the text which will be written between double underscores in the .html and .ehtml files, and the string is what displays.
If an underscored symbol appears in an application but isn't defined in a developer's .rtm file, the Toolkit will search for the symbol in the ehtml.rtm file, which should not be altered.
The msg section is set up and used exactly the same way, except you must use __symbol__MSG to reference them. Maybe longer strings should go in there.
Before it can be used, html.rtm must be compiled with the utility emprtmc. The syntax is:
$MSHYPERPATH/ehtml/bin/emprtmc -o html.nls html.rtm
This tells the utility to compile the contents of html.rtm into the language file html.nls. emprtmc is found in the bin directory of the Toolkit installation.
Back up your html.rtm file, and don't get the syntax backwards, because the emprtmc utility can easily overwrite your source file.
To use a new language properly, you will also need a directory with that language name in the $MSHYPERPATH/nls directory, with a corresponding ehtml.rtm file written and compiled. If English Toolkit messages are fine, simply creating the directory and softlinking the ehtml.nls file from en_US will do fine.
Once the above files are in place, and an application is written with underscored strings anywhere language support is needed, a language can be turned on by including the parameter MSLANG:name_of_language_directory as the last parameter of a URL calling a Toolkit program. In the US English example, one might have an ACTION of a form read:
action="/My-bin/ehsql.cgi/helpform.ehtml?MSLANG:en_US"
When ehsql.cgi processes the helpform.ehtml file, it will look up any underscored language references in the html.rtm file it finds in the $MSUSERPATH/en_US directory.
It is only necessary to specify the language on the URL line once, say at the starting page of an application. After this, simply including the parameter MSLANG:eh-language as the last parameter in the calls to subsequent pages will keep the application displaying in the language initially set. That is to say, if it is desired that the user select a language from a pull-down list at the start of a Toolkit application, and this is used to set MSLANG on the URL line, it is not necessary for you as a developer to keep track of that language and set it every page.
If a certain language is to be used throughout an entire application, then the value of MSUSERLANG can be set in the ehtml.ini file, and the MSUSERLANG parameter can be left out of the URL line. If MSUSERLANG is included as a URL parameter, it will override the setting in the ehtml.ini file for that call only.
If error logging is desired in a different language than the displayed one, the variable MSLANG can be set in the ehtml.ini file to the name of a directory under MSUSERPATH. This will cause messages to write into the HTTP server log file in the language specified by MSLANG, not MSUSERLANG. It will not affect the browser output of the application at all.
Note that when written into the ehtml.ini file, MSLANG controls the message-logging language, and MSUSERLANG controls the application display language. When specified as the last parameter of a URL, MSLANG controls the application display language. There is no way to set the message logging language from the URL line.