CommonGround Softworks Inc. - Getting Started 
t-}i͛2=i	i:02"A}jTEԣf!LjX:4f~CWcPPHLyeo6ѠGbOQslZ^2 TQm\?H$IT
-*Y^Q.Xlu[QedTYo[lN.%AFAF rثfu_C(	
DK[?슏aX>y@
'}G/Zs document introduces the process of setting up Osmosis with a web server, client browser and the Osmosis Collection. Configurations are based upon Quid Pro Quo 2.0 and Microsoft Explorer 4.0.

		
Setting up the HTML

		
Client browsers use a structured text based language, HTML (Hypertext Markup Language) to format and display a 'web page'. It is beyond the scope of this document to explore HTML, but suffice to say the output from Helix must in the form of HTML, so the client will be able to properly display the data. If you are unfamiliar with HTML, there are many books, classes and workshops to help you get started. HTML is not very complex nor is it a 'programming' language. Here's a simple example:

		
<HTML> Tells the browser what follows is HTML

		<HEAD> Tells the browser what follows is part of the document header

		<TITLE> Tells the browser what follows is the document title

		My First HTML

		</TITLE> Tells the browser the document tile is finished

		</HEAD> Tells the browser the document header is finished

		<BODY> Tells the browser the document body is about to begin

		Here is my data Where you put the Helix HTML formatted information

		</BODY> Tells the browser the document body is finished

		</HTML> Tells the browser the HTML is finished

		
There are an unlimited number of format options and variations for you to choose from, including lists, tables, layers, dynamic HTML, style sheets, etM.Mc Y"퐍|d$'Y*d(GYSr|es[re0Yc&s|f4Ykfs
#dYss|gt-}i͛2=i	i:02"A}jTEԣf!LjX:4f~CWcPPHLyeo6ѠGbOQslZ^2 TQm\?H$IT
-*Y^Q.Xlu[QedTYo[lN.%AFAF rثfu_C(	
DK[?슏aX>y@
'}G/Znload the graphic, but merely tells the client where to go an get it.

		
Setting up the Web Server

		
The web server is a critical link between the client browser and Osmosis. Clients communicate directly with the web server. When a client submits a request (clicks the submit button), the web server is requested to launch Osmosis and pass data. Osmosis, in turn, tells the web server to wait for a reply - and when received, send the reply back to the client. All of this communication happens behind the scenes, assuming some configuration has been done beforehand.

		
Here's what's involved:

		
A HTML is accessed by the client. The HTML is located on the web server and is accessed by the client typing in the address of the web server, on his/her browser, followed by the file's location. For example 10.1.1.6/myfirstdocument.html.

		
Within this file, there are specific statements passed to the web server when the form is submitted. These statements tell the web server what to M.Mc Y"퐍|d$'Y*d(GYSr|es[re0Yc&s|f4Ykfs
#dYss|gt-}i͛2=i	i:02"A}jTEԣf!LjX:4f~CWcPPHLyeo6ѠGbOQslZ^2 TQm\?H$IT
-*Y^Q.Xlu[QedTYo[lN.%AFAF rثfu_C(	
DK[?슏aX>y@
'}G/Zb servers, by default, assume all files are text unless instructed otherwise. You will note the file, "Osmosis.acgi" has a suffix, "acgi". Web servers identify a file's suffix to know how to treat the file. Most web servers have a, "Action" set up dialog. You must insure the suffix, "acgi" is treated as an application. Once this is done, the web server will successfully launch Osmosis and await a reply.

		
Setting Up Osmosis

		
When a client asks the web server to launch Osmosis, a script is identified. This is a file created by the designer that instructs Osmosis as to where Helix is located (Target Step), what entry relation/view to use for data storage (Entry Step) and what output relation/view to use to retrieve data (Output Step) amongst other actions.

		
Although the client initiates the storage of data through an entry, Osmosis controls data output. Helix cannot initiate an AppleEvent, therefore it must be 'asked' (polled) for data. OsmosM.Mc Y"퐍|d$'Y*d(GYSr|es[re0Yc&s|f4Ykfs
#dYss|gt-}i͛2=i	i:02"A}jTEԣf!LjX:4f~CWcPPHLyeo6ѠGbOQslZ^2 TQm\?H$IT
-*Y^Q.Xlu[QedTYo[lN.%AFAF rثfu_C(	
DK[?슏aX>y@
'}G/Zas four collections, one to handle internet access, one to process requests, one for reporting and one for archiving. The user has two web servers, one for internet and one for intranet access. A copy of Osmosis is running on each web server. An internet client enters/retrieves data from the internet collection. Osmosis is scripted so that each entry into the internet collection is transferred to the process collection, then after processing by a Helix client, is transferred back to the internet collection for inquiry by the internet client. Simultaneously, the intranet web server, via a HTML, is running Osmosis in a loop. Processed data is transferred from the processing collection to the reports and archive collections. This looping process is active all day.

		
Reports can be run without interfering with data entry, processing or archiving; Archiving can accomplished automatically, without dumping/loading; and collection structures are specialized and minimized.

		
Getting Started

		
Using Osmosis.acgi, Osmosis Collection (provided) and Quid Pro Quo (a Macintosh web server, provided), we will go through, step by step, the procedures necessary to successfully set-up a Helix - internet link.

		
We will assume you have a PPP (point to point protocol) connection (modem) connection to the internet. You will be running your web server, Osmosis and Helix all on a single machine. Lastly, you are using Mac OS 7.6 or higher.

		
Let's begin...

		
Configuring your Macintosh

		
Your Macintosh must be set up to connect with your internet provider via PPP. To do this, open the control panel, "TCP/IP". The following screen will appear:

		

			


			

			

		

		
This screen has been set-up to connect to an internet provider once the modem connection has been successfully negotiated. Your 'Name server addr' may be different from the ones shown above. Consult your ISP (Internet Service Provider) for more information. The IP Address will be assigned by your ISP when you connect.

		
If you are not using the internet, namely you just want to set up an intranet, your TCP/IP control panel screen may look something like this:

		

		
Note the IP Address is a unique number for the machines just within your intranet. If you are using ethernet, the 'Connect via' pop-up will indicate ethernet, otherwise AppleTalk (MacIP) will be used for localtalk.

		
If you are using PPP, open your connection to your ISP.

		

			


			

			

		

		
Configuring your web server

		
Once a connection is established, double click on the Quid Pro Quo application icon.

		

		
The server activity log screen will open. If this is the first time QPQ is opened, it will likely need to be configured to recognize your ISP connection. Under the Control Menu, select, "Server Settings".

		

		

		

			


			

			

		

		
The address is derived from the ISP. If no address appears, click the pop-up arrow and select the address shown. This is the IP address your ISP is assigning to your machine. Quit and restart QPQ.

		
Note, if you are not using PPP, then the address should be same as entered in the TCP/IP control panel.

		
When you restart QPQ, the server activity log should look similar to this:

		

			


			

		

		


		Under the Control menu, select, "Server Settings"; then click the 'suffix mappings' icon on the left portion of the screen. The following screen will open.

		

			


			

			

		

		
If the suffix, ".acgi" does not appear, you must add it manually. It should appear entered exactly as shown above.

		
Osmosis and it's associated script files must be placed into the cgi-bin folder. This is a special folder where QPQ expects to find cgi's.

		

			


			

		

		


		Our access to Helix is via a HTML that resides on the web server (inside the root folder). The root folder is that folder containing the QPQ application. The two 'access' forms, "AccessSheet.shtml" and "AccessList.shtml" need to be placed in the root folder as shown below:

		

			


			

			

		

		
You will note the suffix for our two access HTML's is, ".shtml". This is a special type of HTML that tells the web server to use server side includes (SSI). In short, this means that web server data is passed down to the client whenever a specific form is accessed. Here's what we want to do:

		
When the client accesses either of our two forms, we want the web server to ask for a user name and password. These are web server variables, not those associated with Helix. We then want the web server user name to be passed to Helix and stored in a field. In order to do this, we first have to create a realm. Simply, a realm is a folder, within the web server's root folder. When a file, stored within that folder, is accessed, the web server responds with an authentication dialog - user name and password. The user name and password are then stored as web server variables. If the appropriate command is used in the .shtml, the variables are sent to the client. In this way, the user name and/or password can be stored in Helix.

		

			


			

			

		

		
The folder, "AccessSheets" is created and the two access forms are placed inside of it.

		

			


			

			

		

		
To create a web server realm, select, "Server Settings" under the Control menu. Click on the Realms icon in the list. Enter, "AccessSheets" for the realm name (folder name) and "Access" for the match name. You will note that both our forms start with, "Access". This is a method the web server uses to identify which forms will invoke the authentication dialog.

		

			


			

			

		

		
Now we must identify who can access our realm. Select, "Server Settings" under the Control menu. Click on the Security icon in the list. Enter a user name and a (optionally) as password. Associate the user name with our realm, "AccessSheets" and save your settings.

		
If you open the form, "AccessList.shtml", you will notice the following command line:

		
<INPUT TYPE="hidden" NAME="UserEntry2" VALUE="<!--#echo var="REMOTE_USER"-->">

		
The VALUE portion of this line, when an authenticated user accesses the form, is replaced with, "Stephen" - the user who accessed the form inside the realm.

		
Your web server is now configured. If you wish, you may quit the server and disconnect from your ISP. We will reconnect later.

		
Configuring Helix

		
Double click on the Osmosis collection to open it. You may use the server or single user version. Refer to the document, "Helix Set-Up" for more details concerning user limits.

		
The collection has been designed with Helix version 4.5.1. You will need either version 4.5 or 4.5.1 to open it.

		
We will explore the Helix construction in more detail later, but for now, just open the collection.

		
Configuring Osmosis

		
The actions to carried out by Osmosis are stored in it's scripts. For example, open "1" by double clicking on it's icon:

		

		

		

			


			

			

		

		
The script window is divided into three sections: available steps, step actions and step set-ups. The available actions are Output, Target, Transfer From and Transfer To. Script, "1" has been configured to enter data, then poll Helix for three outputs.

		

			


			

			

		

		
By clicking on the Target Step in the center column, the set-up will appear to the right. You will note that the machine, collection, user and (optionally) password must be identified. This information is used by Osmosis to access the Helix relation and view in all subsequent steps (or until a new target step is encountered). UserCycle is a very specialized option. Refer to the document, "Scripts and Parameters" for more information.

		

			


			

			

		

		
By clicking on the Entry Step in the center column, the set-up will appear to the right. Here we identify the relation and view to be used for data entry. There are several options that can be used when the data entry occurs, such as 'debug'. For now, just leave these empty.

		

			


			

			

		

		
By clicking on the Output Step in the center column, the set-up will appear to the right. Osmosis will poll Helix for each output, in step order. In the script, "1", we are asking for three outputs. Osmosis gathers data from three different views, assembles the data, then passes the output to the client.

		
Why not just use one output? This is perfectly acceptable so long as the HTML formatting can be done within a single output step. Sometimes this cannot be done when specific tags must be used outside of a list or the designer is attempting to do some unique formatting, such as dynamic HTML.

		
Calling the script

		
By now, you might be wondering how Osmosis knows which script to use. The HTML form, whether accessed by directly by the client from the web server or as part of a Helix response, must contain the necessary information to both launch Osmosis and use a specific script. Here's how it's done:

		
<FORM METHOD="POST" ACTION="../cgi-bin/osmosis.acgi">

		

		<INPUT TYPE="hidden" NAME="SCRIPT" VALUE="1">

		

		
These two HTML statements tell the web server to locate and launch Osmosis, then run the script identified in the second statement.

		
The first statement is an opening FORM tag. It tells the web server that data is about to be submitted. When that data is encountered, POST or send the data to ../cgi bin/osmosis.acgi. The full path must be used to specify the location.

		
The second statement is actually the first part of the data submission. By using the NAME="SCRIPT", Osmosis interprets the VALUE as the name of the script to be run.

		
Additional statements will pass data, using the convention, "UserEntryxx". For example:

		
<INPUT TYPE="hidden" NAME="UserEntry0" VALUE="200">

		

		<INPUT TYPE="hidden" NAME="UserEntry1" VALUE="200">

		
These two statements are each sending the value, "200" to Helix. The NAME="UserEntry", followed by a number 0-127, is interpreted by Osmosis as data to be entered into a view. The UserEntry numerical order will be consistent with the Helix tabbing order.

		
Check out the two HTML forms, "AccessList.shtml" and "AccessSheet.shtml" by opening them with a text editor such as Teach Text or BBEdit.

		
Using a client browser to access Helix

		
At this point, you should have the Helix collection, Osmosis Collection open. Re connect to your ISP and launch QPQ. Note the IP address in QPQ's activity log.

		
Now open your client browser, Netscape or Explorer. Type the IP address, from QPQ's activity log, in the location entry (URL), then type the following:

		
/accesssheets/accesssheet.shtml

		

		then press the return key.

		
This will tell the web server you want to access one of the HTML's. Because it is in the realm, "AccessSheets", a user authentication dialog will open. Type in your user name, "Stephen" and password (if any), then press the return key.

		
The HTML, "AccessSheets.shtml" will be fetched from the web server and displayed in the browser window as shown below:

		

			


			

			

		

		
Notice the user name at the top of the form. This is the user name used to access the realm and downloaded from the server using the server side include command. As an aside, SSI's are very useful and powerful. There are several commands and many types. Consult your web server manual for details.

		
Now let's go ahead and enter some data. Remember, each text box or pop-up will be passed to Helix as field data. How do we know what will go where? Each text box and pop-up is assigned a 'UserEntry' value. A portion of the HTML for AccessSheet.shtml looks something like this:

		
<TD HEIGHT="28"><P ALIGN=RIGHT>Publication</TD>

		

		<TD></TD>

		

		<TD><INPUT NAME="UserEntry8" TYPE="text" SIZE="60">

		

		</TD></TR>

		

		<TR>

		

		<TD HEIGHT="31"><P ALIGN=RIGHT>Ad Size</TD>

		

		<TD></TD>

		

		<TD>

		

		<SELECT NAME="UserEntry9">

		

		<OPTION VALUE="">

		<OPTION VALUE="Full">Full

		<OPTION VALUE="Half">Half

		<OPTION VALUE="Quarter">Quarter

		<OPTION VALUE="Other">Other...

		

		</SELECT>

		
The entry for Publication is UserEntry8 and Ad Size UserEntry9. This means the 9th field (based on the tabbing order for the entry template in Helix) will be used to store Publication and the 10th field for Ad Size. Note that we always start with UserEntry0. The Helix template used for the view NetUserRequestNew entry is shown below:

		

			


			

			

		

		
Helix set-ups are more fully discussed in the document, "Helix Set-Ups", but for now, let's complete our data entry. For Issue Date, enter 1/10/98, then click the Submit button.

		

			


			

			

		

		
The HTML has extensive validation using JavaScript. JavaScript is but one language you can employ to test data entries. In this situation, the issue date is being tested to insure it is a Friday. Refer to the HTML for the complete JavaScript function. Most validation is done at the client, without any interaction with Helix.

		

		

			


			

			

			

		

		
Dismiss the JavaScript Alert and correct the Issue Date. Click the Submit button again. If the data passes the validation, Osmosis will then check the script for errors. Each step is checked. Osmosis checks each script step each time the script is called.

		
If an error occurs, a screen similar to the one shown below will be displayed. Osmosis will tell you what and when the error occurred. You must correct the error before you can continue. The most common error is, "Destination Port does not exist". This just means that the target machine could not be found or is incorrect.

		
The error shown means the target collection name was wrong or misspelled.

		

		

			


			

			

		

		
If the submit is successful, Helix will return the following HTML to the client's browser window:

		

			


			

			

		

		
You will note the information entered is returned for review and confirmation. This is a design preference. In Helix, this entire HTML is one record. The abacus that comprises the display gets data from several relations and is, in itself, composed of many tiles to properly format the HTML.

		
The template for NetValidForm (the second output step in the script, "1") is shown below:

		

			


			

			

		

		
The view has been defined as a list without a query. Therefore all records will be retrieved. In Helix, the relation is a Global with only one record. The list definition is a matter of designer choice, not a specific requirement.

		

			


			

			

		

		
The output abacus is a series of followed by tiles that sends a HTML formatted 'text stream' back to the browser. Imbedded in this text stream is field/abacus data.

		
Where to go from here...

		
Take some time and read through the document, "Helix Set-Up". This document discusses the interrelationship between the net and Helix and the design consideration you need to know before building an internet site with Helix.