HTML Markup and Sapphire/Web Server Applications

When working with Sapphire/Web it is important to understand the mark-ups the tool performs on your HTML. Sapphire/Web binds your Data Objects to your HTML files. Activators are HTML Anchors and Forms. To create an Anchor enter the following HTML fragment:

<A HREF="AnchorName">Title</A>

When you select this Anchor as an activator, Sapphire/Web will rename the Anchor. The code, for example, could read:

<A HREF="http://heartofgold/cgi-bin/ 
MyProg.cgi?FNC=authors__Asamp_html">Title</A>

The HREF has been changed to call your Server Application with an argument.

The first part of the HREF, up to the "?", is the Universal Resource Locator (URL) of your Server Application. The pathname is from the "test.CGI URL" option for the project with the Server Application's executable name appended.

The second part, after the "?", will be either argv[1] to your Server Application or the contents of the "QUERY STRING" environment variable. You can use the argv[1] approach for debugging. In the above example type this at the command:

MyProg.cgi 'FNC=authors__Asamp_html'

The Server Application will print to standard out what it would have sent back to the HTML browser. In the xxgdb debugger type:

run FNC=authors__Asamp_html

and debug the Server Application.

The HTTP server will most likely set the "QUERY_STRING" environment variable. Either way, the Server Application will read the part after "FNC=". This is the string name that is used to lookup the activator function for that bound Anchor.

The function Aauthors is a static function written in the HTML-related module. The name is created from the name of the Anchor with "A" prepended. The string name authors__Asamp_html is used as a lookup to invoke the function Aauthors. This string name is derived from the anchor name and the modified HTML filename with "__A" inserted between.

The Server Applications that Sapphire writes can be called from any anchor. For example, the main page of a project could be called from a line saying "Click here to begin" instead of a query form or submit button, where "here" is the anchor that would be used for the first bind. If you want to play the same HTML document somewhere else, you can copy the URL which HTML generated in one document and paste it into a second document. A better approach to this would be to alias the Anchor.

The registration of that Lookup String is in the registration function for that HTML-related module. The registration function is not static, it is called from Main, and would have the name R_samp_html in this case. This name is derived from the modified HTML filename with "R_" prepended. Sapphire/Web performs all this markup and naming transparently, of course. The activator function is then invoked executing each of your data object requests.

There are two different methods in which to run, depending on whether or not you are using HTML templates. If you have bound a column to a data site in the Object Bind Editor then you are using HTML templates. The Sapphire/Web Server Application will then carry out all object requests and store the results in the Server Application's memory. All templates encountered from the bound sites are added to a list of HTML template files to "play". Duplicates are eliminated and the HTML files are played in the order in which they were added.

Although Sapphire/Web supports the use of multiple templates per activator function, you will rarely use more than one. The reason is that the files being played must add up to a single complete HTML file (as far as the HTML browser is concerned).

In order to play an HTML file, a Sapphire/Web Server Application does the following:

The Server Application must find the HTML templates, then the directory is set through the project option, test.HTML Path.
The Server Application will change its current working directory to the intended directory, read in the HTML template, and print out sections of your template file.
The Server Application looks for a data site when doing this; the Data Site is represented in the HTML files as:

##Sa_SiteName##

: where SiteName is the site's name (as bound to a column in the Object Bind Editor) or a site value for loop constructs or embedded SQL.

Each Site Name is processed as it is encountered.
If the site contains embedded SQL, the SQL might be processed, depending on whether certain projects are set. Embedded SQL sites look like:

##Sa_SQL=select * from authors##

For other sites, the Server Application will determine the Population Callback to invoke with the data returned by the data object. This may be called multiple times during the playing of the Server Application. In the following example the Population Callback for "LastName" is invoked 3 times.

The author, ##Sa_LastName##, currently lives in the state 
of ##Sa_state##. ##Sa_FirstName## ##Sa_LastName## can 
be reached at ##Sa_phone##. For titles written by 
##Sa_LastName## click here. ##Sa_HotList##<A 
HREF="AnchorName" >Title</A>.

When this fragment is being "played" the first fragment, "The Author," is written to standard out. The Population Callback for the site LastName is invoked. This callback may write Ringer to standard out. The next fragment, up to the next site, is written to standard out. Then the next site is processed. You can think of this as substituting data into the sites, because that's what the HTML user will see. The last site, "Hotlist", should be bound as a Hotlist and the Anchor bound as an Activator - to bring up the titles for that author.

