Chapter 17 : Internet Publishing

Transcription

1 Chapter 17: Internet Publishing 621 Chapter 17 : Internet Publishing With the advent of the explosion of the World Wide Web (WWW), the requirements of a development environment have evolved so as to demand capabilities that enable migrating and deploying applications to the Internet. OpenInsight for Workgroup s versatile development environment is prepared to handle today's requirements. OpenInsight is built upon a foundation that permits these new requirements to be easily implemented by integrating new repository-based features and tools. You can migrate existing and develop new applications that provide static and dynamic publishing of OpenInsight forms and data to the WWW in HTML format. OpenInsight's HTML Publisher can create HTML pages from OpenInsight forms, thus performing as an HTML composer. More significantly, OpenInsight for Workgroups provides web server extensions in the form of CGI (Common Gateway Interface) services which let you request information from an executing OpenInsight application and deliver that information to a web browser. This chapter explains what the OpenInsight tools and processes are and introduces the technologies involved in bringing your data and applications to the Internet. Terms and Definitions The following is a list of terms and definitions used in this chapter. You are encouraged to enhance your understanding of these terms by searching out additional information on the WWW or from other sources. HTML - stands for Hypertext Markup Language, a language that uses tags to indicate changes within a document, changes in format style, or changes in content. static publishing - the process of locating and presenting in a web browser, information that already exists; this information is located somewhere on a storage device and has an address (URL) that can be found by the web server.

2 622 Section 6: Deployment dynamic publishing - the process of creating information when it is requested, in real-time, and subsequently presenting the information to the web browser. The request for this information is processed via a Common Gateway Interface (CGI) program. Common Gateway Interface (CGI) - an interface for running external programs or gateways under an information server, based on information received from a web browser anywhere on the Internet. Currently, the only supported information servers are HTTP servers. Using a CGI program let s you access information that exists in a form not readable by your browser. For example, you cannot automatically display linear hash data in a browser because it does not exist in an HTML document. HTTP protocol/server - stands for HyperText Transport Protocol, one of many protocols used to access information over the Internet, in particular, the WWW. HTTP servers utilize this protocol for communications between the browser and the web server software. HTTP is an extremely low-overhead protocol that capitalizes on the fact that navigation information can be embedded in hypertext documents directly and thus the protocol doesn t have to support full navigation features like other Internet protocols such as FTP and Gopher. Universal Resource Locator (URL) - a pointer to information located somewhere on a network which can be returned using any of several different methods. Sometimes the URL points to a file which may be on a web server or on any machine that s part of the Intra/Internet. URLs can also point to queries, documents within databases, or whatever. web server software - software specifically designed to respond to requests for information from clients (web browsers) by locating the requested resource and delivering the information back to the browser that requested it. OpenInsight as an HTML Generator OpenInsight provides the HTML Publisher, a tool that lets you create HTML pages based on OpenInsight forms. Without having to learn HTML, you create a form in OpenInsight then convert it to an HTML document using the HTML Publisher. The HTML document is added to the repository as an entity type Document, class HTML (General - Documents - Documents - HTML Files). The HTML Publisher tool can be used as a quick method of creating any HTML document - the document doesn t necessarily have to be used by an OpenInsight application. Because of the nature of HTML and the web environment, there are a few things to bear in mind when creating your web page with the OpenInsight Form Designer.

3 Chapter 17: Internet Publishing 623 The first is that the Form Designer does not offer a true WYSIWYG HTML design interface. In fact, this is true of virtually all web page creation tools. For example, when you place a control in the center of an OpenInsight form, that control will be centered when you run the form. However, when you convert the OpenInsight form to an HTML document, the control is aligned flush left when viewed through a browser. HTML uses tables to format information on a page rather than x,y coordinate positioning. During the conversion process, the HTML Publisher also uses a table paradigm to position OpenInsight controls on an HTML page. You can use other tools to edit the HTML document and provide additional formatting. The second thing to keep in mind is that not all of a control s functionality is available via the web. Following is a starter list of the controls that can be used on a web page, and some of their limitations. Static Text - HTML ignores any size, font, and color formatting applied to the text and uses the browser s default. Button - HTML ignores the size of the button. Bitmap - the file must be in.gif or.jpg format. Checkbox - all checkboxes are 2-state, even if 3-state is selected. Edit Line - HTML ignores the size of the edit line. List Box - hierarchical list boxes do not work; if this option is selected, the OpenInsight code in the text portion of your list box (indicating bitmaps and levels) will be printed as text. Edit Box - the size of the edit box is ignored. Combo Box - HTML ignores the size of the combo box. Radio Button - appears the same. Other functionality you might want to include on your HTML document is a hyperlink to another web page. In order to create a hyperlink on the OpenInsight form, use a static text control, and in the TEXT property of the control, append a pipe symbol ( ) followed by the URL of the desired link. For example, if you wanted to create a link to Revelation s web site, you would place the following into the TEXT property of the control: Go to our web site

