Detailed Description of a WebZ Session - continued
Start Page, Stage 1, Stage 2, Stage 3
Stage 3: WebZ builds the Home screen in the interface.
In Stage 2, we examined how WebZ processes a request for a new user session. If the request is processed successfully, then WebZ builds the Home screen and sends it to the web browser. At the end of Stage 2, the request had been processed successfully and the RequestManager had begun the process of building the Home screen. To do this, the RequestManager had to locate the homeframe.html file.
Order of Events
The RequestManager processes homeframe.html and sends it to the browser.
Because homeframe.html defines a frameset, the browser automatically sends a GET command to retrieve the source files for the frames.
Before we examine the process that builds the Home screen, let's take a look at the finished product as it will appear in the web browser. The Home screen (shown below) is an HTML frameset that consists of three HTML files. The file which defines the frameset is homeframe.html, and it defines the two frames that comprise the Home screen. The source files for the frames are toolbar.html and dblist.html. Each of these HTML files is located in the <WebZ_root>/htdocs/html directory of your WebZ installation.
| Note: |
The Home screen shown here may differ slightly from the one you see in your installtion of WebZ. |
Processing the homeframe.html File
At the end of Stage 2, the RequestManager executed the next command which instructed the RequestManager to locate the homeframe.html file. The RequestManager locates the homeframe.html file and begins reading the file into the user's UserState object. This step is the beginning of the page preparation process, and it is the process by which the WebZ interface is dynamically generated. The following section of the JaSSI user log illustrates what happens as the RequestManager begins reading the homeframe.html file.
1 Class/file load order:
2 ----------------------
3 [/webz_root/htdocs/html/homeframe.html, homeframe.html, \
ORG.oclc.obi.homeframe.html, ORG.oclc.obi.extverb.homeframe.html, \
ORG.oclc.webz.homeframe.html, ORG.oclc.jassi.homeframe.html]
4 [D19990218.T101104.754] [RequestManager.executeCommand()]
5 Enter method.
6 Try to load class = /webz_root/htdocs/html/homeframe.html
7 [D19990218.T101104.756] [RequestManager.readHtmlFile()]
8 Enter method.
9 Reading HTML file : /webz_root/htdocs/html/homeframe.html
10 <oclc-app type="JavaPage" name="initialize">
The RequestManager finds the homeframe.html file in the WebZ document root (line 6 above) and begins reading the file (line 7). The first thing the RequestManager finds in the homeframe.html file is an <oclc-app> tag (line 10). If you take a look at the HTML source code for homeframe.html, you will see the <oclc-app> tag at the beginning of the file.
The <oclc-app> tag is a meta tag at the beginning of an HTML file which contains instructions to be executed by the RequestManager during the page preparation process. The <oclc-app> tag, like all HTML tags, requires a closing /<oclc-tag>.
The opening <oclc-app> tag includes two parameters: type and name. The type parameter specifies the category of instruction to be executed, and the name parameter is the name of the Java class to be executed. In the current implementation of the <oclc-app> tag in WebZ, the type parameter will always be "JavaPage". JavaPage is a Java interface class that defines a runit() method and is important because the Java class specified by the name parameter must implement the JavaPage interface in order for it to be executed in the page preparation process.
Processing the initialize Class
When the RequestManager finds the <oclc-app>, it attemtps to execute the Java class specified by the name parameter, which in this case is the initialize class. To do this, the RequestManager first tries to locate the initialize class using the Class/File Load Order, as shown in the following section of the JaSSI user log:
1 Class/file load order:
2 ----------------------
3 [/webz_root/htdocs/html/initialize, initialize, \
ORG.oclc.obi.initialize, ORG.oclc.obi.extverb.initialize, \
ORG.oclc.webz.initialize, ORG.oclc.jassi.initialize]
4 [D19990218.T101104.792] [RequestManager.executeCommand()]
5 Enter method.
6 Try to load class = /webz_root/htdocs/html/initialize
7 Try to load class = initialize
8 Try to load class = ORG.oclc.obi.initialize
9 [D19990218.T101104.802] [initialize.runit()]
10 Enter method.
11 [D19990218.T101104.804] [initialize.runit()]
12 Exit method.
The RequestManager locates the initialize class (line 8) and runs it. The initialize class executes in line 10 and completes execution in line 12. The purpose of the initialize class is to set default values within the UserState object in preparation for the new session.
Entity Substitution on homeframe.html
After processing the initialize class, the RequestManager begins a phase called entity substitution. In this phase (which, remember, is still part of the page preparation process), the RequestManager searches the homeframe.html file for embedded entities and replaces them with their equivalent values. The following section of the JaSSI user log shows the beginning of the entity substitution phase:
1 [D19990218.T101104.802] [initialize.runit()]
2 Enter method.
3 [D19990218.T101104.804] [initialize.runit()]
4 Exit method.
5 [D19990218.T101104.806] [RequestManager.doEntitySubstitution()]
6 Enter method.
7 Entity type = ';'
8 Entity = 'StyleTable.pages.toolbar'
9 Entity Value = 'html/toolbar.html'
The RequestManager begins the entity substitution phase in line 5. The first entity it finds is a StyleTable entity (line 8). If you look at the source code for the homeframe.html file, you will see this StyleTable entity within the HTML.The RequestManager then replaces the entity with its equivalent value (line 9).
This particular point in the page preparation process introduces two important concepts: entities and entity values. If you are familiar with HTML then you know that entities are placeholders for values. The entity is replaced with its equivalent value either by the web browser or the web server. A common example of an HTML entity is the copyright symbol. In HTML, the entity for the copyright symbol is the following:
When displayed in a web browser, the copyright entity is substituted for its equivalent value, ©.
Entities and Entity Syntax in WebZ
In WebZ, entities are used in much more sophisticated ways than simply as placeholders for character values (as in the HTML example above). They can be placeholders for entire blocks of HTML code, for example, rather than for a single character. Entities can also launch Java classes that generate, evaluate, or otherwise manipulate values that in turn are substituted for the entity, or for other entities. The flexibility of entities within WebZ is practically limitless, and it's this very flexibility that allows you to customize the WebZ interface to meet your needs.
Types of Entities
In general, there are five types of entities used in WebZ.
- HTML entities.
This is the standard HTML entity set that all web browsers support and
which we discussed above using the copyright symbol.
- WebZ entities. A WebZ entity is a placeholder in the HTML code for a value that exists in the user's UserState object. A WebZ entity begins with an ampersand ( & ) and ends with a semi-colon ( ; ). The entity name can be any combination of alphanumeric characters.
&recordstamp;
&no_recall;
&my1stentity;
The context,
StyleTable, and Format Display entities types described below are all
WebZ entities but with special rules regarding their syntax and usage.
&context;
&StyleTable.pages.toolbar;
The StyleTable entity begins with "&StyleTable." The "pages" part is a pointer to the [pages] section of the interface style, and "toolbar" is the specific field in the [pages] section. So, if the user is using the default interface style (which is the case in our example WebZ session), you could manually locate the value of this StyleTable entity by looking in the defaultStyle.ini configuration file. Specifically, you would look at the toolbar field in the [pages] section of this file. Likewise, if the user were using the red interface style, you could locate the entity value in the same manner within the redStyle.ini file.
&FmtDisplay.FullRecord.gadget;
Entity Values and the UserState Object
Now that we've seen the different types entities used in WebZ, let's take a brief look at how the RequestManager locates values for entities during the entity substitution phase.
The UserState object is essentially a storage container for all information regarding the user's WebZ session. Specifically, it's an extended Java hashtable that contains keys and associated values. The values can be literal values (such as "dog", "5", etc.) or they can be other objects entirely, such as hashtables or databases objects, or even Java classes. Regardless of what the value actually is, every value in the UserState object has an associated key.
When the RequestManager locates an entity during the entity substitution phase, it looks for a key in the UserState object that corresponds to the entity. Once it finds the key, it replaces the entity with the key's associated value. For example: When the RequestManager locates the &context; entity during the entity substitution phase, it then locates a key called "context" within the UserState object and substitutes the associated value for the entity in the HTML.
It is possible to actually view the contents of the UserState object in the WebZ interface. To do this, simply add this entity, &StyleTable.DumpTool.gadget;, to any of the HTML files in the interface, such as dblist.html. Next, logon to WebZ via a browser and view the HTML file you modified. The contents of the UserState object appear where you inserted the entity.
Processing the Remaining Entities in homeframe.html
Now that we've learned a bit about entity types and how entity values are stored and retrieved, let's wrap-up the entity substitution process for homeframe.html. Since the basic process for entity substitution is straigtforward (i.e., the RequestManager finds an entity and replaces the value), we'll forego using sections from the JaSSI user log file for the remaining entities. We'll use the log files again when needed, but for now we'll list the entities as a group. As we proceed, refer to the HTML source code for the homeframe.html file homeframe.html.
The following remaining entities are processed in the homeframe.html file:
- Entity: &context;
Value: 'sessionid=01-37542-1619472257'
This is the user's session id. - Entity: &StyleTable.anchors.dblist;
Value: '/WebZ/&StyleTable.pages.searchactive0;:&context;'
Because the user in our example WebZ session is using the default interface style, the value for this StyleTable entity is defined in the dblist field of the [anchors] section in the defaultStyle.ini configuration file. Also, notice that the value of the entity itself includes two other entities - a common practice in WebZ interface design. When this occurs, the RequestManager processes the new entities before continuing on with the remainder of the HTML file. - Entity: &StyleTable.pages.searchactive0;
Value: 'html/dblist.html'
The dblist.html file provides the main features of the Home screen in the web browser. - Entity: &context;
Value: 'sessionid=01-37542-1619472257'
Once again, we encounter the user's session id.
At this point, the RequestManager has located and replaced all entities in homeframe.html. To see the actual result of the entity substitution, compare the original homeframe.html source with the processed processed homeframe.html file.
| Note: |
It is important to remember that the physical file (html/homeframe.html) on your system has not been altered during the entity substitution phase. The entity substitution phase affects only the copy of homeframe.html in the user's UserState object. |
Sending homeframe.html to the Web Browser
Once the RequestManager locates and replaces the entities in homeframe.html, the JaSSI server sends the newly processed homeframe.html file as an HTTP message to the web browser. The JaSSI user log contains the full content of the HTTP message sent to the browser. Because the message length is rather long, presented below are the first few lines of the message simply to illustrate how the HTTP message appears in the log file:
[D19990218.T101104.890] [JaSSI.run()]
HTTP Message Out for threadid: 91935066433811188
Length: 727
48 54 54 50 2f 31 2e 30 20 32 30 30 20 4f 4b 0d HTTP/1.0 200 OK.
0a 44 61 74 65 3a 20 54 68 75 2c 20 31 38 20 46 .Date: Thu, 18 F
65 62 20 31 39 39 39 20 30 33 3a 31 31 3a 30 34 eb 1999 03:11:04
20 47 4d 54 0d 0a 53 65 72 76 65 72 3a 20 4a 61 GMT..Server: Ja
53 53 49 2d 57 65 62 5a 2f 34 2e 30 2e 30 0d 0a SSI-WebZ/4.0.0..
43 6f 6e 74 65 6e 74 2d 54 79 70 65 3a 20 74 65 Content-Type: te
78 74 2f 68 74 6d 6c 0d 0a 43 6f 6e 74 65 6e 74 xt/html..Content
2d 4c 65 6e 67 74 68 3a 20 35 39 39 0d 0a 0d 0a -Length: 599....
0a 0a 3c 21 44 4f 43 54 59 50 45 20 48 54 4d 4c ..<!DOCTYPE HTML
20 50 55 42 4c 49 43 20 22 2d 2f 2f 49 45 54 46 PUBLIC "-//IETF
Building the Home Screen Frameset
What happens after homeframe.html is sent to the browser? If you refer to the earlier section describing the Home screen, you see that homeframe.html defines a frameset containing two frames and that the HTML sources for these frames are toolbar.html and dblist.html. When homeframe.html is sent to the browser, the browser immediately issues a GET command for the HTML source file to fill the first frame, which in this case is toolbar.html.
WebZ receives the GET command for toolbar.html and begins the very same process to handle this request that was used to handle the user's original request to begin a new WebZ session. That is, the JaSSI creates an Action object and RequestManager to handle the request, goes through the Class/File Load Order to locate toolbar.html, performs entity entity substitution on the file, then sends the file to the browser. After toolbar.html is sent to the browser, the browser issues a GET command for the HTML source file for the second frame, dblist.html, and the entire process begins again.
The following sections describe what happens when WebZ processes the toolbar.html and dblist.html files. Since we've already taken a detailed look at how WebZ processes a user request and at the page preparation process itself, the following sections will give just the highlights about the processing of these two HTML files.
Processing the toolbar.html File
The page preparation process for toolbar.html is fairly simple and non-eventful. Unlike the homeframe.html file, there is no <oclc-app> tag in toolbar.html, so there is no Java class to execute prior to the entity substitution phase. There are, however, more StyleTable entities in toolbar.html than in homeframe.html. The following figure and notes describe a few of the more interesting entities:
- Entity: &StyleTable.colors.tooltext;
Value: '#ffffff'
This entity sets the toolbar text color to white. - Entity: &StyleTable.colors.toolbg;
Value: '#006600'
This entity sets the background color of the toolbar to green. - Entity: &StyleTable.images.toolbar;
Value: '/images/toolbar.gif'
This entity specifies the graphic to use in the toolbar. Tip: If you wanted to use your own, custom graphic in the toolbar, you could edit the toolbar field in the [images] section of the defaultStyle.ini file so that it points to your own graphic.
After the RequestManager completes the entity substitution phase on toolbar.html, the JaSSI server sends the newly processed toolbar.html file as an HTTP message to the web browser. The browser responds by sending a GET command to retrieve the HTML source for the second frame defined by homeframe.html, which in this case is dblist.html.
Processing the dblist.html File
The final HTML file needed to complete the Home screen is the dblist.html file. When displayed in the browser, the dblist.html file contains the QuickSearch input box, the Topic List, and the List of Databases available to the user. The file also displays graphical and text links to other sites along the right side and at the bottom of the Home screen.
The page preparation process for dblist.html is a bit more interesting than that for toolbar.html. For starters, the dblist.html file contains an <oclc-app> tag executed prior to the entity substitution phase. The file also contains quite a few StyleTable entities, three of which are of particular interest because they launch gadgets, specialized Java classes that generate the blocks of HTML code. In dblist.html, the gadgets we encounter generate HTML for the QuickSearch box, Topic List, and List of Databases (shown below).
The following is a description of the noteworthy events that occur when dblist.html is processed:
- <oclc-app> tag
The <oclc-app> tag in dblist.html launches the dblistscreen Java class. The purpose of this class is to initialize some interface variables within the user's UserState object. - Entity: &StyleTable.QuickSearchTopics.gadget;
Value:
'<!- Dynamically Generated by quicksearchtopics -->
<INPUT checked TYPE="checkbox" name="TopicArea" value="Articles"> \
<font &StyleTable.fonts.face;><strong>Articles</strong> \
</font> \
<INPUT checked TYPE="checkbox" name="TopicArea" value="Books"> \
<font &StyleTable.fonts.face;><strong>Books</strong> \
</font>
<!- Dynamically Generated by quicksearchtopics -->'
As you can see, the value of this StyleTable entity is a block of HTML code generated by the QuickSearchTopics gadget. The QuickSearchTopics gadget builds the quick search input box using the list of quick search topics defined in the topicNames field in the [QuickSearchTopics] section of the defaultStyle.ini file. If you want to change the topics included in the Quick Search input box, you must change the topicNames field in defaultStyle.ini, AND you must make sure the topics are defined in the ObiTopics.ini file. The comment blocks before and after the HTML code help you locate the block within the HTML source code.
Value:
<!- Dynamically Generated by topiclist -->
<tr><td bgcolor="#dfdcc4" NOWRAP><b><font &StyleTable.fonts.face; \
size="-2"><a href="/WebZ/&StyleTable.pages.searchactive3; \
:&context;?active=3:dbchoice=1:topic=Articles:&ScreenCount++" .\
&StyleTable.targets.searchPage;>Articles</a></font></b></td></tr> \
<tr><td bgcolor="#dfdcc4" NOWRAP><b><font &StyleTable.fonts.face; size="-2">
<a href="/WebZ/&StyleTable.pages.searchactive3;:&context; \
?active=3:dbchoice=1:topic=Books:&ScreenCount++" \
&StyleTable.targets.searchPage;>Books</a></font></b></td></tr>
<tr><td bgcolor="#dfdcc4" NOWRAP><b><font &StyleTable.fonts.face; size="-2">
<a href="/WebZ/&StyleTable.pages.searchactive3;:&context; \
?active=3:dbchoice=1:topic=HumanAffairs:&ScreenCount++" \
&StyleTable.targets.searchPage;>Human Affairs</a></font></b></td></tr>
<!- Dynamically Generated by topiclist -->'
The TopicList gadget generates a list of topics available to the user. The gadget builds this list based on the topics defined in the topicNames field of the [TopicList] section in the defaultStyle.ini file. Each topic defined in the topicNames field must also be defined in the ObiTopics.ini file. To include all topics in the Topic List, use "All" in the topicNames field.
Value: [not shown because of length]
The DatabaseList gadget generates a list of databases available to the user. The gadget builds this list based on the list of databases contained in the user's UserState object, which was defined when the user began the WebZ session.
Once the RequestManager completes the entity substitution phase for dblist.html, the JaSSI server sends the file to the browser. This completes the construction of the Home screen in the WebZ interface. From this point, the user typically selects a topic or database to search.
Using Log Files to Further Investigate the Process
Though our examination of a WebZ session ends at this point, you can use the JaSSI log files to follow what happens within WebZ as the user submits searches, views records, and performs other activities in the interface. To get the most out of the log files, be sure to set the trace levels to ALL for the JaSSI user log using the ssadmin program.