NetTalk WebServer - Adding Web Server Functionality to your Application
	Version beta www.capesoft.com Updated 20 February 2008

NetTalk WebServer - Template Reference

Learn NetTalk	Examples	Common Features	NetAuto Objects	NetSimple Objects	Dial-Up	Support	Version History

  = recommended reading

Adding WebServer Functionality to your Application

Summary 

1.         Add the Activate NetTalk Global Extension, and the Activate Web Handler Global extension to your application.

2.         Add a WebServer procedure to your application.

3.         Add a WebHandler procedure to your application.

These three steps are sufficient to build a web server that will serve static web pages from your web folder. However you may also add more procedures, based on the other NetWeb procedure templates if you want to. These templates will be explained in more detail later.

 Each of these three mandatory steps is discussed in more detail below.

1. Global Extension Templates

In order to use the NetWebServer functionality in your application you need to add two global extensions to your application.

 

Tip: If you’re new to Clarion, you add Global extensions by going to the Application menu, Global Properties option, or by clicking on the GLOBAL button on the toolbar.

1. Click on the Extensions button.

2. First add the Global Extension called “Activate CapeSoft’s NetTalk”.

3. Then to that add the second global extension, called “Activate NetTalk Web Server”.

There are no global options available regarding the Web Server functionality.

2. Add a WebServer procedure to your application

There are a number of ways to do this.

 

a.         Run the Import utility (Application menu, Template utility option, Select ImportNetWebServer). This imports the Web Server and WebHandler procedures. OR

b.         Simply import a WebServer window from an existing application, such as one of the examples. Go to the File menu, choose Import From Application, and select one of the example applications. Then select the Web server procedure and import it. OR

c.          Alternatively, make a new procedure, based on the Window template. To this window add a NetTalk object (using the “Include NetTalk Object”  Extension.) On the extension set the ThisObjectName to ThisWebServer (or anything else you like) and set the Base class to NetWebServer.The settings for this extension are described below. Optionally add the “NetWebServer Logging Controls” Control template to the window.

3. Add a WebHandler procedure to your application

As before there are a number of ways to do this.

 

a.         If you did step (2a) just now, then a WebHandler has already been added to your app. OR

b.         Import from an example. OR

c.          Create a new procedure, for example called Webhandler, based on the NetWebHandleRequest procedure template. Use the one listed on the Defaults tab and most of the hard work is done for you.

d.         Make sure the procedure prototype is set to
(String p_String)

e.         This procedure also has a “Include NetTalk Object” Extension template. Set the object name to ThisNetWorker, and the base class to NetWebServerWorker. The settings for this template are explained in more detail below.

Settings for the NetWebServer Base Class

When you use the NetTalk “Add NetTalk Object” extension, and set the base class to NetWebServer, then you will see a number of settings appear on the settings tab.

The settings on the settings tab are in turn placed on one of four sub-tabs.

General Settings

Listen on Port Number: This determines the port number that this web server is listening on. Only one program can listen on a specific port at a time. The default port for public web servers is 80, but this will only work if there is no other web server installed on the machine (running on port 80.)  You are free to use any port number, but numbers above 1000 are usually considered safe.  When accessing your server from a remote machine, if the port is not set to 80, then you will need to specify a port number.  For example if you are accessing a server on 192.168.1.1, on port 88, then the URL for that looks like this;

 http://192.168.1.1:88

If you wish to listen on multiple ports then add multiple WebServer objects to the window, each listening on a different port number.

The default port for Secure Sites (ie using SSL) is 443.

Use SSL to make the server secure: If you want this object to be SSL enabled then tick this option on. See the document Building Secure Web Sites for more information on SSL sites.

Certificate: If you make a secure site you’ll need a certificate. The document Building Secure Web Sites covers getting, and installing, certificates in a lot more detail.

Handler Procedure: Select the Handler Procedure that belongs to this WebServer procedure. This is the procedure you created in Step 3 above. If you have multiple WebServer procedures then you can share Handler Procedures. (i.e. one Handler procedure can support multiple WebServer procedures.)

Web Directory: If left blank the the default is WEB. This is the directory, usually under the application directory, where the web files (HTML and so on) can be found. It’s possible that your app has no external files, but it’s more likely that you’ll want to have at least some static files. The Styles, and Scripts directories, are by default, sub-directories of this folder.