4 624 Section 6: Deployment When the OpenInsight form is converted to HTML, the Go to our web site is underlined and appears as a hypertext link. Alternatively, you could create a link that enables a user to Revelation s general information mailbox. In that case, you would assign the following to the static text control s TEXT property: Click here to mailto:info@revelation.com When converted, the Click here to is underlined an appears as a hypertext link. The following procedure lists the steps for creating an HTML document. Procedure: To Create an HTML Document 1. Start OpenInsight s Form Designer. 2. Create a form using any of the following subset of standard controls: Text, Push Button, Bitmap, Check Box, Edit line, Edit box, Combo box, List box, Radio button group. Other OpenInsight controls do not have equivalents in the context of an HTML document and therefore are cannot be converted. 3. HTML pages may have static link (reference) elements on them. To create a static link element, place a static text control on the form and change its TEXT property by appending a pipe symbol ( ) followed by a reference URL (i.e. or the literal mailto: that is in turn followed by an address (i.e. mailto:shelly@revelation.com). 4. Save the form. The following figure shows an example form.

5 Chapter 17: Internet Publishing Start the HTML Publisher, shown below, by choosing HTML Publishing from the Form Designer File menu or by executing the OpenInsight window executable WEB_PUB from the repository outline. (Select the entity then SHIFT+double-click to execute it.) 6. Select an application and the form you want to translate into HTML, to preview the form.

6 626 Section 6: Deployment Tip: The HTML Publisher tool provides a fast way of previewing all of your OpenInsight forms, regardless or whether you plan to convert them to HTML documents or not 7. With the appropriate form displayed, click the Compile HTML Page hot spot. The progress of the conversion is indicated in the status line. 8. You are prompted to specify a path to save the HTML document file. OpenInsight provides an HTML subdirectory which can be used. When you save the file, the HTML Publisher automatically registers the HTML file in the repository as an entity of type Document, class HTML, and name equal to the form name. 9. Click the hot spot View HTML Page to display the document in your browser as shown in the figure below.

7 Chapter 17: Internet Publishing 627 The source code for this HTML document follows. (Minor modifications have been made to this code using Notepad.) <!-- Generated by the Revelation HTML Publisher > <HTML> <HEAD> <TITLE> WEB TEST FORM </TITLE> </HEAD> <BODY BGCOLOR="#ffffff" > <FORM METHOD="post" ACTION="./"> <TABLE> <TR VALIGN="top"><TD ALIGN="left" WIDTH="306">This is a demonstration page used to illustrate the functionality of the OpenInsight HTML Publisher.</TD> </TR> <TR><TD ALIGN="left"><A HREF=" text here is a link to the Revelation web site! </TD> </TR></table> <TR><TABLE> <TR VALIGN="top"><TD><TABLE> <TR VALIGN="top"><TD ALIGN="left">Select a Report</TD> </TR> <TR><TD ALIGN="left"><SELECT NAME="LIST_1" SIZE="2"><OPTION>Orders Processed<OPTION>Invoices Billed<OPTION>Inventory Status</SELECT></TD> </TR></TABLE> </TD> <TD><TABLE> <TR VALIGN="top"> <TD ALIGN="left"><A HREF="mailto:shelly@revelation.com">Click here to send us an ! </TD> </TR> <TR><TD ALIGN="left"><INPUT TYPE="submit" NAME="BUTTON_1" VALUE="Process a Report" SIZE="19"></TD> </TR></TABLE> </TD></TR></TABLE> </TR></TABLE> </FORM> </BODY> </HTML> Note: The above HTML document uses the <FORM> tag and several form related tags such as <SELECT>, <OPTIONS>, AND <INPUT>. Creating an HTML document that uses form features provides additional functionality when using CGI programs. More information about the use of forms with OICGI can be found later in this chapter.

8 628 Section 6: Deployment Any registered HTML page is also accessible from the repository outline. When you SHIFT+double-click on an HTML document entity, it is launched in your web browser; double-clicking the HTML document entity displays it in Notead where the document can be modified. Any HTML document that has been registered as an entity in the repository can be accessed in a web browser via OpenInsight CGI services. To registered an HTML document not created with the OpenInsight HTML Publisher, create the entity in the Application Manager using the following procedure. (Documents created with the HTML Publisher are registered in the repository as mentioned above. Procedure: To Register an HTML Document in the Repository This procedure assumes that the HTML document was created outside of the OpenInsight development environment. 1. Choose New from the Application Manager s Entity menu. This displays the Create New Entity dialog box shown below.

9 Chapter 17: Internet Publishing Select Document Entity then click the OK button to display the New Document Entity dialog box. 3. Select HTML from the Document Type combo box then enter the full path (or Browse to find the full path) in the Document Name edit line. 4. Click the ACCEPT button to register then entity, then click the CLOSE button to end the dialog. The entity is registered as having the type Document and class HTML.

10 630 Section 6: Deployment OpenInsight as a Web Server Extension As mentioned in the Terms and Definitions topic, a web server can deliver information to a browser when that information already exists. Make a request using the appropriate URL, and if the information is out there, the web server locates it and returns it to the browser. But what if the information that is requested doesn t exist or needs to be produced, or cannot be directly located. For example, what if you want to access information that needs to be produced by a program, such as a report? This is called dynamic publishing to the web. Or what if you want to access information that exists in the context of an executing program, such as an entity in a repository. This is a case of static publishing to the web when the entity points to a.htm file. The web server needs a gateway to process the browser s request for this type of information and communicate with the executing program to obtain the information. A Common Gateway Interface (CGI) program provides this functionality. The CGI program provided with OpenInsight for Workgroups is OICGI. (It has no file extension.) This 32-bit program is executed to process a request from the web server. It then forwards the request to OpenInsight for processing and returns the dynamic output information, an HTML document/script back to the browser. This process is illustrated in the following figure and elaborated upon in the topics that follow. Client Browser 1. Request from bowser to HTTP web server 2. Web server to OICGI/Inet_Gateway 3. OICGI/Inet_Gateway OpenInsight 4. OpenInsight creates HTML <HTML> <HEAD> <TITLE> OI Web Form </TITLE> </HEAD> <BODY OpenInsight/HTML to Inet_Gateway/OICGI 2. OICGI/HTTP services to browser Client Browser These components must be stored on the server. Windows NT Server HTTPcompliant web server software OpenInsight OICGI Inet_Gateway window OpenInsight File Server These components must be executing on the web server. OpenInsight Development

11 Chapter 17: Internet Publishing 631 Setting Up the Resources Let s begin with a look at the resources required as shown in the above figure. You need an HTTP web server machine. This is a high-end computer with an Intel processor running either Windows 95 or Windows NT. This computer needs to be capable of providing HTTP services using any web server software that is CGI 1.1 compliant. This machine is referred to as the web server. OpenInsight s CGI program, OICGI, provides the gateway services and must be stored on the web server. Your web server software dictates where this file must be stored so that it can be recognized and executed as a CGI module. Refer to your web server documentation for specifics. Typically, this is the subdirectory \CGI-BIN. Note: Some web servers require that the OICGI file be renamed OICGI.EXE. The web server may have a copy of OpenInsight installed on a local hard drive, although that is not a requirement. OpenInsight may be installed on another file server machine on the network. What is required however is that the web server must run OpenInsight either by accessing it locally or remotely from a mapped drive. The fact that OpenInsight may be located on another computer in the network can benefit performance and accessibility. Team development may continue on this copy of OpenInsight as long as the appropriate number of collaborative development disks have been installed. The copy of OpenInsight running on the web server is considered one user. A special benefit of this situation is that any developer with proper access rights can update the Internet application and the client browsers see the update immediately. The OpenInsight Internet Gateway Services must be running on the web server. The Internet Gateway Services are provided by the window executable form INET_GATEWAY which can be loaded from the repository outline or as the Entry Point window for the OpenInsight Internet application. The final requirement for the setup is that the client browser requesting information must support HTML 3.0. (Netscape 2.0+ and Microsoft Internet Explorer 3.0+ meet this requirement.)

12 632 Section 6: Deployment Laying the Foundation If you created the HTML page using the HTML Publisher described earlier in this chapter, and accessed that page in a browser, you probably found its functionality limited to sending or viewing another HTML page. This functionality is provided by clicking on the hypertext link elements. If you made a selection from the list box and clicked the button on the page, you discovered that nothing happens. If the original OpenInsight form executed in an OpenInsight application, you would expect to see a report displayed or some other response to your actions. This would be a typical behavior in the event-driven paradigm that OpenInsight applications run in. However, browsers, HTTP, and web server software do not use the same paradigm, although it can be simulated. To do this you ll integrate OpenInsight capabilities, HTML and CGI features. In OpenInsight you ll design forms with selected controls, use certain naming conventions and incorporate additional features in TEXT properties. In addition, you ll specify QuickEvents for the Internet-related SUBMIT event and execute OpenInsight supplied Internet procedures or your own. With regard to HTML, you ll need to know about how forms are specified, and how form information gets communicated to the CGI program (OICGI). Some of the form-related tags are coordinated with OpenInsight control names and their TEXT properties and with QuickEvent parameters. You ll need to understand how the browser packages the HTML form input for delivery to the web server and puts it in a special format called URL-encoding. You ll also need to understand how this URL-encoded input may need to be parsed using the OpenInsight Internet procedure Inet_QueryParam(). Concepts and Conventions Before proceeding, additional concepts and conventions need to be discussed. Be warned that the following information assumes you are familiar with the HTML element FORM and the Common Gateway Interface. If you are not familiar with these terms, it is strongly recommended that you use one of the many search engines on the WWW or other sources to obtain more information on these topics before proceeding. An HTML page created using OpenInsight Form Designer and the HTML Publisher is referred to as an OI Page.

13 Chapter 17: Internet Publishing 633 The expression <Server URL> is the notation used for your web server URL (i.e. A BASIC+ variable stores an HTTP-Request (you can say the variable is an HTTP- Request) if this variable is a delimited array of fields as outlined in INET_EQUATES insert record listed below. * CGI environmental variables equ QUERY_STRING$ to 1 equ PATH_INFO$ to 2 equ CONTENT_TYPE$ to 3 equ CONTENT_LENGTH$ to 4 equ GATEWAY_INTERFACE$ to 5 equ HTTPS$ to 6 equ HTTP_ACCEPT$ to 7 equ HTTP_COOKIE$ to 8 equ HTTP_FROM$ to 9 equ HTTP_REFERER$ to 10 equ HTTP_USER_AGENT$ to 11 equ PATH_TRANSLATED$ to 12 equ REMOTE_ADDR$ to 13 equ REMOTE_HOST$ to 14 equ REMOTE_IDENT$ to 15 equ REMOTE_USER$ to 16 equ REQUEST_METHOD$ to 17 equ SCRIPT_NAME$ to 18 equ SERVER_NAME$ to 19 equ SERVER_PORT$ to 20 equ SERVER_PROTOCOL$ to 21 equ SERVER_SOFTWARE$ to 22 equ SERVER_URL$ to 23 According to HTTP and CGI specifications the QUERY_STRING$ field of an HTTP Request is an ampersand ( & ) delimited sequence of Query Items. A sub-string represents a Query Item if it has a format of <Query Item Name>[=<Query Item Value>]. Query Item Name is an alphanumeric literal. Query Item Value is a literal which is in a format permitted inside of a URL. For example, you must use a + instead of space and %2b instead of + inside of a URL. A BASIC+ stored procedure is an OpenInsight Internet Procedure if all of the following is true: 1. The name of the stored procedure starts with INET_. 2. The first parameter of the stored procedure is an HTTP-Request.

14 634 Section 6: Deployment 3. The stored procedure is declared as a function and its return value is an HTML script/document. 4. Actual parameters are passed as the QUERY_STRING$ field of an HTTP-Request and have to be parsed using the Inet_QueryParam function. Refer to the syntax later in this chapter. The HTTP-Request Dispatcher is an OpenInsight supplied BASIC+ procedure called Run_Inet_Request which serves as an entry point for all requests coming to OpenInsight via CGI. (Run_Inet_Request is analogous to the Run_Event procedure that serves as an entry point to all events coming from Presentation Server.) An Internet procedure can programmatically specify a time-out for a CGI request by sending an event to the Internet gateway monitor window. The default timeout is 30 seconds. The syntax used is: $insert Inet_Equates... /* GS_MONITOR$ is the Internet gateway monitor */ Send_Event(GS_MONITOR$,'OMNIEVENT',INPROGRESS$,timeleft) where timeleft is the maximum time in seconds you want to allow this request to work without timing out the CGI request. OpenInsight Form to OI Page Conversion The table in this section shows the mapping between OpenInsight controls and HTML features. The conversion of an OpenInsight form into an HTML document performed by the HTML Publisher uses these mappings. Of course you can modify the resulting HTML document with any other HTML authoring tool. The Comments column in the table provides information that begins to shed light on how the event-driven paradigm can be simulated in the HTML page/web browser environment. Keep in mind that the simulation of this paradigm has some limitations due to the nature of the WWW, HTML, and a number of misfits between a formoriented event-driven application running under Windows and an HTTP/HTMLbased application running in a browser. One is that HTML has equivalent elements with some functionality for only a subset of OpenInsight controls. (However, any invisible control on an OpenInsight form is converted into a HIDDEN HTML element.) Another limitation is that currently, an OpenInsight form is translated into one and only one HTML FORM element.

15 Chapter 17: Internet Publishing 635 The following table lists OpenInsight controls which can be translated into HTML elements. This table assumes you are familiar with FORM-related HTML tags and their functionality. OI Form Control HTML Element Type HTML Element Name HTML Element Value Comments window FORM N/A N/A ACTION element is generated; additional HIDDEN elements could be generated (by invisible OpenInsight controls). static text plain text N/A N/A HREF or MAILTO: elements could be generated. push button SUBMIT $SUBMIT control s text Additional HIDDEN element could be generated. bitmap IMG N/A N/A SRC element contains a relative path to the image file. edit line TEXT control s name control s text edit box TEXTAREA control s name control s text combo box list box SELECT without SIZE SELECT with SIZE control s name N/A OPTON element for each line. control s name N/A OPTION element for each line. check box CHECKBOX control s name 1 radio button group collection of RADIO elements control s name Corresponding radio button value

16 636 Section 6: Deployment Using the SUBMIT Event on Your OpenInsight Form The SUBMIT event can be used when developing Internet applications and has been added to the following controls event sets: window, push button and static text. Currently, only a QuickEvent can be defined for this event. The QuickEvent executes an Internet stored procedure, either a system stored procedure or one you create. The conversion of the SUBMIT event s QuickEvent into an HTML feature is different for each control. When the SUBMIT QuickEvent is defined for a: Window: the SUBMIT event translates into an ACTION element with a CGI request ( ACTION=.//<Internet procedure name> ). You can also specify additional parameters for this QuickEvent as a comma delimited sequence of Query Items. Another way to specify additional parameters is to name your controls using a Query Item definition. Then the incoming HTTP- Request will carry the Query Item with a name equal to a control name <Query Item Name> and a value <Query Item Value> (possibly) set by a user. Push button: Static Text: the SUBMIT event translates into an additional HIDDEN element that allows the HTTP- Request Dispatcher to figure out what button has been pressed. There is no need for QuickEvent parameters in this case. the SUBMIT event translates into HREF element using the QuickEvent parameters: ( HREF=.//<Internet procedure name>? <Quick event parameters> ) Note: The QuickEvent dialog for this control can be accessed from the Form Designer's Properties menu or by CTRL+doubleclicking on the text. When defining the SUBMIT QuickEvents you need to select a QuickEvent Option which describes what it is that you want to occur. Any of the following options can be selected. Execute a stored procedure, in which case you choose a system Internet procedure or one you created. Publish Report creates a dynamic HTML page using a report layout defined with Report Builder. (Report Builder, a wrapper for RLIST, can be run by executing the OpenInsight form executable ORMAIN. More information on this topic can be found later in this chapter.) The parameter REPORT_ID is the name of the report layout created in Report Builder is entered in the window s QuickEvent.

17 Chapter 17: Internet Publishing 637 Read the Document performs a function similar to a hyperlink (displays an HTML page) except that it uses OICGI to access a static web page registered in the repository. The parameter DOC_ID is the name of the HTML document to be accessed and is entered as a parameter in the window s SUBMIT event. If you want to access an HTML document that was not created with OpenInsight, simply register it in the repository. Bootstrapping In order to implement the functionality of the OI Page, the OI Page itself needs to be requested via a CGI call. One way of doing this is by using an HTML page with a hypertext reference to your OI Page via <OICGI>, i.e. <HREF= >. For example, you could hard code a link like the one above on your home page. You can think of this HTML page as the visual entry point to your Internet-based OpenInsight application and the OI Page (WEBFORM.HTM) that the link requests as the functional entry point to your Internet application. The link above locates and runs OICGI which calls the OpenInsight Internet procedure INET_REPOS. This function that accepts the parameter DOC_ID with a value that is an existing HTML document registered in the repository. The syntax for INET_REPOS() is described later in this chapter. Creating the Response This section integrates the foundation material and presents several different examples of how you can use OI Pages to request information from an OpenInsight Internet application. Before continuing, familiarize yourself with the OpenInsight provided Internet procedures found later in this chapter. These examples demonstrate the use of those procedures. Accessing a Document Registered in the Repository This is probably the easiest task to perform. You can request an HTML document that is registered in the repository. This is an example of static publishing. Procedure: To Request a Document Type Entity 1. Create an OpenInsight form with two static text controls: "HR Application" and Click here to see the HR policy.

18 638 Section 6: Deployment 2. Create a QuickEvent for the window s SUBMIT event, selecting the QuickEvent Option Read the document and adding the parameters DOC_ID=HRM, DOC_TYPE=DOC*HTML. The parameters must appear in quotes as shown in the following figure. The DOC_ID is the name of the document entity registered in the repository. The entity points to the file HRM.HTM which contains the HR Policy. DOC*HTML is the default value for DOC_TYPE. 3. Save the OpenInsight form, then compile and save it with HTML Publisher. HTML Publisher creates the following script. <!-- Generated by the Revelation HTML Publisher > <HTML> <HEAD> <TITLE> HR Application </TITLE> </HEAD> <BODY BGCOLOR="#ffffff" > <FORM METHOD="post" ACTION="./INET_REPOS"> <TABLE> <TR VALIGN="top"><TD ALIGN="left">HR Application</TD></TR> <TR><TD ALIGN="left">Click here to see the HR Policy</TD></TR> </TABLE> <INPUT TYPE="hidden" NAME="DOC_ID" VALUE="HRM"> <INPUT TYPE="hidden" NAME="DOC_TYPE" VALUE="DOC*HTM"> </FORM> </BODY> </HTML>

19 Chapter 17: Internet Publishing 639 To understand how the HTML Publisher generated this code you need to refer back to the topics OpenInsight Form to OI Page Conversion, Concepts and Conventions, and Understanding the Submit Event covered earlier in this chapter. The following information covers some of the main concepts. 1. The OpenInsight form is mapped/converted to the <FORM> tag with the METHOD and ACTION attributes. Setting the METHOD equal to post means that the CGI program gets its input from the standard input used on the OI Page; in other words from the <INPUT> tags. The ACTION attribute specifies the Internet procedure indicated in the SUBMIT event for the form. 2. All of the controls on the OpenInsight form (in this example the two static text controls) are put into a <TABLE> element. This is how the HTML Publisher attempts to provide some formatting in an environment that doesn t use x,y coordinates for alignment purposes. 3. The QuickEvent parameters for the window s Submit event are mapped to the <INPUT> tags with the TYPE attributes is set to hidden. The NAME and VALUE attributes work as a pair and specify a Query Item. 4. The OI Page displayed in the browser is shown in the figure below. When you click on Click here or press the ENTER key, the browser packages the form input for delivery to the web server using a special format called URL encoding. Notice the URL displayed in the figure below. The Query Items are concatenated using ampersands (&).

20 640 Section 6: Deployment Ad Hoc Reporting The following example shows one method of dynamically publishing a report to the web using OpenInsight for Workgroups Internet publishing features. Procedure: To Dynamically Publish Reports to the WWW 1. Create and save a report using Report Builder as described later in this chapter (in this example, TESTB). The report definition exists as an entity in the repository. 2. Create an OpenInsight form. This example uses a simple form, shown below, which lets you select a report from a list box and then preview it. The list box s control name must be REPORT_ID. 3. Define the QuickEvent SUBMIT for the window, deleting the Parameters information, as shown in the following figure. The REPORT_ID parameter value is assigned/passed when the resulting OI Page is displayed in the browser and the user selects a report from the list box. The other parameters are optional and do not need to be specified in the QuickEvent. Of key importance is that the list box on the OpenInsight form be named REPORT_ID. Save the form.

21 Chapter 17: Internet Publishing Choose HTML Publisher from the Form Designer's File menu (or SHIFT+doubleclick on the OpenInsight window executable WEB_PUB in the repository outline). Compile the OpenInsight form into an OI Page and save the.htm file in the \OINSIGHT\HTML subdirectory. 5. Display the form in a browser. This can be done by launching the HTML document entity from the repository outline.

22 642 Section 6: Deployment 6. With the form launched in the browser, select a report then click the PRINT! button. A request is created based on values from the OI Page s elements (including the elements derived from the SUBMIT QuickEvent on the form. The web server passes this request to OICGI who then passes the request on to the OpenInsight HTTP-Request Dispatcher to process.

23 Chapter 17: Internet Publishing 643 The following code is the HTML script for the OI Page displayed in the browser. <!-- Generated by the Revelation HTML Publisher > <HTML> <HEAD> <TITLE> REPORTS </TITLE> </HEAD> <BODY BGCOLOR="#ffffff" > <FORM METHOD="post" ACTION="./INET_RLIST"> <TABLE> <TR><TD ALIGN="left">SELECT A REPORT:</TD></TR> <TR> </TABLE> <TABLE> <TR VALIGN="top"> <TD><TD ALIGN="left"><SELECT NAME="REPORT_ID" SIZE="3"> <OPTION>TESTA<OPTION>TESTB<OPTION>TESTC</SELECT></TD> </TD> <TD><TD ALIGN="left"> <INPUT TYPE="submit" NAME="BUTTON_1" VALUE="PRINT" SIZE="13"> </TD></TD></TR> </TABLE></TR> </TABLE> </FORM> </BODY> </HTML> 7. The report is executed and the output formatted in HTML. The output is returned to the web server and delivered to the browser. The URL in the figure below indicates the current directory on the web server where the OpenInsight CGI program is located and the parameters being passed that result in the report being produced.

24 644 Section 6: Deployment To understand how the HTML Publisher generated this code you need to refer back to the topics OpenInsight Form to OI Page Conversion, Concepts and Conventions, and Understanding the Submit Event covered earlier in this chapter. The following information covers some of the main concepts. The OpenInsight form is mapped/converted to the <FORM> tag with the METHOD and ACTION attributes. Setting the METHOD equal to post means that the CGI program gets its input from the standard input used on the OI Page; in this case a combination of the <SELECT> and <INPUT> tags. The ACTION attribute specifies the relative path to OICGI and the Internet procedure specified in the SUBMIT event for the form. 1. All of the controls on the OpenInsight form (in this example the static text, list box, and button controls) are put into an HTML table. This is how the HTML Publisher attempts to provide some formatting in an environment that doesn t use x,y coordinates for alignment purposes. 2. The OpenInsight list box control is converted to the <SELECT> tag and it's attributes. The value of the NAME attribute is derived from the control's name. The push-button control is converted to the <INPUT> tag with a TYPE ="submit". 3. When the user selects a report on the OI Page, then clicks the PRINT button, the browser packages the form input for delivery to the web server which results in the following URL: Creating a Custom Internet Procedure As mentioned above, you can write your own custom Internet procedure. Refer to the topic "Concepts and Conventions" earlier in this chapter for the requirements. The following code is an example of a very simple custom Internet procedure that checks to see whether a value for the "PARAM" argument has been passed with request. This procedure is created in the System Editor, saved and compiled.

25 Chapter 17: Internet Publishing 645 function inet_feedback(request) $insert inet_equates declare function Inet_QueryParam myparam = Inet_QueryParam(request, 'PARAM') if len(myparam) else myparam = "Attention: You did not enter a parameter!" end html = "<HTML><BLINK> % </BLINK></HTML>" swap '%' with myparam in html return html A quick and easy way to test the functionality of this code is to enter a request in your browser similar to this: is a feedback test. When you press the enter key to process the request, the response is displayed in the browser as shown in the following figure. Type the same request without providing a value for "PARAM" and press the enter key. You should get the response shown in the figure below.

26 646 Section 6: Deployment

27 Chapter 17: Internet Publishing 647 Internet Procedures The following functions are used to implement OpenInsight s web publishing features. function Inet_Repos(Request) - Internet procedure that retrieves an HTML document from the repository. Parameters: Request [in] HTTP-request that carries the following parameters: DOC_ID DOC_TYPE Repository name of a document to retrieve. Repository TYPE*CLASS of a document to retrieve (defaulted to DOC*HTML ). return [out] Repository document in HTML or text format (as a result of the GETHTML method execution) Note: Currently only repository types DOC* HTML and DOC* NOTEPAD implement the GETHTML method. function Inet_Rlist (Request, RlistScript) - Internet procedure that produces an Rlist report in HTML format. Parameters: Request [in] HTTP-request that carries the following parameters: REPORT_ID STYLE_ID ARGS name of report created with Report Builder tool. name of HTML style sheet to use; NA. comma (, ) delimited array of arguments. Rlist Script [in] if specified, overrides a report specified by REPORT_ID item return [out] report in HTML format

28 648 Section 6: Deployment function Inet_Trace (Request) - Internet procedure that reflects the incoming request back to the client (used for remote debugging). OpenInsight ships with the source code of this procedure. Parameters: Request [in] HTTP-request. return [out] Incoming request as an HTML script. The following procedures are used to assist with OpenInsight s web publishing features. function Inet_QueryParam (Request, ItemName, DefaultValue, NewValue) - allows to get or set a specified item in an HTTP-request Parameters: Request [in/out] HTTP-request DefaultValue [in] name of an item to look for ItemName [in] the value to return if the item name is not found NewValue [in] if assigned, new value for the item return [out] value of a specified item (NULL if not found)

29 Chapter 17: Internet Publishing 649 function Inet_Msg (Request, MsgRec, MsgId, argv) - Converts a message from MSG to HTML format (see MSG function) Parameters: Request [in] HTTP-request MsgRec [in] message definition structure (can be null if MsgKey set) MsgId [in] name of the message to execute (can be null if MsgRec is set) argv delimited list of substitutable parameters return [out] message in HTML format function Inet_Security (Request, InetProcName) the function that is called by the HTTP-request dispatcher before it calls any Internet procedure specified in the HTTP-request. OpenInsight 3.3 ships with the source code of this function. Parameters: Request [in] HTTP-request InetProcName [in] Name of Internet procedure that is about to be called return [out] empty string to allow the call or valid HTML script with an error message (this message will be immediately passed back to the client)

30 650 Section 6: Deployment Report Builder The legacy tool, Report Builder is a non-procedural tool for creating columnar reports. Report Builder is a wrapper for Rlist, a reporting and query language. The undocumented Report Builder has been replaced in OpenInsight for Workgroups by the more powerful Revelation Reporter. However, Report Builder still exists in the repository and can be used to create a report which can then be published to the web in HTML format using the Inet_Rlist (Request, RlistScript) function. Report Builder must be started from the repository outline by SHIFT+double-clicking on the OpenInsight window executable ORMAIN. Report Builder is shown in the following figure. To create a simple report choose a table from the Select menu, then choose columns from the table. Details are shown in the following figure. Provide other report specifications as needed.

31 Chapter 17: Internet Publishing 651 Preview the report (as shown in the figure below) and save it when you are satisfied with the layout. This report can now be published to the web in HTML format. An example of such a report is shown below.

32 652 Section 6: Deployment Related Topics In this manual: Chapter 7: Form Designer Chapter 12: Non-Procedural Event Handlers Chapter 13: Procedural Event Handlers Programmer's Reference Manual