Sapphire/Web allows the developer to write the HTML fragment in any authoring tool. As the documents are prepared, users can select data sites by clicking the insert ##Sa_## and get dynamic population at runtime. The user need not know database table or column names.

However, the method by which the developer/user names the sites can be used as a design specification to the Sapphire/Web developer. This is the document-centric concept of HTML, and a fundamental concept of how Sapphire/Web works. One option is to use a source repository. Sapphire/Web provides hooks to these. (See Scripts Used by Sapphire/Web in Chapter 7 for more information). Also, Sapphire/Web provides some capability to work concurrently on HTML files through its refresh mechanism.

Here is a situation you may encounter. The Sapphire/Web developer completes the application and then goes on to other projects. The original author decides that the code fragment should be reworded as follows:

The author, ##Sa_FirstName## ##Sa_LastName##, currently 
lives in the state of ##Sa_state## and can be reached 
at ##Sa_phone##. For titles, click here: 
##Sa_HotList##<A HREF="AnchorName" >

Even after this change the application works seamlessly with no need to design, build, or test. At the next click every one in the enterprise sees the new format - Sapphire/Web gives you dynamic, live documents.

The above example will look good to the HTML user even if there is only one row or author returned. This will happen if the original anchor was bound as a HotList with the Primary Key for the Authors Table.

Suppose you wish to duplicate this text for each author returned; for example, an on-line address book of authors writing for a certain publisher. To accomplish this, insert the indented code lines above between the ##Sa_BeginLoop## and ##Sa_EndLoop## comments. This construct, called a Sapphire/Web loop, has special meaning to the "playing" of HTML files.

When a Sapphire/Web Server Application sees this construct, it will "play" the fragment between the ##Sa_BeginLoop## and ##Sa_EndLoop## comments repeatedly for each row, as described for normal "playing", until any site in the fragment runs out of rows. Note that the fragment is "played" once even if no rows were returned.

Sapphire/Web allows you to add your own Population Callbacks. For these calls, you receive a data structure with all the data returned. When your callback is called outside of the loop structure, all the rows are in the data structure. When called within a loop construct, the data structure contains only one row, the current row derived from the current loop counter. When you write a Population Callback, write it to be generic, and the mode will be transparent to your Population Callback.

The FILE= Tag and Server-Side Includes

Sapphire/Web supports the use of the following site markup in a template file:

##Sa_FILE=filepath##

where filepath is the path to a file. When Sapphire encounters this markup while playing a template file, the contents of the file are substituted for the tag. Note that the path must be valid for the Server Application.

When Sapphire/Web encounters this tag, its current directory will be the HTML directory that was specified for the project. The contents of the file are not processed in any way. For example, if the file contained other sites, they would not only not be processed, but the sites would actually appear in the returned HTML. This capability is a form of server-side include. The following file path spec works on both the UNIX and Windows versions or Sapphire/Web:

##Sa_FILE=../librarydir/JavaScripts.js##

By using this relative path specification, you can include files from a common area. This way, if you are including the same file in multiple projects, you only need to have one copy of the file and that makes the job of keeping things up-to-date easier. The above example assumes that all your projects have an HTML directory option such that the projects are at the same directory level. This makes the task of moving this "site" easy since all you need is to copy from the parent directory on down the tree.

Activators

In order to implement Activators in an Object Binding, it is necessary for Sapphire/Web to control the URLs associated with anchor tags <A> and forms <FORM>. To control these URLs the developer must name forms and anchors which will be used as Activators in Sapphire/Web.

A suggestions for naming Activators when creating new HTML is:

<FORM ACTION="some_name" METHOD="post"> ... </FORM>
<A HREF="some_name"> ... </A>

After using this method, some_name will appear in the Activator Selector, and the developer can easily select the appropriate Activator when binding data. They will appear as follows:

ACTION=some_name
HREF=some_name

The rule is that whatever is in the ACTION and HREF sections of the tag will be the name that shows up in the Activator Selector, without the quotes. Therefore, if you re-use an existing HTML document, the Forms and Anchors will appear as follows in the Activator Selector:

ACTION=www.bluestone.com

Once you select one of these default names in the Activator Selector, it will become the true name if the Use Default Name toggle is selected. If the Use Default Name toggle is not selected, you will be prompted for a name. Names can contain only alphanumerics and the underscore character, and must be unique within an HTML document.

[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com