Default Page: This is the first page of your site, the one people get if they don’t enter a page name. A typical site sets this to ‘index.htm’ or ‘default.htm’. Of course you then need a page with that name.

Login Page: If your site contains pages visible only to users that are logged in, then set this to be the name of your Login page. That way, if a user attempts to access a restricted page, and is not logged in, then they will be redirected to the login page.

Login Page is a control: You may use the NetWebForm template to create your login page. If so then tick this option on.

Date Picture Format: Use this to set the default date format for your site. The default is dd/mm/yyyy but an alternative is mm/dd/yyyy.

Generic Page Header Tag:

Generic Page Footer Tag:

It’s is possible to create browses and forms and source procedures in your app. These are usually used as controls on a page. However they can also be used as pages in their own right. When they are it’s possible to specify a common header, and/or footer (source) procedure that can get generated around the page.

These settings are in the form of tags. For example;

'<!-- Net:PageHeaderTag -->' would use a procedure called PageHeaderTag.

Suppress Error Messages: This is on by default, and I recommend leaving it on. When you make server software you don’t want error messages popping up on the (server) window, and halting the server. If you are having TCP/IP problems then tick this off to see what they are.

Scripts Settings

Scripts Directory:  Leave this blank to use the default (web\Scripts) or specify your own value here.

Scripts: Add any JS files that your site requires here. The files shipped with NetTalk do not need to be added here, they are automatically added for you.

Styles Settings

Default Form Style: Select the default Form Style from the drop down list. There are currently 4 supported styles;

Plain

Rounded

Tabbed

Outlook

Default Browse Style: Set the name of the CSS Class that you want to be used as the default BrowseStyle.

Styles Directory:  Leave this blank to use the default (web\Styles) or specify your own value here.

Styles: Add any CSS files that your site requires here. The files shipped with NetTalk do not need to be added here, they are automatically added for you.

Buttons

On this tab you can specify the default settings for the different types of buttons in your web application. For each button you are able to set the:

• Text: This is the text that will appear to the end user.

• Image: this is the image that will appear on the button. (For now only FireFox and Opera browsers support this feature.)

• Image Width, Height and Alt: These specify the attributes of the image.

• Class: This is the CSS class that will be applied to the button.

Note: For internet Explorer it is possible to make a button containing an Image by using CSS. A number of built-in classes are available in MSIE.CSS which contain examples of this. Example 23 has good examples of using these button settings, with various classes and images, to get graphics on buttons, and buttons (with graphics) as items in a Browse.

Advanced Settings

Always redirect to Secure Site: If your web server procedure has 2 NetTalk WebServer objects.  (One secure, and one not-secure). And this is the Non-Secure object. Then you can redirect all requests on this object to the secure object.  Use this switch when you want a completely secure site, but you also want to listen on a port (for example, port 80) for unsecure traffic.

Bind Server to only IP: Allows you to set the server so that it only responds to requests that arrive via a single netweork connection. Set this to 127.0.0.1 to force the user to use the browser on this machine. (Good for Service interfaces.) Or set it to the LAN address to restrict access only to the LAN. You can read more about this feature in the document Building Secure Web Sites.

Settings for the NetWebServerWorker Base Class

Suppress Error Messages: This is on by default, and I recommend leaving it on. When you make server software you don’t want error messages popping up on the (server) window, and halting the server. If you are having TCP/IP problems then tick this off to see what they are.

Settings for NetWebPage Procedure template

The NetWebPage procedure template is the base template for HTML pages that you want to include in your app. (your server can also serve static pages off the disk.)

The procedure settings can be accessed via the NetWebPage Settings button.

There are also a number of extensions that can be added to this page – these extensions will be discussed in more detail later in this document.

Click on the NetWebPage Settings button to see the settings for this procedure.

General Tab

PageName: When linking to this page from other procedures in your app you may use the procedure name directly without any extension. However if you wish to use an alternate name then enter the Page Name into this field. This field cannot contain a variable or expression, and so does not need quotes. For example

Index.Htm

