(3 out of 6)
Getting Started on the Tutorial
The tutorials are presented in a step-by-step format. We have included screen shots so that you can verify your steps as you work through the tutorial. By default, a new directory, referred to as the Tutorial Project Directory will be created in your HOME directory. Installed in this directory are several HTML documents and DSQL Objects that are used to create your end-user Web application. It does not matter what directory you are in when you run this script, as it is fully self-contained. Please follow the prompts and supply information as needed. If you do not understand any portion of the tutorial installation script, please see your Systems, Web, or Database Administrator. At the prompt(s) below you may wish to modify the tool, depending upon your skill and your organizations' requirements.
In addition to setting up your Tutorial Project Directory, the tutorial installation script will also create a run script that will bring up the tool with the correct environment.
- You will be prompted 3 times; the prompts are:
- Would you like to change any of the above settings? Y or N <ENTER> to accept the default, which is Yes.
- Is it okay to use this Directory to create a Project Directory? Y or N <ENTER> to accept the default (Yes).
- The final prompt asks if you would like to start Sapphire/Web? Y or N <ENTER> to accept the default (Yes).
Once the tutorial installation script completes, Sapphire/Web will start up automatically. The Project Screen opens.

Figure 3-1 Project Window
- Step 1. Select the Document Manager by clicking on the Icon.
- Document Manager Window opens: select File from the pulldown menu, select Add.
- The Add Window opens displaying four files with .html extensions.
- Using the mouse¯highlight the four files shown in the window
- home.html
- books.html
- book_results.html
- book_detail.html
- Click OK
- Click on the Close Icon, or select File ->Close to exit.

Figure 3-2 Document Manager with four HTML documents loaded
- The Document Manager Window closes, and you are returned to the Project Window.
- Step 2. At the Project Window: select Tools, use the pulldown menu to select Object Bind Editor (Tools->Object Bind Editor), or by clicking on the Object Editor Bind Icon (New Activator).
- Before the actual Object Bind Editor is displayed the Activator Selector Window pops-up.

Figure 3-3 Activator Selector Window
- Step 3. Under Document: select home.html.
- Under Anchors: the selection shows HREF=books
- Click OK.
While still in the Object Bind mode, a new pop-up window appears, called the Open DSQL (Figure 3-4).

Figure 3-4 Open DSQL
- At Object Type: use the down
arrow (Combo Box) to select DSQL - At Server: select (the server you are running on)
- You will be prompted for your Login, (your Username, and your Password).
- Note: If you are unsure of your Login, see your Database Administrator.
- Step 4. At Database: select pubs2
- Under the DSQL Name select (the DSQL object): BD_Get_Title_Types
- Click Ok.
- The first section at the top of the window is to specify your data object, this is the Object Specification box, this function provides information about your database object, and allows you to select different objects. The second section of the window is the Arguments Specification box, and the third section is the Results Specification, for specifying where to place the results. When Steps 5 and 6 have been completed, the Object Bind Editor will look like Figure 3-6
- Step 5. Data Object:
(Shows your Server) |pubs2|BD_Get_Title_Types
- Object Type: shows DSQL
- Bind Name: shows bind1
- DB Vendor: shows either, Sybase, Oracle or Informix
- Arguments<=>Activator: shows home.html<A>books
- (Indicating that the Anchor has become an Activator.)
- Step 6. Displayed in Results Specification Area:
- At Results<=>Template: select books.html.
- (This Step tells Sapphire where to place the results.)
- At the type char(12) label, use the down
arrow to select TitleTypes - (This acts as your Data Drop Site, and places the results of the Get_Title_Types DSQL procedure, in that location in the Template books.html.)
- Click on the Results Detail Dialog Button o to bring up the Results Detail Dialog Box as shown in Figure 3-5.
- At Callback use the down
arrow, select SaPopulateOptions, - Click OK
- The Results Detail Editor tells the Object Bind Editor what output format to use when writing results to your Data Site.

Figure 3-5 Results Detail Dialog Box
- At the bottom of the screen, press the Apply Button
- This will save your changes in memory and the Change Flags in the Object Bind Editor will be reset.

Figure 3-6 Object Bind Editor
- Click OK to close the Object Bind Editor.
- Note: Clicking OK will save the file, and pop down the Object Bind Editor.
- Step 7. At the Project Window: select Edit, use the pulldown menu to select Options ...
- The Options Editor for Project Options pops up.
- At Category, use the down
arrow to select Project - At the Options List; select HTML Startup Document
- Change the value in the Value Field to home.html.
- Click OK to close and popdown the Options Editor.

Figure 3-7 Options Editor for project Options
- Step 8. At the Project Window: select File->Save, then select the Test button

