[Prev] [Top] [Contents] (2 out of 2)

Introduction

Before embarking on this tutorial, you should be familiar with the various elements of Sapphire/Web, by reading the preceding chapters. Note: Your System Administrator (or the person who installed Sapphire/Web) should have installed the Tutorial files supplied, in the Sapphire/Web Installation Guide. The files are configured for your HTTP server and database. Be sure that this installation has been completed.

In this Tutorial you will build an HTML database application, that demonstrates key features of Sapphire/Web. Once you have completed this tutorial, you will understand how to:

Creating a new Project Directory for this Tutorial

To ensure that you do not damage other projects created with Sapphire/Web, you will need to create a new directory for this tutorial. You can put this directory anywhere on your file system, that you have write permission. Use the mkdir command to create the directory:

mkdir tut3
Change your current directory to the new project directory:

cd tut3
Copy HTML files to your project directory:

cp $SAPPHIRE/tutorials/tutorial3/html/* .
Start Sapphire/Web: saweb tut3.pj &

Working with Sapphire/Web

After you have run Sapphire/Web, the Project Window pops-up, displaying the tools, and pulldown menu (see Chapter 1, of this Guide, for a detailed view of the Project Window.

The Object Editor

The Object Editor provides a way to Create, Modify, and Delete Data Objects. Data Objects can be Stored Procedures from the database, Dynamic SQL, Files, Functions and Executables. In this Tutorial we will be creating File and Executable Data Objects. See the Reference Manual for a detailed description of functionality, and use of Object Editor.

We are going to create a file, by creating a data object, using the Object Editor. We will be able to read this file from the disk, on the machine that the HTTP server is running on. The file will contain a list of names, which will consist of two columns (first name and last name). The actual name of the file on the disk is going to be gbook.txt.

Step1. At the Project Window, select Tools from the pulldown menu, then select Object Editor (Tools>Object Editor) or press the Object Editor Icon to open the Object Editor.
From the File pulldown menu in the Object Editor select New
At Object Type use the down arrow, select FILE, then type guestBook in the selection text field.
Press OK.
For File Name type: gbook.txt
Step 2. You must tell the Object Editor how to split up the contents of the file, in this case, two columns. We do this by specifying Column and String delimiters.
A Column Delimiter specifies what character separates the columns.
A String Delimiter specifies what character will be placed at the beginning, and end of each of the column, in a row of data.
Note: You will need a String Delimiter, if there is the possibility that the Column delimiter is part of the value in a column.
Step 3. For Column delimiter type: , (a comma)

Figure 5-1

For String delimiter type: " (a double quote)
Now we can name the columns that are going to be in our file.
Under the Delimited Column Names type: firstName
Press the ADD>> button
Under the Delimited Column Names type: lastName
Press the ADD>> button
The Object Editor Screen should look like Figure 5-1. Save the file object by selecting SAVE under the Object Editors File Menu

Now that we have created the guestBook File data object, it will be easy to write the append version of the file object. A file object with a mode of append allows you to add data to the bottom of a file. Since we already defined the delimiters and the column names when we created the guestBook data object all we have to do is change the File Mode to append and save the data object to a new name.

Step 4. Click on the Append Button in the File Mode radio box
Press the Save As Button under the Object Editors File Menu
In the window type: guestBook_append
Press OK
From the Object Editor select File->Close

The Document Manager

The Document Manager allows you to manage the HTML Documents that exist in your project. You can create new documents, add documents, edit documents and preview documents from the Document Manager. All of the HTML files needed for this tutorial have been delivered with Sapphire/Web. Below you will add these documents to your project.

Step 5. From the Project Window select Tools from the pulldown menu, select Document Manager, (Tools>Document Manager) or select the Document Manager Icon.
From Document Manager double-click the Add HTML Icon
From Add Document window select all of the HTML files
Press OK
Your Document Manager window should like Figure 5-2.

Figure 5-2

To see what these HTML files look like, you can click on an item in the HTML Documents List and select Preview from the Edit pull down menu in the Document Manager. Your browser will display the selected HTML Document. You should preview index.html to see the first document that will be shown when this tutorial is tested.
Choose File->Close at the Document Manager.
Step 6. At the Project Window select Edit, use the pulldown menu to select Options Edit (Edit>Options Editor).
At Category use the down arrow, select Project.
Select the HTML Startup Document Option
Press the ... button to open the HTML Startup Document window.
Click on the index.html and Press OK
Press OK to close Options Editor

Object Bind Editor

In Tutorial 1, you used the Object Bind Editor to bind DSQL Data Objects to HTML templates. In this Tutorial we will bind the File Data Objects that you just created to the HTML templates. You will also bind NULL Data Objects to HTML documents.

The first binding that you are going to create will be defining what happens when you press the SignBook anchor in the index.html document. When this anchor is pressed the CGI will play the signbook.html template. There is no dynamic data on this page so we will use a NULL data object.

Note: We use NULL data objects several times in this tutorial to bring up another HTML document. This same functionality can be done with standard HTML links. The main purpose of a NULL data object is allow you to add Activator Code and call functions in the Network Object Toolkit API without the need to get data from a data object. This topic is very advanced and will not be discussed in this tutorial. For more information about using the Network Object Toolkit API please refer to the reference manual.
Step 7. From the Project Window Select the Object Bind Editor (New Activator) Icon. This will bring up the Activator Selector Screen
Under the Document list, select index.html
Under the Anchors list select HREF=SignBook
Press OK to close the Activator Selector.
From the Object Type use the down arrow, select NULL
Press OK
From the Results<=>Template use the down arrow, select signbook.html
Press OK
The next binding will be defining what happens when you press the SeeBook Anchor in the index.html document. When this Anchor is pressed the CGI will play the seebook.html template. The guestBook File Object will be used to populate the dynamic data in this document.

Step 8. Under the Project Window select Object Bind Editor (New Activator Icon). This will bring up the Activator Selector.
Under the Document list select index.html
Under the Anchors list select HREF=SeeBook
Press OK to close the Activator Selector.
Under Object Type select FILE.
In the File Objects list select guestBook
Press OK
In the Results<=>Template use the down arrow, choose seebook.html
Bind the firstName Result Argument with the firstName Data Site.
Bind the lastName Result Argument with the lastName Data Site
Press OK
The next binding will demonstrate the Submit Button function, on the form in the manform.html document. When this button is pressed the CGI will append what the user entered into the form to the end of the guest book file and then show the new contents of the guest book file to the user. Two bindings will be created for this activator. The guestBook_append file object will be used to add the data to the file and the guestBook file object will be used to populate the dynamic data in the seebook.html document.

Step 9. From the Project Window select the Object Bind Editor (New Activator Icon)
Under Document list select signbook.html
Under Form select ACTION=FormAction
Press OK
From the Object Type use the down arrow, select FILE
Select guestBook_append
Press OK
Bind the firstName Argument with the FirstName Form Element
Bind the lastName Argument with the LastName Form Element
Press Apply
Press the Data Object Button
From the Object Type use the down arrow, select FILE
Select guestBook
Press OK.
In the Object Bind Editor from Results<=>Template choose seebook.html
Bind the firstName Result Argument to the Firstname Data Site.
Bind the lastName Result Argument with the Lastname Data Site.
Press OK

What is an Alias?

An Alias is when one Activator does exactly what another Activator does. Using aliases cuts down on the amount of work required to build a project, because you wont have to define the same bindings several times.

The first alias we are going to create will cause the SignBook Anchor in the seebook.html document to execute the same code that is called when you press the SignBook Anchor in the index.html document. As you may remember, the SignBook Anchor shows a Form for the User to enter a name.

Alias Manager

The Alias manager takes care of Aliases for a project. They can be added, deleted and queried from the Alias Manager. The Alias Manager can be invoked from the Project Window and the Object Bind Editor.

Step 10. From the Project Window use the Tools pulldown menu and select Alias Manager (Tools>Alias Manager)
From the Activator use the down arrow, select index.html<A>SignBook
From the Alias Screen press the Add Alias button
Under Document List select seebook.html
Under the Anchor List select HREF=SignBook
Press OK
The next alias we are going to create will cause the SeeBook anchor in the signbook.html document to execute the same code that is called when you press the SeeBook anchor in the index.html document.

Step 11. From the Activator combo box select index.html<A>SeeBook
In the Alias Manager press the Add Button
In the Document list select signbook.html
In the Anchors list select HREF=SeeBook
Press OK
In the Project Window select File->Close.
Select File-> Save.
From the Project Window press the Test Button

Testing Your Project

Before you try out your project you must make sure the directory represented by the Test.HTML Path option is writable by the user on the http server that runs the cgi. Many servers have the CGIs run as user nobody. In order for the user nobody to write to a file the file must be writable by every user on the system. To insure that the Test.HTML Path is writable, you'll need to use the UNIX command chmod 777 on the directory pointed to by the Test.HTML Path option.

For example: if the value of the Test.HTML Path option is /usr/users/jdoe/public_html, a user would enter the command "chmod 777 /usr/users/jdoe/public_html" at the UNIX prompt:

If you do not want to allow everyone to write to the directory to which your Test.HTML Path points, you need to create a file in that directory and give every user write access to it.

For example:

touch /usr/users/jdoe/public_html/gbook.txt
chmod 777 /usr/users/jdoe/public_html/gbook.txt
If you want more information about security concerns you should read the section in the Reference Manual on Security.

If you did not make any mistakes in the above steps your HTML browser will come up with the HTML Startup Document for the project, which is index.html. You will now add names to the Guest Book to test the project.

Step 12. Click on the Sign Guest Book anchor
Enter your first name, and last name, in the two text fields, then press the Add Name Button.
Your your first and last name should appear in the Guest Book list. If your name does not appear in the file, make sure that you correctly entered the chmod command described above.
Press Sign Guest Book button to add another name to the list.
Continue adding names, verifying that your CGI is working correctly.

Adding an Executable Data Object to your project

This section of the tutorial can be done in any development environment. Depending on how your HTTP server is setup--you may experience problems when testing the project.

Note: This part of the tutorial assumes the following:
Now we are going to create an Executable Data Object using the Object Editor. An Executable Data Object is an executable program that can be accessed by the machine that the http server runs on or the machine the Sapphire/Gateway runs on. The executable object can be a binary executable, or an interpreted script (like C shell or Perl). We our going to create an Executable Data Object that executes the UNIX command man.

Step 13. From the Project Window, select Tools from the pulldown menu, then select Object Editor (Tools>Object Editor), or use the Object Editor Icon.
From the File pulldown menu, select New (File>New)
At Object Type select EXEC
As your selection type: man
Press OK.
Type man into Executable Name text field, this tells the CGI what command to execute and process.
Step 14. Now that we have named the object we need to specify how to send command line arguments to the object. You must follow this format when specifying arguments for EXEC Data Objects
	#name, type[, remove_previous]#
Where

name
The name of the argument. This will appear in the Object Bind Editor.
type
This can be WRAP or NO_WRAP. WRAP means to wrap the argument value with quotes and NO_WRAP means to not wrap the value with quotes.
remove_previous
This is an optional parameter. A value of True means to remove the prefix of this argument if the value returned for the argument is NULL or empty. False means do not remove.
We want to send one command line argument to man. That argument is going to be named title and we do not want to wrap quotes around the argument. By specifying not to wrap quotes around the shell will interpret the argument before executing the command. This allows you to use wild cards for filenames and other shell expansions. Specifying NO_WRAP also causes some security concerns as you will see later.

Type #title,no_wrap# into the Command-Line text field.

Step 15. Now that the input to the object has been defined we need to specify how the output of the object will look. When man is executed at the command line it returns one big string. It is not formatted into multiple rows and columns. We need to tell Sapphire/Web about this, so that it does not try to parse the output.
The following steps specify that the column is delimited by the End Of File character ^D (on most machines). We specify ^D because we know this character cannot be in the middle of the output of the man page. Then we need to say that one Result Column will be returned. We are going to name our Result Column output.

Step 16. Make sure the delimited toggle button is pressed in.
From the Column Delim: use the down arrow, select ^D
In Name Text type: output
Press the Add >> button.
Your Object Editor should look like Figure 5-3
From the Project Window select File->Save; then select File->Close.

Figure 5-3

The next binding will demonstrate the ManPage Anchor in the index.html document. When this Anchor is pressed the CGI will play the manform.html template. There is no dynamic data on this page so we will use a NULL data object.
Step 17. From the Project Window open Object Bind Editor to create a New Activator.
From the Document list select index.html
In the Anchor list select HREF=ManPage.
Press OK
From the Object Type Combo Box select NULL
Press OK
At the Results<=>Template, select manform.html
Press OK.
The next binding will demonstrate the Submit button in the manform.html document. When this Submit button gets pressed we want to take the string entered by the user then pass it in as the Title Argument to the man Executable Data Object. The results of the man will be placed into the manres.html template.

Step 18. Select the Object Bind Editor (New Activator) icon on the project window.
From the Document list select manform.html
From the Forms list select ACTION=FormAction
Press OK.
From the Object Type combo box, select EXEC
From the Executable Objects list, select man
Press OK.
Bind the Title Form Element to the Title Argument.
From the Results<=>Template use the down arrow, select manres.html
Bind the Results Site to the Output Result.
Press OK
Save and Test the project.

Testing Your Project

After the above steps have been completed, the HTML Browser will come up with the HTML Startup Document for the project, which is index.html. In the next step you will type a Unix command into an HTML Form, showing the man page for that command, in your HTML Browser.

Step 19. Press the Man Page Anchor. If you get an error URL not found, your Browser most likely has an older version of index.html in its cache. To correct the problem:
Press the Back Button to go back to index.html and then
Press the Reload Button on the Browser to get the latest copy of the file.
Enter ls (or any other UNIX command you want to see a man page for) and press the Submit Button.
Notice the output of the man command now shows up in your browser.
Use your Browser to go back to the man page form.
At Text Field type: ls; cat /etc/passwd
Press the Submit Button.
Depending on the security of your server you have just displayed the contents of your password file at the end of this HTML document. Scroll down to the bottom of the page in your Browser to see it.This is a security hole that can pop-up in any CGI program, if you are not careful. The cat command could have been any Unix command, that could harm your system.

Cleaning up Command Line Arguments

To prevent CGIs that use Executables as Data Objects being a security risk you should not allow user input to go directly to a CGI. The function SaSafeExecArg fixes this problem.

Step 20. From the Project Window in the Activators list, select manform.html<FORM>FormAction activator
Select Edit use the pulldown select Selected Activators,
From the Project Window select Bind
Notice the value of the text field for the title argument is: SaGetInputValue("title")
Change the value of the Title Argument by clicking in the far left corner of the Text Field, then type: SaSafeExecArg(
Click on the right-most part of the text field and type: ")"
The value in the text field should now be:
SaSafeExecArg(SaGetInputValue("title"))
Note: You may have to make the Object Bind Editor Window wider to see all of the text entered into the text field.
Press OK
Save and Test the project.
Step 21. Wait for your HTML Browser to show the HTML Startup Document index.html.
Press the Man Page Anchor.
Type this into the text field: ls; cat /etc/passwd
Press the Submit Button.
Look at the bottom of the next page that comes into your Browser. You will see that it does not contain the contents of your password file.
Note: Another way to fix the problem with the shell executing the cat command would be to change the definition of the man Executable Data Object. You could have made the Command-Line: parameter look like this:
#title,wrap#
This would have made the CGI put single quotes around the title argument so the semi-colon would not be interpreted by the shell as another command.


[Prev] [Top] [Contents] (2 out of 2)