Page Title: In HTML pages can have a title – which is not displayed on the page itself, but can be used by the browser (and search engines) to describe the page. Enter the title here if you want one. For example

‘NetTalk WebServer Example Site’

 

Scripts Tab

Enter the names of any custom Script files (.JS files) used by this page. You do not need to add the files NetTalk ships with, and you do not need to add any files entered on the Scripts tab of the WebServer settings.

Styles Tab

Enter the names of any custom Style files (.CSS files) used by this page. You do not need to add the files NetTalk ships with, and you do not need to add any files entered on the Styles tab of the WebServer settings.

HTML Tab

Use this tab to enter HTML snippets onto the page. Snippets entered here will automatically be “encoded” into Clarion in a Routine. The page is then put together from one or more snippets. You can also "embed" other NetWebSource procedures in your page by using this tab.

Embed: You can select to embed another procedure (usually a NetWebSource procedure) or a Routine (containing HTML) at this point. 

If you select Procedure then you can enter;

Procedure Name: The name of the procedure to embed.

Parameters: any parameters required by the procedure. NetWebSource procedures always have the p_web as the first parameter, so this is the default. Brackets are not required in this field.

Return Value: If the procedure returns a value, and you want to store the returned value in a variable, then enter the variable here.

If you select Routine then you can enter;

Routine Name: The name of the routine this snippit will end up in.

HTML: The HTML itself can be cut & pasted from any visual web page editor.

For both options you can enter;

Condition:  Surround the call with a condition. If the condition evaluates to True then the Routine or Procedure will be included. This is ideal if you want to base the call on some condition, like for example the fact that the user is logged in (or out). 

Location: Enter the location where you want to embed the call.

Note that you don’t need to put the whole web page in here. Just HTML that would normally reside inside the <body> </body> tags. All the rest of the page, such as the header, will be generated for you.

Advanced Tab

No <body> tag: In most cases your page should have a Body tag. However in very special cases you may prefer to code this in yourself. In that case tick on this option. Using the FrameSet extension template automatically suppresses the body tag.

User must be Logged in: Tick this on if the user must be logged in to view this page. If this is on attempts to go directly to this page, without logging in will redirect the person to the Login page.

Only Server is Secure SSL: This page is only accessible via the Secure SSL port. If this page is requested via the unsecure port, then the request will automatically be re-routed to the secure port.

Settings for the Frameset Extension Template

This template can be added to NetWebPage procedures. It generates the html code for a FrameSet for you. Before using this make sure you understand Frames just a little, and read the introduction to Frames in the document Webserver Basics.

Frames allow you to split the web page up into different areas, and treat each area separately. For example in Example 4 the page is split up like this;

Example 4, FrameWithMenu, contains an example procedure with a FrameSet extension. The procedure is called FramePage.

Tip: When adding this extension tick on the option right at the top called Show On Procedure Properties. This will put these settings on the Window Properties page, where it is easy to get to them.

General Tab

Maintain Sessions: This make sure that the Session ID is passed on the various links that are generated. Unless your site is completely static leave this on. And even if it is completely static leaving it on is a good idea.

FrameSets:

Name: This the name frameset you make. The name is important, and case sensitive. I use names like top, and bottom, or left and right and so on.

Rows: Enter the number of rows into which this Frameset will be divided.

Row Sizes: Enter a comma delimited list of the row sizes here. Use either a specific number, or a *. Entering ‘100,*’ means that the first row is 100 units high, and the second is whatever is left. If you had 3 rows then you could enter ‘100,100,*’ or ‘100,*,*’ or even ‘*,*,*’’.

Columns: Sames as rows, but indicates the number of columns.

Column Sizes: Same as Row sizes.

Contents: These contain the contents for the FrameSet. The number of items here Must match the number of panes in your frame set. Ie Rows * Columns. (Where a blank value is treated as 1). The contents are assigned first by row, then by column.

Each item consists of either a Frame, or another Frameset.

Frameset Name: If another Frameset then enter the name of the frameset here. This must match the name of another frameset as defined in the list of frameset. Don’t use any quotes, and remember it is case sensitive.

Frame Name: If the Item is a frame then enter the frame name here. Use something simple you’ll remember because later on you’ll direct pages using this frame name. Don’t use quotes here.