Figure 3-8 Save and Test Button
- Under Messages Sapphire/Web will write the HTML files to the disk and the generated CGI programs (tut1.c and home.c) will be compiled and linked.
- Then the HTML files and CGI executable will be copied to your test.CGI Path (configured by the tutorial install script).
- When successfully completed, the browser will automatically be invoked with home.html. Your documents will be automatically loaded into the current instance of the browser, or a new instance will be invoked.
- Note: If you are using a Web browser other than Netscape, the browser may need to be defined using $SAPPHIRE/bin/sabrowser.sh (See the Installation Guide.

Figure 3-9 Bluestone Generated Web page
- Step 9. In the center of the Book Search Icon, click the left mouse button, to access the first bind, the following occurs transparently:
- Refer back to Results Specification box, Figure 3-6 in the Object Binding Window.

Figure 3-10 books.html Data Site
As Sapphire/Web reads in HTML documents, anything it finds that begins with "##Sa_"
and ends with "##"
is considered to be a Data Site, and the text between the delimiters becomes the name of the drop site that you see in the Object Bind Editor. Using this mechanism you can put Data Sites almost anywhere in your HTML documents.
<OPTION>##Sa_TitleTypes##</OPTION>
- Step 10. Click on the Category Box. You will see a populated listing of topics.

Figure 3-11 Dynamically Populated Options Menu
Previously, the Options Menu in books.html only contained a marker that acted as a placeholder for data objects. Now the placeholder has been replaced with real values from your database. You may choose to leave the Netscape browser up while you complete the Book Query Bindings, or close it, to conserve screen space.
Creating the Book Query Bindings
The next step is to bind the "Submit Query" button in the Book Query HTML document (books.html) to another DSQL object.
- Step 11. From the Project Window, select the Object Bind Editor (new activator).
- In the Activator Selector Window pop-up, under Document choose books.html (as your document)
- Under Forms: select ACTION=BookForm as your activator,
- Press Ok.
- Note: For each HTML document you choose in the Activator Selector, you should only choose a Form OR Anchor activator. You will be choosing a single activator from the two activator types available¯Forms or Anchors.
- Step 12. At the Open DSQL Window pop-up, choose DSQL, as the Object Type.
- At the Server: select the appropriate server.
- At Database: select pubs2 database.
- Under the DSQL Name: select BD_Title_By_Title_And_Type, as the activator,
- Press Ok.
- At this point You have told the Object Bind Editor about your activator, and, have selected the data object you wish to call.
- Step 13. Since the DSQL object we just selected requires two arguments, use the Arguments Specification area in the Object Bind Editor to select the Title and Category HTML objects in books.html. (Figure 3-12)
Why is "books" listed differently in the Activator Selector?
When the Activator Selector dialog box appeared, you may have noticed that the books Anchor was listed as just "books", not "HREF=books". This is a visual indication of which Anchors in your documents are being used as Activators, and which are not, (e.g., when listed as "books", that Anchor has been bound, and when listed as "HREF=books", the Anchor has yet to be bound).

Figure 3-12 Object Bind Editor
- Step 14. Arguments for the DSQL object now need to be specified,
- At Title WRAP: select TitleText for title argument,
- At Category WRAP: select CategoryOption for the category argument.
- Note: In the Arguments and Results areas there will only be one Combo box "active" at a time. You will need to click in the area that you wish to change to make the Combo box appear, then make your changes using the Combo box.
- To finish this object binding, specify where to place the results of the DSQL object.
- At the Results<=>Template: select book_results.html,
- At title_id: select TitleHotList.
- At title varchar: select TitleHotList
- You may have noticed that we are telling the tool to place two database result columns (title_id and title) in the same data drop site (TitleHotList). Sapphire/Web automatically handles situations where multiple results are placed in the same data drop site. Because of this special handling, you will also need to select one population method from the Results Detail Editor for all occurrences of TitleHotList.
- Press the First Results Detail Editor button found to the right of the TitleHotList selection. The Results Detail Editor pops up.
- Select SaPopulateHotList from the Callback combo box and press OK.
- The Results Detail Editor disappears and the Object Bind Window becomes active.
- Click OK to save your changes and close the Object Bind Editor. The Project Window becomes the active window.
- Step 15. The Project Window pops-up.
- Now that these changes are complete, save your project using the File->Save menu.
- Press the Test Icon
- Note: You will now be able to test the application as before, except that you can now interact with the second screen (books.html). See Figure 3-13.
- books.html: Under Book Query: At Title: type %. This is the SQL wildcard. books.html: At Category: Use the pulldown menu and select Business.
- Press the Submit Query button.

Figure 3-13 Book Query page
The results you see in book_results.html are based on the two arguments ("%" and "business") you supply to the BD_Title_By_Title_And_Type DSQL object. Your results should approximate Figure 3-14:

Figure 3-14 Book Results page
Notice that each item listed is a book title that comes from your database. Also notice that they are all URLs because we choose to populate a Hotlist. The URLs currently point to nothing, but in the last portion of this tutorial we will create the object bindings needed to turn them into activators that provide details about each book.
(3 out of 6)