URL: When the Framset page is opened each frame is immediately filled with a default page. Enter the default URL for this frame here. Use quotes. Use the name of another NetWebPage if you like. (But still put it in quotes. For example ‘PageHeader’.

Scrolling: Set the scrolling option for this frame. Auto places scroll bars in the frame only if the content is bigger than the frame. No supresses all scroll bars, and Yes always has scroll bars even if the content fits in the frame. The recommended value is Auto.

Frame Border: Tick this on if you want the Frame to have a border. Borders are necessary if you want to support resizing.

Allow resizing: Allow this frame to be resized. In almost all cases you should allow resizing, unless for some reason you want to fix the size of a frame.

Left/Right Margin: The margin space to be used on the left, and right, side of the frame.

Top/Bottom Margin: The margin space to be used on the top and bottom of a frame.

Advanced Tab

Text if browser doesn’t support Frames: Enter HTML here that will be visible to the user if frames are not supported. This may be an error message, (example: Bummer – Frames not supported) or an alternate index page for your site; for example:

<!—Net:IndexPageNoFrames -->

Settings for the WebBorder Extension Template

The WebBorder extension template allows you to wrap some html in a fancy border.

A good example of using this template is in example 1, BasicBrowseAndForm, in the PageHeaderTag procedure.

General Tab

Border style: If set to round then the border has rounded corners. If set to plain then it has square corners. Note that the classes set on the Styles / CSS tab set the colors of the border.

Blank Line Above: Includes a space above the border after the previous part of the page.

Blank Line Below: Includes a space below the border before the next part of the page.

HTML Tab

This is the HTML that will be included inside the border. It does not include the border itself.

Routine Name: The name of the routine that will be generated to contain the HTML code.

Condition: A condition that specifies whether the HTML will be included or not. If the condition exists, then it must evaluate to TRUE for the HTML to be included.

HTML: The HTML to include.

Styles / CSS Tab

This tab allows you to change the CSS styles that will be used. You can read more about CSS in the document NetWebServer CSS.

Outer Div Class: Set this to the class to use for the outer DIV. A rounded border itself is made up of 2 DIV areas, with potentially different colors. The default for this class is ‘headingouterdiv’.

A plain border only has one DIV. (The Outer Div.)

Inner Div Class: Set this to the class to use for the inner DIV. The heading for this class is ‘headinginnerdiv’.

Settings for the WebMenu Extension Template

Menu Style: There are currently 2 different menu styles supported by this template. The first is a drop-down Windows style menu. The other is an Outlook style menu.

For an example of the Windows style menu see example 2, BasicWithMenu, PageHeaderTag procedure.

For an example of the Outlook style menu see example 4, FrameWithMenu, MenuOnLeft procedure.

Maintain Sessions: Tick this on to maintain the session number when menu items are called.

Blank Line Above: Thick this on to add a blank line above the menu on the page.

Blank Line Below: Tick this on to add a blank line below the menu on the page.

Menus: Each menu consists of multiple items.

Menu: the name of the menu on the menu bar.

Menu Condition: An optional condition. If it exists, and it evaluates to true, then the menu is included.

User must be logged in: Tick this on if the user must be logged in in order to see this menu.

URL: Enter a URL here if the menu itself is clickable, and there is no drop-down for this menu. This is only available in the Windows Style menu.

Target Frame: If the URL is entered, and you want to specify a target frame, then enter it here.

                Items: Each menu will consist of 1, or more items. (If a URL is entered for the menu itself, then menu items
                are not allowed.)

Display: The text to display for the menu item.

Item Condition: An optional condition which (if it exists) must evaluate to True in order for the menu item to be displayed.

User must be logged in: The user must be logged in to see this menu item.

URL: The URL to go to if the menu item is selected. This can be a procedure name in the app, or an HTML page name. For example;

‘MailboxesBrowseControl’ or

‘Somepage.Htm’

Target Frame: If your site has multiple frames, then enter the name of the target frame here. Target frame names are case sensitive. The page the user has chosen will appear in the target frame. If this is left blank then the page will appear in the current frame. You can enter an expression here, so use quotes if you are entering a specific frame name.  For example;

‘left_fram’

The names of the frames are set on the FrameSet extension template, in the Frame Name. Note that when setting the frame name quotes are not used.

Image: Enter the name of an image here.

Image Width: Enter the width of the image.

Image Height: Enter the height of the image.

Image Alt: Enter the alternate text for the image, if applicable.

Styles / CSS tab

Windows Style

Drop Menu: Set the style to be used for the drop-down menu. Default is ‘DropMenu’.

 

Outlook Style

Outlook Menu: Set the style to be used for the Outlook style menu.

Title: Set the style for the title bar of the menu.

Content: Set the style for the content part of the menu.

Settings for the NetWebGraph Extension template

Note: This extension allows the use of Insight Graphing graphs in your WebServer application. Insight Graphing is not included with your NetTalk purchase. For more information on Insight Graphing visit the CapeSoft web page

http://www.capesoft.com/accessories/isgsp.htm

An example of using this extension is example 10, BasicGraph.

This extension is designed to be attached to a normal Window procedure, onto which an Insight graph has been populated.

The procedure must have the p_web parameter declared as:

NetWebServerWorker p_web

or

<NetWebServerWorker p_web>

There are no extra settings for this extension. All the settings for the graph are done, as normal on the Insight extension. The size, and shape, of the Insight control on the window dictates the size, and shape, of the graph on your web page.

Settings for the NetWebBrowse Procedure Template

The NetWebBrowse procedure template allows you to make a Browse Control, which you can then embed on a page. You can also call the procedure directly, which will wrap the control in a generic page.

A good example of the Browse template is in example 1, Basic Browse and Form.

The procedure must have the prototype

(NetWebServerWorker p_web,long p_action=0),long,proc

The procedure must have the Declare Globally option ticked on.

The settings for the browse are accessed via the NetWebBrowse Settings button.

The table being browsed, as well as the initial sort order, are set under the Tables button.

General Tab

Browse Heading: An optional heading for the browse.

Browse Subheading: An optional subheading for the browse.

Filter: Enter an optional view filter here. Use this to limit the number of records that will be used in the browse. See also the Locator Type (on the options tab) and the Runtime Filter tab (Fields area) for additional ways to limit the records on the browse.

Message If Empty: If there are no records in the browse then this text will be displayed.

Page Name: By default you can use the procedure name as a URL to bring up a generic web page containing the Browse control. However if you want the client to see the address as, say an HTM name, then you can fill in a page name here. For example, if the Page name is set to ProductsBrowse.Htm and the site links to ProductBrowse.Htm then this browse control will be served, wrapped in the generic page.

Page Title: If this control is called as a page, and hence is wrapped in the generic page, then you can set the title of the generic page by using this field.

Default Sort Order: Enter the default sort order here. If this is left blank then the KEY set under the Tables button is used. This expression should be of the form

Fields:

General Tab:

Field: The name of the field being displayed in the  browse column.

Description: A description of the column. This is only used internally on the template list, and not in generated code.

Format Picture: A picture for the field. The picture field is primed from the dictionary, so having a correct dictionary saves a lot of work here.

Display: An optional field that overrides the Field value. Use this when you want to display an Expression, and not a single field.

Header: the text that should appear in the header for this column.

Not In View: If the field is a local variable, and is not in the table, then tick on this option.

Column Condition: If a condition exists here, and it evaluates to false, then the whole column will be suppressed, regardless of the individual cell conditions.

Style: Enter an optional CSS style for this column here.

               

Runtime Filter Tab:

                                Not operational yet             

 

Image Tab:

This tab allows you to set an image to appear in the cell. The image can be overridden (and hence not appear) if images on the Conditional tab are used. The image will display to the left of any text that appears in the cell.

 

Conditional Tab:

This tab allows you to override the contents of a cell depending on external conditions. For example you may want an image to show whether an employee is in, or out. You could use this tab to set the condition, and also the image to display.

 

Totaling Tab:

This tab allows you to set totaling options for this column. You can override the style of an individual total by entering it into the style field. However if you want to change the style of all the totals then set iy on the Style / CSS Tab.

Hot Fields Tab

Enter additional fields here that you want to be included in the VIEW structure. Only fields in the view can be reliable used in any hand-code you may embed on the browse.

Form Tab

Show Buttons: Tick on the various buttons that may appear under the form. If allowed, the Select and Cancel buttons will only appear when the browse has been called as a Lookup. The Insert, Change, and Delete buttons will not appear when the browse has been called as a lookup.

Button Position: Use this to determine the position of the Insert, Change and Delete buttons. The position can be either above, or below the browse, or both.

Call form only if Logged In: If this option is on, and the user is not logged in, then the Insert, Change, and Delete buttons will not be displayed.

Form Control Procedure: Enter the name of the form procedure here.

Form URL: If you leave the Form Control Procedure blank you can link directly to a URL. This allows you to hand-code a custom form.

Select Condition: Enter a condition here that must be matched in order for the Select button to appear when the browse is called in Lookup mode.

Select / Cancel URL: In most cases, when called in lookup mode, a browse should go back to the form. This is the default behavior if this field is blank. However you can enter a custom URL in here if you wish to go somewhere else.

Unique, Unchanging, Key: When calling a form it is important that a Unique, unchanging, Key be used to identify the record being changed. Enter the key here. If this field is left blank then the Primary key will be used. Not that which ever key is used the fields that make up this key should not be included on the Form itself.

Options Tab

This tab covers various options regarding the Browse behavior.

Greenbar: Tick this option on to have a greenbar effect occur on the browse. This typically alternates the row color of the browse rows to create a visually pleasing effect.

Show Column Headings: Tick this option on to include column headings on the browse.

Loading Method: Set this to File or Page. File loaded browses display all the records, regardless of the file size. This is ideal for small files. Page-loaded browses only show a fixed number of records at one time. This is faster, and more appropriate, for tables with a large, or indeterminate, number of records.

Records per Page: If set to Page-Loaded, this determines the number of records displayed on the page.

Include Blank rows: If set to page-loaded, this forces that the number of records be consistent, even if there is insufficient data to fill those rows.

No Sorting: The browse cannot be resorted by the user. The initial sort order still applies though.

Client Side Sorting: The user can resort the table based on the column headings. The sort is done by the browser itself, and data is no re-fetched from the server. This sort is ideal for file-loaded browses.

Server Side Sorting: The user can resort the table based on the column headings. The sort is done on the server, and the browser re-fetches the visible page. This sort is suitable for page-loaded, or file-loaded browses.

Locators: Locators are only available for Page-Loaded browses. They allow the user to automatically jump to a specific place in the browse.

In the case of Server Side sorting the Locator field is automatically changed whenever the sort field is selected.

Locator Position: Select the position of the Locator to be either above or below the browse, or both.

Locator Type: Select either a Position,Range or a Contains locator. 

A position locator loads the table at the closest place to the locator selected. The user can then scroll up, or down, through all the records. 

A Range locator limits the records to those that match the Locator.
For example: If a range locator is selected, and the user enters RED as the locator, then only records starting with the letters RED will be displayed. Redfern, Redvers and Redza would all be visible.  However no other records will be visible.

A Contains locator is similar to a Range locator, but the locator string can exist anywhere in the field. So if the contains locator was set to RED then agredible, redder, and corred will all be visible.

Table Blank until Locator entered: Especially useful on the Range and Contains locators. If this is ticked then no records are returned in the browse if the locator is not filled in.

Message waiting for: Enter the message that will be displayed to the user if no records are being displayed because the system is waiting for a locator to be entered.

HTML Tab

Use this tab to enter HTML snippets onto the page. Snippets entered here will automatically be “encoded” into Clarion in a Routine. The page is then put together from one or more snippets. You can also "embed" other NetWebSource procedures in your page by using this tab.

Embed: You can select to embed another procedure (usually a NetWebSource procedure) or a Routine (containing HTML) at this point. 

If you select Procedure then you can enter;

Procedure Name: The name of the procedure to embed.

Parameters: any parameters required by the procedure. NetWebSource procedures always have the p_web as the first parameter, so this is the default. Brackets are not required in this field.

Return Value: If the procedure returns a value, and you want to store the returned value in a variable, then enter the variable here.

If you select Routine then you can enter;

Routine Name: The name of the routine this snippet will end up in.

HTML: The HTML itself can be cut & pasted from any visual web page editor.

For both options you can enter;

Condition:  Surround the call with a condition. If the condition evaluates to True then the Routine or Procedure will be included. This is ideal if you want to base the call on some condition, like for example the fact that the user is logged in (or out). 

Location: Enter the location where you want to embed the call.

Styles / CSS Tab

On this tab you can set the CSS styles that will apply to this browse.

Advanced Tab

User must be logged in: The user must be logged in for this browse to appear. If the browse is on a generic page by itself, then the user will be redirected to the login page. If the browse is included as a tag on a bigger page, and the user is not logged in, then the browse control is simply not included.

Only serve if Secure SSL: The connection must be on a secure port. If not, and a secure port exists, then the request is automatically redirected to the secure port.

Force whole page refresh when browse changes: By default, if supported by the browser, the server will only refresh the browse area when the user clicks on the Next (etc) button by using Ajax techniques. If you wish the whole page to be refreshed (ie no Ajax) then tick this option on.

Multi-Record Rows: Implicit in each browse is the idea that 1 record in the data file = one record on the browse. However NetTalk Web Server allows for multiple records to appear on the same line of the browse.

Start new Row When: Enter an explicit row-breaking condition here.

When Row Starts: Optionally enter HTML code here to include at the front of every row in the table.

Session Variables: The template can create local variables for you, and copy the current contents of the Session variable into the local variable.

Variable: Enter the name of the Session variable here. The local variable will be created with the same name, but with the LOC: prefix. For example a session variable called EmployeeName will be created (and primed) as LOC:EmployeeName.

Variable Type: Enter the Type of the Variable here (String, Long etc). If no type is entered then the variable will be made with the type STRING(255).

Settings for the NetWebForm Procedure Template

The NetWebForm procedure template allows you to create a Form Control, which you can then embed on a web page. You can also call the procedure directly, which will wrap the control in a generic page.

A good example of the Form template is in example 1, Basic Browse and Form.

The procedure must have the prototype

    (NetWebServerWorker p_web,long p_action=0),long,proc

The procedure must have the Declare Globally option ticked on.

The settings for the form are accessed via the NetWebForm Settings button.

General Tab

Form Style: This allows you to override the Default Form Style for the web server. Typically you would not set this unless you were overriding the global style. (The global style is set in the WebServer procedure, Extensions, NetTalk object, Settings Tab, Styles tab, Default Form Style.)

Form Source: Select either File or Memory.

File: The name of the file that is being changed.

Unique, Unchanging, Key: In order for forms to work, you need to have a Unique Unchanging Key for the table. The fields in this key must NOT be on the form.

Form Heading: The heading for the form (optional).

Form Subheading: The subheading for the form (optional).

URL on Save/Cancel: By default the form will go to the place it came from (usually the Browse). If you wish to go somewhere else then enter the URL here.

Target Frame: If you want the Save / Cancel button to link to a page in another frame then specify the Frame name here.

Page Name: By default you can use the procedure name as a URL to bring up a generic web page containing the Form. However if you want the client to see the address as, say an HTM name, then you can fill in a page name here. For example, if the Page name is set to ProductsForm.Htm and the site links to ProductForm.Htm then this form control will be served, wrapped in the generic page.

Page Title: If this control is called as a page, and hence is wrapped in the generic page, then you can set the title of the generic page by using this field.

Fields Tab

Tabs: Each form contains one, or more, “tabs”. The actual presentation of these tabs depends on the form style used

Heading: The heading of the tab.

Tab Condition: An optional expression for this tab. If the expression evaluates false then the tab is suppressed from the form.

Fields: Each tab contains one or more fields.

Field: The name of the field being edited.

Prompt: The prompt that will appear to the left of the field, on the form.

Condition: An optional condition, which if it exists, must evaluate to True for the field to be displayed.

Type: The type of the field being entered.

Comment: An optional comment that will appear to the right of the entry field giving additional instructions. If not entered then some comments are generated automatically based on validation rules.

Advanced:

Submit Form When Clicked: [work in progress]

Read-Only Condition: If this condition is true then this field is set as read-only. If false then the field is editable. This overrides the Read-Only option on the previous screen.

String and Text Settings:

Lookup Button: Tick this on to include a Lookup button to the right of the field.

Lookup Button Settings

URL:       The URL of the lookup window.

From File: The file which contains the value being looked up.

Value Field: The field, in the remote table, which will be retrieved.

Description Field: The field in the lookup file which contains the text of the lookup value.

Auto-Lookup on Insert: Tick this option on if you want the user to go straight to this lookup, before the form displays. For example on the browse you have an Insert button to add an Invoice. The first thing to do when adding an invoice is to select a Customer. If this button is ticked (on the Customer lookup field) then the page will go straight to the lookup, select the customer, then continue on to the form.

Force user to use lookup: If this is on then the user can only change the field by using the lookup button. This applies only to Date, String and Text fields.

Read-Only Field: Tick this to make the field Read-Only.  Read-only fields allow Cut & Paste, so use this for cases where you want the user to see the value, but not change it.

Password Field: Tick this on if the field is a password field. Password fields do not display the text entered into them.

Width: Optionally override the width of the field here.

Date Settings:

Refresh Window When Date Changed: Tick this option if the page should be refreshed when ever the date field is changed.

Read-Only Field: Tick this to make the field Read-Only.

Force user to use lookup: If this is on then the user can only change the field by using the lookup button. This applies only to Date, String and Text fields.

Use an Image for the Lookup button: Tick this on to use your own image on the lookup button.

Droplist Settings:

From File: The related file containing the value to lookup.

Filter: The filter which will be applied to the View. Enter an expression here. Records which evaluate to true will be included in the Droplist.

Value Field: The field in the remote file, which should be used in the Form file.

Description Field: The field in the remote file which is displayed to the user.

Droplist Prefix Options:

Droplist suffix Options:

                                Validation:

Required: Tick this on if the field is required.

Numeric: Tick this on if the field is numeric.

Low: If the field is numeric, set an optional low-value.

High: If the field is numeric set an optional high-value.

Layout Tab

Source Before: Obsolete - use HTML tab to embed procedures.

Source After: Obsolete - use HTML tab to embed procedures.

Vertical: Usually the Form is generated in a horizontal format.

Prompt : Value : Comment

In some cases it is good to generate it in a Vertical format.

Prompt

Value

Comment

An example of this is the LoginForm procedure in Example 4.

Suppress Comments: If you wish to suppress the comments column, then tick this option on.

HTML Tab

Use this tab to enter HTML snippets onto the page. Snippets entered here will automatically be “encoded” into Clarion in a Routine. The page is then put together from one or more snippets. You can also "embed" other NetWebSource procedures in your page by using this tab.

Embed: You can select to embed another procedure (usually a NetWebSource procedure) or a Routine (containing HTML) at this point. 

If you select Procedure then you can enter;

Procedure Name: The name of the procedure to embed.

Parameters: any parameters required by the procedure. NetWebSource procedures always have the p_web as the first parameter, so this is the default. Brackets are not required in this field.

Return Value: If the procedure returns a value, and you want to store the returned value in a variable, then enter the variable here.

If you select Routine then you can enter;

Routine Name: The name of the routine this snippet will end up in.

HTML: The HTML itself can be cut & pasted from any visual web page editor.

For both options you can enter;

Condition:  Surround the call with a condition. If the condition evaluates to True then the Routine or Procedure will be included. This is ideal if you want to base the call on some condition, like for example the fact that the user is logged in (or out). 

Location: Enter the location where you want to embed the call.

Styles / CSS Tab

On this tab you can set the CSS styles that will apply to this form.

Advanced Tab

User must be logged in: The user must be logged in for this form to appear. If the form is on a generic page by itself, then the user will be redirected to the login page. If the form is included as a tag on a bigger page, and the user is not logged in, then the form control is simply not included.

Only serve if Secure SSL: The connection must be on a secure port. If not, and a secure port exists, then the request is automatically redirected to the secure port.

Include Cancel Button: If this is on then a Cancel button is included on the form. Tick this option off if the form will usually be part of a bigger page.

Include Delete Button: Deletes can be done directly off the browse, or you can choose to open the form and have the user click the Delete button. If this option is on then a Delete button is included on the form (when the user has clicked the Delete button on the browse.)

Field Priming: Fields on the form can be primed to values, when the form is called for Insert or for Change.