Copyright: Copyright (c) 1995-1999 HREF Tools Corp.


WebHub Help File Contents

Shortcuts: | Hub Panels | WebHub Event Macros | WebHub VCL Components |

See WebHub Run

Use this URL to test your installation and see the WebHub demos:

http://localhost/htdemo/index.htm

Introduction

• WebHub - An Overview

• WebHub Lite Defined

• Understanding WebHub URLs

• Documentation Style Conventions

Installation

• Installing a Web Server

• Testing the WebHub Installation

• Installing Components in Delphi

Skills

• Creating a new AppID

• Working with HTML Files

• Creating a new Delphi Project with the WebHub Wizard

• Creating a new Delphi Project without the Wizard

• Application Defaults

WebHub-HTML ("W-HTML")

• Pages

• Chunks

• Macros

• Component Properties

• Built-in Event Macros

• Importing Existing HTML Files

WebHub Components (VCL)

• Components and Classes

• Form to HTML Converter

WebHub User Interface

• Panels

• ComboBar

• Menus

WebHub System

• Unlocking Hub Capacity

• Running Programs as a Service

• Command Line Options

• Runners

• HubLog

• WebHub Coolness Layer

• WebHub Application Icon Colors

WebHub Utilities

• AdjDpr

• Wait

Advanced Topics

• About the INI Files

• Property Editors

• How Macros are Decoded

• Maître d'Hub Mode

Related Product Recommendations

• Recommended VCL Products

• WebHub Add-On Products

Copyright 1995-1999  HREF Tools Corp.  All Rights Reserved. Last updated 3 August 1999.

Help file updates are free to download from http://www.href.com/pub/docsnhelp.


WebHub: An Overview

People use WebHub to solve business problems by developing applications that run over the web. The solution might be a static or a dynamic web site.  The technology works equally well for Internets, Intranets and Extranets.  Most people use WebHub to build dynamic, database-driven sites.

The WebHub paradigm may not appear simple at first.  While other systems claim to follow the K.I.S.S. system (keep it simple, sweetheart), WebHub claims elegance, extensibility and long-term benefits.  Most people say that the more they work with WebHub, the more they grow to appreciate the depth and breadth of the underlying design.  This help page explains the basics.

Object Oriented Web Applications

When you use WebHub, you organize your features around a few key objects: the machine your application runs on (TWebInfo), the web application itself (TWebApp), web pages (TWebPage), surfer data (TWhSession) and web action components (TWebAction).  You can look up any of these objects in this help system, and see how their properties and methods relate to the work you do on a daily basis.  For example, when you maintain the list of HTML files in the project, you are maintaining the TWebApp.Files property.

The benefit to this strong organization is that there is a place for everything.  By understanding the various components, you will know where to put things.  For example, if you have a setting that needs to be kept separately for each surfer, that belongs on the TWhSession object, probably as an entry in the Literals property.  If you have a setting that is "global" for the application, that belongs on the TWebApp object, probably as an entry in the Defaults property.

If you are not responsible for programming, and are using a WebHub application that someone else made for you (maybe you downloaded one from HREF Tools, or maybe you are working with a programmer)... then all of this design is invisible but serves as a very strong foundation for any additional features you might want to add down the road.

Save-State is Built In

WebHub includes a multiuser state engine.  The benefit is that you will always have surfer-specific information available, no matter how many pages are involved.  This single issue generally costs developers weeks and sometimes months of work in other programming systems.  In WebHub, the surfer's data is available on the TWhSession object, primarily in the Literals property.  For database programmers, the functionality extends through features on the TWebDataSource object.

If you are new to web programming, look at the WebHub demo called FORM. It uses a playful example to demonstrate how save-state works in WebHub.

Separation of HTML from Program Logic

One of the key benefits of WebHub is that you can easily separate the user interface (HTML, graphics, JavaScript, etc.) from the program logic, or business rules.  In other words, a programmer can write a generic program that is not tied to a specifc user interface.  Instead it uses chunk and macro IDs as placeholders for HTML that is maintained in ASCII files outside the project.  If someone wants to change the page style, that is done by editing the ASCII file.  There is no recompilation necessary.

How to use the dynamic features

The key is to use macro syntax to invoke text substitution macros, chunks, pages, built-in event macros, custom event macros, and web action components.  For example, let's say you have a web page that needs a grid coming from a database. You would have an web page defined something like this:

<h2>Ok here is some HTML</h2>

The grid follows:

<p>

%=webdatagrid1.execute=%

<p>

<hr>Copyright notice here.

The %= tags invoke the web action component.  That component then does some work -- sometimes a lot, sometimes a little -- to do the required action, and generally to output some HTML which is filled in on the page.

Web Actions for Beginners

The best place to start is by making a web action component that does something simple, such as in the Hello, World example.  (See the User Manual, Cookbook.)  The TWebOutput component has a number of helpful methods such as Send which are used to generate HTML on the fly.  Here's an example, where we customize the OnExecute event handler for a component named WebAction1:

procedure TfmAppSendStr.webAction1Execute(Sender: TObject);
begin
  inherited;
  with TWebAction(Sender).WebOutput do begin
    Send('Enter any string here...');

    Send('You can even call more macros: %=mcMessage=%');
    end;
end;

Specialized Web Actions

There are over a dozen specialized web action components included with WebHub.  Each one does something different. You will see the components on the palette when you install in Delphi; and you can read about each one in this help file.

Integration of Static and Dynamic Pages

By using the BRANDFILE macro, you can link to and through static web pages without losing state.  That is essential if you have a public Internet site and you want to get in the search engines based on your static pages.

Running Live -- Middleware in Action

When you actually run your application, you are running an EXE built with the WebHub components, plus a WebHub runner and optionally the Hub.  The runner simply carries information between the web server and the Hub/your EXE.  The Hub serves as a process controller or "traffic cop."  The combined effect is called "middleware" -- software that is in the middle of a multi-tier architecture.  The web browser is the client, the web server plus the WebHub system is in the middle, and a database is typically on the back end.  This sort of multi-tiered architecture is becoming increasingly popular because (a) it's inherently fast, especially when using an EXE built with Delphi; (b) you can upgrade the software without changing anything on the client side; and (c) it scales well when you need to support more traffic.

Summary

The WebHub development paradigm has been proven since October 1995 to be exceptionally cost-effective for a wide variety of web sites.  The very simple ideas of object oriented design, saving-state on the server, using a SessionID to track surfers, and separating the user interface from the business rules have held up for two years marked by rapid change because WebHub's design follows principles much older than the web.  Invest in learning WebHub, and you will have the rewards of a high-performance, well organized, scalable web application that will work on any public Internet, internal Intranet, or corporate Extranet.


WebHub Lite Defined
WebHub Lite - Defined

WebHub Lite is a FREE subset of the full WebHub Components package.  It includes:

• All the components required to create generic application servers including aserver.exe.

• The essential WebHub demo projects: aserver.dpr, webapp.dpr and htmail.dpr

• W-HTML for over a dozen demos.

• The Hub, registered version, with a 1-exe capacity.

This means you can run 1 EXE per machine. You can put unlimited pages and features into that EXE.

• Permission to deploy on unlimited machines.

• Runners for cgi-win, cgi-bin and ISAPI

• WebHub Project Wizard

WebHub Lite is designed to be the perfect package for Delphi developers who want to get started with WebHub. Anything you build with WebHub Lite will be recompilable with the regular WebHub Components, under Delpih 2, 3, 4 or 5.

The Fine Print explains the limitations of WebHub Lite in contrast with the WebHub Components.  The one thing you really need to know in advance is that it does not include any database components, but it can still use any aspect of Delphi's database capabilities.

Additional FREE Downloads

• HTML Import Wizard, http://www.href.com/whtmlwiz

• WebHub Developer's Manual, http://www.href.com/whmanual

What you get in the WebHub Lite Add-Ins for $149

• Full source to tPack, over 50 units, as defined in your help file.

• Source to TWebLogin, TWebCycle and TWebDCom

What you get in the WebHub Component package for $295

• The ThtDBWebApp component which enables easy sending of W-HTML from a database, with optional caching.

• The rest of the WebHub components, including the database components (ThtDBWebApp, TWebDataGrid, TWebDataScan, TWebDataForm, TWebDataPoster, TWebDataSource, TWebDBAlphabet, TWebDBListBox,  TWebTable)

• Other special purpose web actions such as TWebDropDown, TWebPicture, TWebHTTP, TWebOutline, TWebScan and TWebVarsDelete.

• The rest of the demos

What you get in HtPlus Pack

• Full source to tPack, over 50 units, as defined in your help file.

• Full source to many other units, including the async classes for background task processing.  The full list of units is maintained at http://www.href.com/htplus.  New units are added over time.

Pricing Note: Because tPack is bundled with the WebHub Lite Add-Ins and with HtPlus Pack, the price for HtPlus Pack is $120 for WebHub Lite customers and $260 for WebHub Components customers.

What you get if you unlock your Hub Capacity for $425

The ability to run 5 EXEs on the same machine. Higher unlocks, including unlimited, are available.  For a worksheet on estimating your hub capacity requirements, see http://www.href.com/design1.  If you anticipate 10,000 or fewer page requests per day, the FREE 1 EXE capacity should be sufficient.

How to Order

Go to http://www.href.com and go into HREFShop.


The Fine Print
The Fine Print - What's Lite about WebHub Lite?

This document defines exactly what is "lite" about WebHub Lite.  Some of these topics are advanced in nature and will not be relevant until you have built one or two projects web applications and have the background necessary to understand the issues.

• WebHub Lite does not include any database components

This does not mean that you can't do any database processing!  Au contraire! Your application can still access any of the databases available to Delphi.  It's just that you don't have WebHub style components to make it easier.

The Lite version excludes the TWebDataGrid and TWebDataScan components for publishing HTML tables.  It excludes TWebDataPoster and the a series of virtual scan components for dealing with other types of lists of data.

The most powerful omitted capability is that of deep-cloning arbitrary datasets.  This is implemented by TWebDataSource in the regular WebHub Components.  Cloning makes it possible to easily exceed the Delphi/Midas limitations by providing cloned datasets for surfers.  Please note -- most beginners find this "cloning" area quite difficult and complicated -- that's part of why we omitted it from the Lite version.

• WebHub Lite excludes source to TWebLogin, TWebCycle or TWebDCom

Source to these and many other TWebAction components are included in the registered version of the WebHub Components.

• WebHub Lite prevents persistent connections to same EXE

This means you can not use some of the load balancing features of The Hub. In the free version, TWebApp.CgiUseHandle is not available as a property, and traffic will always route through The Hub to the least-busy instance of your EXE.

• WebHub Lite has approximately 10% slower parsing

The free version allocates memory for object-arrays on the fly rather than pre-allocating intelligent blocks. Thus the free version does not parse as efficiently.

• WebHub Lite uses only 5 digits for session numbers.

Session numbers will be in the range of 10000 through 99999.  On the surface, this might seem that your site will be slightly easier to hack, compared to having the full range of 10 digits available. To a certain degree, that might be so, but since WebHub includes a plethora of features enabling you to lock down session security (see the Security section in the manual), we don't really believe that you will be more vulnerable.  You will have to become more aware of the security features and implements events such as OnNewSession, OnBadIP and OnBadBrowser, but ideally everyone would do that.

• WebHub Lite omits the async thread classes for background processing

While you can license HtPlus Pack and receive source for the async classes, you can not use the Keep-Open-Connection logic that lets you send progress messages to dozens of users from a single EXE.  Therefore writing real-time JavaScript or other games will have to happen using full pages rather than streams.

• WebHub Lite omits support for binary streaming nor the SendFileIIS method

This means that you cannot send dynamically generated images or binary files from a secret URL. You can use temporary files to overcome the first restrictions if you write the code for that yourself.  What is restricted is the secure software delivery angle of WebHub.

• WebHub Lite does not support automatic file uploading

The ProcessUploadedFiles method which processes the incoming list of files (TWebServer.FormFiles) is omitted.


Understanding WebHub URLs

WebHub uses the URL in order to provide the save-state feature without relying on cookies.  Nonetheless, WebHub allows unlimited flexibility for your application's custom features.

Syntax

WebHub URLs use a standard set of four (4) parameters within the CGI Query String.

http://domain/path/runner?AppID:PageID:SessionID:OptionalCommand

Example: http://www.href.com/scripts/runisa.dll?hubapp:systeminfo:123456:arbitrary

AppID 	= Application ID (hubapp)
PageID 	= Web Page ID (systeminfo)
SessionID 	= Anonymous Surfer ID (123456)
OptionalCommand 	= Additional information for your application (arbitrary)

AppID

In the example above, the AppID is 'hubapp'.  The AppID identifies a web application.  Its presence in a URL tells WebHub which web application should serve the dynamic page request.

[? WebAppID setting ]

[? AppID property of TWebBasicApp]

PageID

In the example above, the PageID is 'systeminfo'.  The PageID identifies a web page within the AppID. Because WebHub pages are dynamic, it is possible to have one web page with dramatically different content at different times, and also possible to have multiple web pages that show the same content.  [? Page Syntax]

New surfers are always routed to the FrontDoor page if that is defined.  For returning surfers or when there is no Frontdoor, set the Homepage so that there is a default destination for surfers.  Invalid page requests are routed to InvalidPage, if defined.

SessionID

In the example above, the SessionID is '123456'.  The hub assigns a SessionID to each new surfer.  The number of digits in the SessionID ranges from 6 to 10, depending on the Digits setting.  The more digits, the more security.  You should also shorten your SessionLifeMinutes setting if you have more than 100,000 new surfers per day.

The SessionID relates directly to the TWhSession inside your custom EXE.  A copy of this object is instantiated for each new surfer, and the object is named based on the SessionID.  Session objects will be streamed to .var files on disk in the SessionsDir if TWebApp.ShareByFile is true (which it is, by default).  This enables you to share the session data among multiple EXEs.

Random SessionID

Sometimes you will see a suffix after the SessionID -- a period followed by a number. This comes from the TWebApp.Random property.  Its purpose is to create a "new" URL which the web browser can not cache.  See JUMP vs JUMPR and other 'R'andom macros.

OptionalCommand

In the example above, the OptionalCommand is 'arbitrary'.  This is where you put any alphanumeric data that you want to pass to your web application.  For example, from a feedback page you might pass 'webmailform.feedback' as the command so that the TWebMailForm component knows to use the 'feedback' settings when sending the e-mail message.

How to Link Into Your WebHub Application from a Static HTML Page

If you want to make a link into a WebHub page from a static page, do it like this:

http://www.href.com/scripts/runisa.dll?AppID:PageID

If you need to pass a command, use :: as a placeholder for the unknown sessionID:

http://www.href.com/scripts/runisa.dll?AppID:PageID::Command

Depending on your web server, you may be able to redirect your domain's home page to a dynamic page within your WebHub application, thereby bypassing the need for a static launch page.


WebAppID Setting

The WebAppID setting is configured once per machine. It tells the Hub which AppID to assume when none is given.  Use Components|WebInfo|Edit Defaults to set the value.

By setting the WebAppID to your most popular AppID, you can give out shorter URLs that only use the PageID and they will still resolve correctly.

To make subsequent links also avoid the AppID, set the TWebApp.CgiUseAppID property to FALSE.  This causes macros which build URLs dynamically (JUMP, ACTION, etc.) to avoid the AppID.

Example

Long form:	http://www.href.com/scripts/runisa.dll?HREFSITE:EVENTS

Short form:	http://www.href.com/scripts/runisa.dll?EVENTS


CGI Query String

The portion of the URL after the question mark ('?').  The query string is passed to the web application as a parameter telling it what to do.  The CGI Query String is standard throughout the web and is not particular to WebHub.

WebHub stores the CGI Query string in the TWebServer.CgiQueryString property.


FrontDoor Page

The purpose of the FrontDoor setting is to force new surfers to all enter through a single page in your application.  If you have a FrontDoor set, then no matter what PageID the person has bookmarked, they will be bounced automatically to the FrontDoor page.  This is one of the first steps you should take to increase security on your site.

Set the FrontDoor under AppID|Edit Defaults or on the HTML|Defaults panel.  There can only be one FrontDoor setting per AppID.

Example

FrontDoor = Login


Homepage Page

The purpose of the Homepage setting is to provide a default PageID within your application.  The Homepage applies if

• the surfer is returning and no PageID is given on the URL, or

• you have a new surfer and no FrontDoor is defined

Set the Homepage under AppID|Edit Defaults or on the HTML|Defaults panel.  There can only be one Homepage setting per AppID.

Example

Homepage = Login


InvalidPage Page

The purpose of the InvalidPage setting is to define where surfers will go if they request an invalid page.  If you do not define your own InvalidPage then surfers will see WebHub's default message about an invalid PageID.

Set the InvalidPage under AppID|Edit Defaults or on the HTML|Defaults panel.  There can only be one InvalidPage setting per AppID.

Example

InvalidPage = ErrorPageID


Documentation Style Conventions
Documentation Conventions

• The ? symbol means For more information, search for this topic in the WebHub Help File.  For example, [? Technical Support] means "for more information, search for "Technical Support."

• The c:\ht\ directory is the default root for HREF Tools installation.  You can install WebHub on any drive, in any directory.  As you follow the documentation, substitute your path as necessary.

• The c:\htdocs\ directory is the default root for WebHub's Hyper Text document files.  This is also known as the "web root" or the "wwwroot" directory.


Installing a Web Server

WebHub runs with all popular web servers on the Windows platform.  There is a separate help file called WebServr.hlp which covers web server installation.  You will find webservr.hlp in the ht\doc\ directory, and on the web at http://www.href.com/pub/docsnhelp/.


Testing the WebHub Installation

1. Test your web server

Be sure your web server is running.  Then try the following URL from your web browser:

http://localhost/

In all examples, substitute your own domain name or IP number for the word "localhost".  For example, you might test http://127.0.0.1/ or http://www.mydomain.com/

2. Test the /htdemo/ index page

This following web page has been set up to guide you through a series of tests, from which you can determine what needs attention.

http://localhost/htdemo/index.htm

This file installs as c:\htdocs\htdemo\index.htm by default.  If it does not work, see the Web Server Help File for assistance in configuring the /htdemo/ mapping on your web server.

Summary of Tests within the /htdemo/ index page

  http://localhost/path/runner?echo

e.g. http://localhost/scripts/runisa.dll?echo

http://localhost/path/runner?hubapp:systeminfo

http://localhost/path/runner?BW

http://localhost/path/runner?YourCustomAppID


Installing Components in Delphi
Installing WebHub Components in Delphi

This instructions apply to WebHub v1.46+.  If you have an earlier version, read this.

Delphi 3, 4 and 5

During installation of the WebHub VCL, the DCUs will be installed on your system.  The package files ("DPL" and "DCP") will either be immediately installed, or compiled during installation for you.  (Yes!)  When you next open Delphi, you will have the necessary packages automatically installed.

The packages are installed to the c:\ht\pkg directory.  See ht\pkg\read-pkg.pas for further detail on ways to optimize your deployed applications.

## means your version of Delphi, e.g. 30, 40 or 50.

Package Name	Purpose
WHub##	Most of WebHub!
WHubDB##	The parts that are dependent on the Borland Database Engine.
WHDemo##	Used in demos only.
WhLite##	WebHub Lite.

If you want to build projects with packages, set that under Project|Options.

Delphi 2

Component|Install the following:

c:\ht\lib32\regtpack.pas

c:\ht\lib32\reghref.pas

If you want to work with the Fish Store demo, repeat the procedure for the ht\htdemos\register\regapps.pas file.


Installing Older Components in Delphi

Delphi 3

File|Open c:\ht\pkg\webhub.dpk

Make sure the Global path includes your \ht\lib32 and \ht\pkg directories.

Compile + Install the webhub package.

If you want to work with the Fish Store demo, repeat the procedure for the ht\pkg\whdemos.dpk package.

Delphi 2

Component|Install the following:

c:\ht\lib32\regtpack.pas

c:\ht\lib32\reghref.pas

If you want to work with the Fish Store demo, Component|Install ht\htdemos\register\regapps.pas.


Defining a WebHub AppID

You need an AppID for each WebHub application that you build.  The AppID is a short phrase that will identify your application.  It can be easily changed later, but you must set one up.

Creating an AppID from the Hub

1. On the Hub, go to the Connected|Edit Setups Panel.  Add one new entry with the first 3 columns filled out:

AppID	Application ID.  Example: TEST

Directory	A directory path.  (Where your .ini and .htm files will live.)  Example: c:\ht\apps\test

Ini filename	The name of your configuration file.   Example: test.ini

In WebHub v1.10+ the Connected|Edit Setups panel has a shortcut for step 1.  Use the [New AppID] toolbar button, or right-click and choose New Setup.  To find the toolbar button, look for the hint which says "Create a blank INI file for a new AppID" and follow the prompts.

2. Click [Save] to save your changes.  You should see your new AppID on the Connected|Setups Panel.

3.  Make sure the referenced INI file exists!  Create an empty one if you have to.  WebHub requires a valid AppID and an existing INI file for each application.

4.  If you had a WebHub project open in Delphi while you did this, select the TWebInfo component, right-click and Refresh to alert it to the presence of the new definition.  Then, select your TWebApp component, set its AppID property to your new AppID.  You should see the IniFilename property fill in based on your definition.  Then right-click and Refresh to fully update the TWebApp component.

Alternative -- Creating an AppID from inside the Delphi IDE

1. Select the TWebInfo component. Right-click and choose Edit Setups.  Add a new entry as shown above in step 1.

2. Click [Ok] to close the dialog box and save your changes.

3. Select the TWebApp component.  Use the Object Inspector to set the TWebApp.AppID property to match the new AppID.  Then right-click the component, and Refresh.

4.  Make sure the referenced INI file exists!  The quickest way to check is to select the TWebApp, right-click and Edit INI File.  If that does not work, either the AppID definition is wrong, or the INI file does not exist.  Create an empty one if necessary.

5. If you had the Hub running while you did this, use Components|WebInfo|Refresh to alert the Hub to the presence of the new AppID.  You should then see it on the Connected|Setups panel.

See also: Understanding WebHub URLs


Working with HTML Files

Prerequisite: AppID set up

Choosing your Editor

Depending on which product you licensed, you may have a choice of HTML editors.  For example, if you have licensed both the VCL and the Hub, you can use either the Hub (hub.exe) or the HTML panel in a custom EXE.  You will get the same HTML editing features either way. If you know which one you want to use, skip ahead to that section below.

Advantages to using the Hub: It already exists! Many Delphi programmers use the Hub "as an editor" while they are first setting up their application.  Once the AppID and a few pages are defined, they do the rest of the work in their custom EXE.

Disadvantages to using the Hub: It can only run one AppID at a time (see HubAppID Setting).  You may find yourself switching the HubApp a lot, which is perfectly ok so long as you remain aware of which one you are currently using.

Advantages to using a separate EXE: You can leave the HubAppID set to HubApp and pretty much ignore the Hub.

Disadvantages to using a separate EXE: The user interface is hidden; you have to learn the steps.

Using the Hub

1. Make sure the Hub is running your AppID.

2. Go to the HTML|Files Panel.

3. If you need instructions and tips on using the HTML editor, please click here for help with the HTML|Files Panel.

Once you have your AppID set up, use it.  If you're using the Hub, go to the Hub's Setup Panel. Select your AppID.  Right-click and choose Default HubApp.  That will permanently load your AppID into the Hub.  If you're writing a custom web application, set the TWebApp.AppID property to your AppID.  Make sure you use the whHTML.pas unit in your project so that you have the HTML editor interface available.

Using a different built-with-WebHub EXE as your editor

1. Make sure the program is running your AppID. Use AppID|Pick AppID to change AppIDs if necessary.

2. Go to the HTML|Files Panel.  This may be the only panel in the application.  The tab should be labelled HTML.

3. If you need instructions and tips on using the HTML editor, please click here for help with the HTML|Files Panel.

From inside the Delphi IDE

1. Build a basic WebHub application, either by using the wizard or from scratch.

2. Use the Object Inspector to make sure TWebApp.AppID is set to your AppID.

3. Select the TWebApp, right-click, choose Refresh.  Verify that the IniFilename shows properly.

4. Select the TWebApp, right-click, choose Edit Files.  This gives you the same HTML editor as you would have using either of the techniques above.


Creating a new Application with the WebHub Wizard
Creating a new Delphi Application with the WebHub Wizard

General Background Information about the Wizard

WebHub v1.1+ includes a wizard for creating new projects and new forms, for use with Delphi 3, 4 and 5.  The wizard operates in two modes: New-Project and New-Form.

The New-Project Wizard is a general-purpose tool for building projects out of reusable forms.  The New-Form Wizard helps you quickly add any of the reusable WebHub panels to your current project.
All files install to the ht\wizard directory:

WhWizard.dll	This DLL contains the code for the wizard.
WhWizard.reg	This defines the project styles and requirements.

The WhWizard.reg file contains the rules for the wizard in the form of an ASCII text file which, when run, loads up the HKEY_CURRENT_USER\Software\HREF Tools\WebHub\Project Wizard registry entry.

The rules are expressed as unit descriptions, and likely combinations.  Advanced users may want to add their own units and project styles.  The easiest way to do this is to edit the .reg file and then run it again to update the registry.

The wizard knows where to find the units based on a setting in WhWizard.reg. The defaults are ht\lib32 and ht\htfrm.  These are updated during installation to match your setup.
Using the Wizard to Create a New Application

Select File|New|Project|WebHub Application.  Select a project style and choose your options.  The wizard will create the project for you.

If you are new to WebHub and enjoy seeing as many features as quickly as possible, select the "FULL" project option, and add in at least one of the following optional panels: SendStr, DataScan, DataGrid or ScrolQry.

If you are new to WebHub and want to start cautiously, select the "BASIC" project option and add in the SendStr unit.

Using the Wizard to Add in a WebHub Panel

Select File|New|Form|WebHub Form.  Select your panel.

Known Problems & Restrictions

If the wizard does not work, the most likely reason is that you had Delphi running while you installed WebHub. In that case, just exit Delphi, install the .reg files manually, and then restart Delphi.

You may get multiple GPFs in a row in the Forms Wizard when viewing the DPR and adding inherited forms that are not auto-created. These come from Delphi itself. To avoid them, have the Forms Wizard AutoCreate inherited forms.

There seems to be a limit of three forms inherited per project in the Project Expert. The program will alert you to the condition and explain a manual way to continue - you need to open and close the DFM so that Delphi will update the Uses clause.

Wizard Credits

• Jerry Coffee for publishing Ray Lischner's Book on the Open Tools API.
• Ray Lischner for writing the book and leaving enough juicy bits unexplained.
• Anders H. and the Borland Team for producing Delphi in the first place.

• Michael Ax at HREF for writing the Delphi 3 wizard.

• Christian Bøhn, student, for converting the Delphi 3 WebHub Wizard to Delphi 4.

Updated 3-Aug-1999


Application Defaults

Application defaults are values that are set for the application as a whole, and apply to all surfers equally.  They are saved in the Defaults property of the TWebApp object. WebHub has a number of built-in application defaults which you can see on the HTML|Defaults panel.  You can also add your own application defaults, which are then referenced with the AppDefault macro or pWebApp.AppDefault['keyword'] in Delphi.

See also:

[? HTML|Defaults panel]

[? Defaults Property of TWebApp]


Page Syntax
WebHub Page Syntax

A certain syntax is used to define a WebHub page. Whereas standard HTML pages are defined one-per-file, in WebHub you can have multiple pages defined in the same file.  The Page definition is used to set certain properties of the page, such as the description.

<h1>-Page:PageID=[PageDestination],[ExportFilename],[AdditionalTags],[PageDescription]</h1>

HTML for page goes here.

PageID: use any short alphanumeric phrase. Do not use a word you have used as a filename. Do not use underscores or spaces.  While you can create a PageID that is completely numeric, that is not recommended because it will only work if you include the AppID in every JUMP.

PageDestination: leave blank unless you want to set up PageAliases.  [? PageDestination Property of TWebBasicPage ]

ExportFilename: leave blank unless you want to export the file to a static page.  [? ExportFilename Property]

AdditionalTags: leave blank unless you want to specify a frame target.  [? TWebAppPagesList Class]

PageDescription: fill this in to associate a title with your web page.  This information will be available as %=PageDesc=%.

The end of a page definition is marked by either the beginning of the next definition, the end of the file, or the MacroEndBuffer as defined under AppID|Edit Defaults.

Insert Markup

Use the Insert Markup feature in the HTML editor to have page syntax typed in automatically for you.  In the editor, right-click for the menu.

Example showing just PageID

This is the simplest syntax:

<h1>-Page:InBrief</h1>
<h2>WebHub is a</h2>
component-based web application development framework

Example Showing Page Description

This is the more common style, with the page description added.  Although the triple commas are not required, they are recommended as a placeholder for the other options (export filename and special page attributes).

<h1>-Page:InBrief=,,,WebHub In Brief</h1>
<h2>WebHub is a</h2>
component-based web application development framework

Example Showing 2 Pages; Form submission links to 2nd page

<h1>-Page:homepage=,,,here's the PageDescription</h1>
<FORM METHOD=POST ACTION="%=ACTION|hello=%">
Hi, welcome to my web site. Please enter your name.
<INPUT TYPE=TEXT NAME=UserName VALUE="%=UserName=%">
<p>
<INPUT TYPE=SUBMIT VALUE="Click to continue">
</FORM>

<h1>-Page:hello=,,,Hello by Name</h1>
Hello there, %=UserName=%.


Chunk Syntax
WebHub Chunk Syntax

<h1>-Chunk:ChunkID</h1>

HTML for chunk goes here.

The 'ch' prefix on ChunkIDs is an optional naming convention.

The end of a chunk is marked by either the beginning of the next definition, the end of the file, or the MacroEndBuffer as defined under AppID|Edit Defaults. [? Configurable Chunk Syntax]

Example

This example defines a chunk with the ID 'chAddress'.

To include this chunk on another page, type %=chAddress=% wherever you want the chunk dynamically inserted.

<h1>-Chunk:chAddress</h1>
<ADDRESS>
<HR><A HREF="mailto:webmaster@href.com">Webmaster</A>
</ADDRESS>

Example for page headers and footers

The default names for these chunks are chPageHeader and chPageFooter. Configure that under AppID|Edit Defaults.

<h1>-Chunk:chPageHeader</h1>
<HTML><HEAD><TITLE>%=PageDesc=%</TITLE></HEAD>
<BODY>

<h1>-Chunk:chPageFooter</h1>
<hr>
%=GO|homepage|Home=% %=GO|Hello|Hello=%
<hr>
Debug Information:<BR>
%=Literals=%<P>
%=webserver.cgivalues=%
<hr>

See also:

Using Comments


Chunk Syntax Configuration
Configurable Syntax for WebHub Chunks, Pages and Macros

The syntax for defining pages and chunks is configurable.  It is set under AppID|Edit Defaults.  The information shown below is the default.

[TWebApp.Defaults]
MacroPageBegin=<h1>-Page:
MacroChunkBegin=<h1>-Chunk:
MacroEndMarker=</h1>
MacroEndBuffer=<!-- ****
MacroSectionBegin=<h1>-Macros

You may change any of these syntax tags. The change effects only those projects which use the particular INI file containing the change.


Macro Syntax
WebHub Text Substitution Macro Syntax

Text substitution macro definitions must fit on one line. Use a chunk if you need more space.

<h1>-Macros</h1>

MacroID=MacroDefinition

The 'mc' prefix on MacroIDs is an optional naming convention.

Examples

<h1>-Macros</h1>

mcBody=<BODY bgcolor="#FFFFFF">

mcHotGif=<IMG SRC=/planet/gif/hot.gif alt="hot!" BORDER=0>

mcNewGif=<IMG SRC=/planet/gif/new.gif alt="new!" BORDER=0>

//

mcDemoDivider=<p><CENTER><IMG SRC=/planet/gif/bar3.gif></CENTER><p>

mcDemoHeadFontON=<FONT COLOR="BLUE">

Edit Macros Verb

You can also define macros using AppID|Edit Macros.  Those definitions are stored in the application-level INI file and take precedence over those defined in chunk files.  Using the -Macros tag is usually preferable because the HTML chunk file can be shared across projects.

See Also:

Using Comments

Built-In WebHub Macros

Version Notes

The W-HTML parser changed at v1.640, enabling much greater nesting of macros within W-HTML.

As of v1.650, comments are supported within Macro definition sections in W-HTML.


Using Comments

Comments in W-HTML Files

W-HTML comments are enabled by setting TWebApp.whComments to True, which is the default setting.

Comments in a W-HTML file are lines that start with //, for example:

//This is a comment

For comments longer than one line, each line must start with '//'.

Comments and JavaScript

Lines that start with // and contain <!-- and --> all on the same line will be considered a comment and stripped out when sending the W-HTML.

Lines that start with // and contain --> without an opening <!-- will be ignored. That means they will not be considered WebHub comments.

Comments in INI files

Comments in an INI file take this form:

;This is a comment

Warning regarding comments in INI files: When WebHub rewrites sections of the INI file, your comments can get lost.  To preserve comments reliably, put them under a separate [comments section] that you invent for this purpose.

Version Notes

As of v1.650, comments are allowed within Macro definition sections, including lines that are just //.


Controlled HTML

"Controlled HTML" is purely a WebHub term.  Controlled HTML was used prior to the introduction of the INPUT macros (introduced in v. 1.460)   to monitor and modify HTML syntax within FORMs so that attributes like 'CHECKED' and 'SELECTED' can be added dynamically.  It was most commonly used with checkboxes, radio buttons, and select lists.  Controlled HTML can be used instead of the various INPUT macros, if desired.

Generally, HTML has no rules about line breaks.  However, when you are using controlled HTML, WebHub requires that everything from the leading %= to the closing > symbol be one a single line in the source file.

Example

<FORM METHOD=POST ACTION="%=where=%">

Radio button:

// controlled HTML is used here to save-state on the radio buttons.

%=<INPUT TYPE=RADIO NAME=R1 Value="Red">

%=<INPUT TYPE=RADIO NAME=R1 Value="Blue">

<INPUT TYPE=SUBMIT></FORM>

Example

Click here for a sample page that you can add to your WebHub application to test controlled-HTML.  Or see the FORM demo.

[? How Macros are Decoded ]

[? onHTMLControl event]


Controlled HTML Example

Copy this information into a file that is part of your WebHub application, and then request PageID 'testme'.

<h1>-Page:testme</h1>

<FORM METHOD=POST ACTION="%=where=%.CKB">

<hr>

// This example works when run inside hub.exe where the application object is named HubApp.

HubApp.CGIAPP is: %=HubApp.CGIAPP=%

<hr>

// Setting literal x...

%=SET|x=%=HubApp.CGIAPP=%=%

<hr>

x is: %=x=%

<hr>

// The rest of this will work in any dynamic WebHub application.

// note the variations on quotation marks, capitalization, spacing and order of the terms.

c1 %=<INPUT TYPE=CHECKBOX NAME="1name" Value="YES">label<br>

<hr>

c2 %=<INPUT TYPE= "CHECKBOX" NAME="2name" Value="YES">label<br>

<hr>

c3 %=<INPUT TYPE = "CHECKBOX"  NAME = 3name Value = YES >label<br>

<hr>

r1 %=<INPUT TYPE=RADIO NAME="radio" value="value1">label<br>

<hr>

r2 %=<INPUT TYPE=RADIO NAME="radio" value="value2">label<br>

<hr>

r3 %=<INPUT TYPE=RADIO NAME="radio" value="value3">label<br>

<hr>

A drop-down choice: %=<SELECT NAME="litWallpaper">

 %=<OPTION VALUE=""> None

 %=<OPTION VALUE="parch.gif"> Parchment

 %=<OPTION VALUE="pink.jpg"> Pink

 %=<OPTION VALUE="blucloud.jpg"> Clouds

 %=<OPTION VALUE="palace.jpg"> Palace

 %=<OPTION VALUE="hemlock.gif"> Hemlock

 </SELECT>

<hr>

<INPUT TYPE=TEXT NAME=name Value="%=name=%">

<hr>

<INPUT TYPE="SUBMIT">

</FORM>

Please note, as of v1.460, you can use the INPUTRADIO, INPUTCHECKBOX, etc. macros to set up these types of fields, and then you do not need to use controlled HTML.


Built-in WebHub Macros
Built-in WebHub Event Macros

Background Information

General Syntax Rules

Navigational and URL Event Macros and Related Properties.  -- About the 'R' suffix

CGIHTTP	Determines the use of an 'HTTP://' portion of all links.

DYNACTION	This forces a dynamic form-action going to the given PageID.

DYNJUMP	Use this to link to the dynamic version of a PageID, from an exported page.

FRAME	Use the FRAME macro when you want a shortcut for the FRAME SRC tag.

GO	Use the GO macro to create a link which will become inactive if pointing at the current page.

GOR	Same as GO; prevents browser caching.

HIDE	Use the HIDE macro to create a link which will become disappear if pointing at the current page.

HIDER	Same as HIDE; prevents browser caching.

HREF	Use the HREF macro to create a hypertext link to a non-WebHub resource.

JUMP 	Use the JUMP macro to create a link to a page within a WebHub application.

JUMPR	Same as JUMP; prevents browser caching.

MAILTO	Use the MAILTO macro to generate a mailto link.

MEDIA	Use this property for cycling media lists.  [? Media Property of TWebBasicApp]

STATICJUMP	Creates a jump to the static version of the page.

WHERE 	Use this property in a FORM ACTION to link to the current page.  [? Where Property of TWebSessionIDApp]

Macros for use within HTML Forms

ACTION	Use the ACTION macro in the <FORM> tag to define where control goes when the form is submitted.

ACTIONR	Same as ACTION; prevents browser caching.

INPUTCHECKBOX	creates INPUT TYPE=CHECKBOX tag.

INPUTFILE	creates syntax for uploading files to the web server.

INPUTFORM	creates syntax for beginning or end of FORM, depending on usage.

INPUTHIDDEN	creates INPUT TYPE=HIDDEN tag.

INPUTIMAGE	creates INPUT TYPE=IMAGE tag.

INPUTNUMBER	creates INPUT TYPE=NUMBER tag.

INPUTPASSWORD	creates INPUT TYPE=PASSWORD tag.

INPUTRADIO	creates INPUT TYPE=RADIO tag.

INPUTRESET	creates INPUT TYPE=RESET button tag.

INPUTSELECT	creates a SELECT tag (including multiple select) based on a list.

INPUTSELECTRADIO	creates a series of radio buttons based on a list.

INPUTSELECTCHECKBOX	creates a series of checkboxes based on a list.

INPUTSUBMIT	creates SUBMIT button tag.

INPUTTEXT	creates INPUT TYPE=TEXT tag.

INPUTTEXTAREA	creates TEXTAREA tag.

Branding Macros

BRANDFILE	Displays a static HTML file, with links expanded to preserve state.

BRANDJUMP	Creates a JUMP to the branded version of the PageID.

Event Macros Which Change the PageID Dynamically

BOUNCE	Use this macro to bounce the user to another page using HTTP redirection.

HUBAPP	Use this to remotely change the App being served by the Hub.

JUMPBACK	Use this to jump back to the prior AppID and PageID as defined on TWhSession.

PAGE	Use the PAGE macro to switch the surfer to a different page.

POPPAGE	Use this macro when you want to bounce the surfer to the PageID which was already stored in the named Literal.

PUSHPRIOR	Use the PUSHPRIOR macro in conjunction with POPPAGE to implement pages or sequences that act as subroutines.

PUSHTHIS	Use the PUSHTHIS macro in conjunction with POPPAGE to implement pages or sequences that act as subroutines.

Action Event Macros

Action macros, as opposed to WebAction Components, have no visible output and do something affecting the entire document.

CLOSE	Closes the file and ends the page right there.

EXCEPT 	Terminates production of the page with an errormessage.

FLUSH	Clears (resets) the output document.

Database Macros

DBEDIT	Creates an input box for a field.

FIELD	Displays the contents of a named field for the current record.

HTTP-Header and Page-Summary Event Macros

COOKIE	Use the Cookie macro to send cookies to the surfer.

EXPIRES	Use the EXPIRES macro to tell the web browser when to invalidate the cached copy of the web page.

HEADER	Use this macro to add a line to the HTTP header which is sent out as a prefix to the dynamic web page.

PROLOGUE	Replaces the document's prologue to match the requested type.

SUMMARY	This adds text to the WebHub page footer (after all sections are sent).

Conditional Event Macros

ASSIGNED,NOTASSIGNED

Show the VisiblePhrase if a Literal or Checked form variable has been set (or not).

CMDHAS	Sends a chunk if the WebHub OptionalCommand contains the given phrase.

IF, IFNOT	Use these macros to conditionally display a phrase based on a checkbox setting.

IFDYNAMIC	Sends the phrase if you are making a dynamic HTML page.

IFSTATIC	Sends the phrase if you are making a static HTML file.

MATCH, NOMATCH	Use these macros to conditionally display information based on a string.

REQUIRES	Requires the named literal or checkbox.

Data-Changing Event Macros

APPDEFAULT	Sets an application default.

CHECK	Sets a single boolean variable to true.

CLEAR	Use this macro to remove a Literal or Checked item from the list kept on TWhSession for the current surfer.

PAGEDEFAULT	Sets a page default.

REFRESH	Refreshes the TWebApp component so it loads new HTML files from disk..

SET	Use the SET macro to set the value of a Literal.

TOGGLE	Toggles the value of the named Checkbox between True and False.

File-Processing Event Macros

ANCHOR	Remember a position by name, and substitute content into that place later.

EMBED	Use this macro to embed a VRML file.

EMBEDR	Same as EMBED, but prevents web browser caching.

FILELINK	Sends a link to a file, presumably a dynamically-created file.

INCLUDE	Use this macro when you want to include an entire text file on a page.

SENDFILE	Use this macro when you want the dynamic response document to consist of a single file, and you want to hide the file location from the surfer.

See also: INPUTFILE

Event Macros for Documentation

CMD	Use this macro to display a chunk based on the Command from the URL.

SOURCE	Use this macro to display the WebHub HTML source behind a chunk, for training purposes.

JavaScript Shortcut Event Macros

CHUNKID	Sends the current ChunkID.

JS	Creates an A HREF link which calls a JavaScript function.

Event Macros for Links to External Programs

COM	Use this macro to call a COM program.

SHELL	Use this macro to run another program and wait for it to finish.

START	Use this macro to start an external program.

Event Macros for Security / Session Control

ASSERTPROTOCOL	Force the use of a certain protocol such as HTTPS.

IFINACTIVEFORSEC	Do something if the session is inactive for N seconds.

SESSION	Controls the session file's date/time stamp.

Macros for Optimizing Almost-Exactly Repetitive Chunks

CRUNCHKEYS	Rename literals in a named set so there are no gaps.

INC	Increment a literal that contains an integer (add 1 to the value).

DELKEYS	Delete literals whose name is based on a pattern ending in a number.

DYNCHUNK	Send a chunk whose name is calculated dynamically.

LIT	Return the value of a numbered literal.

PARAMS	Send a chunk, passing parameters that may be used within the chunk.


Macros, Background Information
Background Information on Event Macros

The built-in event macros are expanded by a web application object, i.e. TWebApp or one of its descendants.  Each macro is listed in this help file, along with the name of the component which implements it.  Note the component name responsible for the macro, because full Pascal source is available to the ThtWebApp and ThtDBWebApp components.

EventMacros differ from simple text-substitution macros in that they always contain at least one vertical bar '|' to separate even a hypothetical parameter from the macro keyword. Along with the %= and =% tags, that rule was chosen as it yields performance advantages.

See also: How macros are decoded


General Syntax Rules
Syntax Rules for Event Macros

Event Macros take the form:

%=<MacroID>|<Term>[|<OptionalTerms>]=%

Terms shown in square brackets are optional.

Some 	terms are comma-separated lists of items.  Many terms include 'key=value' pairs. In such cases, values are often run through the internal CompareTo function and thereby translated on the fly.

Event macros can include other macros, but infinite recursion is not supported. Expressions using built-in macros (e.g. JUMP) can nest no more than 3 macros and must be on a single line.

Example

%=SET|x=%=HubApp.CGIAPP=%=%

Here the literal 'x' is set equal to the expression HubApp.CgiApp.


CompareTo Function

CompareTo is the name of a built-in function which lets you refer to and access a subset of the values available by macro expansion. Here is what is "compared-to" when the method is run, in order of precedence, with an example of each:

• core-properties (Appid, TheAppid, Pageid, Session, Command, ChunkID, PriorPageID)

%=theappid=%

• WebSession.Literals	%=inLastname=%

• WebApp.Macros	%=mcImageDirectory=%

• WebPage.Defaults	%=pagedefault.security=%

• WebApp.Defaults	%=appdefault.salesrep=%

• WebServer.Cookies	%=cookie.chocolate=%

• WebSession.TextAreas	%=txtMessage=%

• Web Action components	%=webmailform.execute=%

• Component.property	%=webinfo.version=%

Version Notes

The above list is correct for v1.39+.


ACTION Macro

Use the ACTION macro in the <FORM> tag to define where control goes when the form is submitted.

Syntax

1. ACTION|PageID

2. ACTION|[AppID:]PageID

3. ACTION|[AppID:]PageID,Command

4. ACTION|[AppID:]PageID[(ServerID)]

5. ACTION|PageID,<comma separated list of commands>

Example

Use the ACTION macro in your HTML forms to link to a WebHub page, e.g.

<FORM METHOD=POST ACTION="%=action|feedbackpost=%">

Example for use with Forms that Post Checkboxes

<FORM ACTION="%=ACTION|feedback,.CKB=%" METHOD=POST>

Example for use with Frames

The ACTION macro does not generate any quotation marks. It does not support an embedded request for a frame target.  To specify a frame target, use it like this:

<FORM ACTION="%=ACTION|pageid=%" Target="_top" METHOD=POST>

See the .KEEPCKB command for use with FrameSets.

Example in Client Side ImageMap

The ACTION macro is ideal for use inside IMAGEMAPs:

<h1>-Chunk:chGridImagemap</h1>
<p>
<IMG SRC=/planet/gif/gridbtns.jpg USEMAP="#Grid Buttons" ISMAP>
<MAP NAME="Grid Buttons">
<!-- #$-:Image Map file created by Map THIS! -->
<!-- #$-:Map THIS! free image map editor by Todd C. Wilson -->
<!-- #$-:Please do not edit lines starting with "#$" -->
<!-- #$VERSION:1.20 -->
<!-- #$AUTHOR:unknown -->
<!-- #$DATE:Thu Dec 19 21:26:22 1996 -->
<!-- #$PATH:E:\htdocs\planet\GIF\ -->
<!-- #$GIF:gridbtns.jpg -->
<AREA SHAPE=RECT COORDS="2,0,53,42" HREF="%=ACTION|PageA">
<AREA SHAPE=RECT COORDS="53,2,105,42" HREF="%=ACTION|PageB">
<AREA SHAPE=default HREF="%=ACTION|homepage">
</MAP>

Implemented by

TWebApp

See also:

ACTIONR macro

Built-in WebHub Event Macros


ACTIONR Macro

Use this instead of ACTION when you want to be sure that the web browser can not cache the target page.  RandomSession is used instead of Session.

Implemented by

TWebApp

See also:

Built-in WebHub Event Macros


.CKB and .KEEPCKB Commands

If you want WebHub to save-state on your checkboxes, do two things on your forms.

1. Use the command .CKB in your form ACTION, e.g.

<FORM METHOD=POST ACTION="%=ACTION|feedback,.CKB=%">

2. Use controlled HTML syntax (leading %=) for your checkboxes, e.g.

%=<INPUT TYPE=CHECKBOX NAME="aCheckbox" VALUE="Yes">

Step #2 ensures that WebHub will set up a Pending array of your outgoing checkboxes.  Step #1 ensures that when the data is posted, the values will be compared against the Pending list, and all Pending variables will be set True or False appropriately.  This is essential only when you are generating checkbox names dynamically.

The leading dot in '.CKB' is new in v1.39.  Its purpose is to keep the command from going to other components that may be executed on your web page.

If you are using a FRAMESET, the Pending list can be damaged due to the unpredictable order that the frames are created in.  To compensate for this, use the .KEEPCKB command on the other frame(s).

Example

<FRAMESET ROWS="40%,60%">
  %=FRAME|search|cat=%
  %=FRAME|intro,.keepckb|files=%
</FRAMESET>

The .KEEPCKB command is new in v1.39.


ANCHOR Macro

Use this macro to define anchors, and to add text to anchors. An anchor is a named position in a WebHub page.  Once the position is set up, you can later add content (retroactively) into that position. You might use this to mark the spot in the page header where META tags go, and then later in the page body add the content to that position.  It also applies for JavaScript - and any situation where you want to mark a position and then fill it "later."

Syntax

1. ANCHOR|AnchorName

2. ANCHOR|AnchorName[,RequiredAnchor]

3. ANCHOR|AnchorName|text to add to the anchor

4. ANCHOR|AnchorName[,AnchorCMD]|text to add to the anchor

Syntax 1 defines an anchor, for example:

%=ANCHOR|metatags=%

Syntax 2 defines an anchor which will only be sent if the RequiredAnchor is non-blank, for example:

%=ANCHOR|metatags,anchorB=%

In the case above, the metatags anchor is only expanded and sent if anchorB has some content of its own.

Syntax 3 is used to add content to an anchor. The content can be regular HTML or it can contain WebHub macro syntax.

Example

%=ANCHOR|metatags|<meta name="Keywords" content="delphi,cgi,isapi">=%

Syntax 4 adds Anchor Commands, "unique", "replace" and "remove" :

unique	add the new text to the anchor if it's not already part of it, else ignore.

replace	replace the entire anchor with the given new text

remove	remove the new text from the anchor if there is a match (i.e. if found)

Example for filling in a Graphic within a generic Page Header

Let's say you want to make a generic chPageHeader with a graphic that is used each time, but you want to choose the name of the graphic "after" the header has been rendered.  Set up chunks like this:

<h1>-Chunk:chPageHeader</h1>

// generic page header

<HEAD><TITLE>%=PageDesc=%</TITLE>

<BODY bgcolor="#FFFFFF">

<center>

// set aside a spot named anch_banner, to be filled in later.

<img src="/%=ANCHOR|anch_banner=%" border=0>

</center>

<table>

<tr><td valign=top>

// some speedbar here

</td>

<td valign=top>

<h1>-Page:mission=,,,mission page for the site</h1>

// define the name of the graphic for the homepage

%=ANCHOR|anch_banner|thegreatest.jpg=%

Here is the site's mission statement....

</td>

<h1>-Page:homepage=,,,home page for the site</h1>

// define the name of the graphic for the homepage

%=ANCHOR|anch_banner|homepage.jpg=%

Here is some more text for the site....

</td>

<h1>-Chunk:chPageFooter</h1>

// generic page footer

</td></tr></table>

%=chCopyright=%</body></html>

<h1>-Chunk:chCopyright</h1>

<hr>Copyright &copy; 1998 HREF Tools Corp.

Example Showing Nested Anchors

Use nested anchors when you want to separate the page layout from the calculation of the contents, especially when the contents might be "empty" and necessitate removing a whole section of HTML.  An example might be an order form, where the look is very different if no items have been ordered. You could use a nested anchor, with a dependency as shown below, to make sure that the anchor-content was not even sent unless it applied.  VCL programmers, please note that you can access and further control anchors from Object Pascal.

<h1>-chunk:chJSshell</h1>
//define a nested anchor for sections that have formatting after the end of the anchor text
<script language="JavaScript">
%=Anchor|jscode=%
</script>

<h1>-chunk:js1</h1>

<!--
document.write("Example js1 function.")
//-->

<h1>-chunk:js2</h1>
<!--
document.write("Example js2 function.")
//-->

<h1>-Page:AnchorDemo</h1>
<html>

<head>
<title>
%=pageid=%
</title>
</head>
//Define the anchor to 'anticipate the use of javascript'
%=Anchor|js,jscode=%
//and give it some data. You must do this in two steps.
//Parameters are macro-expanded when this is processed, after the page is done.
%=Anchor|js|%=chJSshell=%=%
<body>
//The anchorjs chunk defines a nested anchor jscode
//define the contents of the jscode anchor
//you can add references to multiple chunks of javascript here.
//
//For nested anchors, you 'pre-load' the anchors and the contents
//will be processed when the anchor is defined later on.
//In programming speak this would be a 'forward declaration of
//an implementation'. When defined later, the anchor's text
//is sent and macro expanded.
%=Anchor|jscode|%=js1=%=%
//one can add to an anchor at any time during a page.
<b>example</b><br>
%=Anchor|jscode|%=js2=%=%
%=Anchor|jscode,unique|%=js2=%=%

// This section just shows some MATCH macro ideas.

<b>Your Browser's short-name is %=Browser.ShortName=%</b>
%=MATCH|Browser.ShortName=Mozilla4|True Moz4=%
%=MATCH|Browser.MozLevel!4|MozLevel4=%
%=MATCH|Browser.MozLevel!4|%=Anchor|jscode|  %=Browser.ShortName=%  =%=%

//When do you need a nested anchor?? when you want to insure that
//you control what goes after the elements that you nest.. like the </script> in this js example.

// This section shows some error handling. Nothing "bad" will happen

// even though the macro is defined twice.
%=Anchor|js,jscode=%
//and try to give it some more data...
%=Anchor|js|%=chJSshell=%=%
// Once an anchor is defined, defining it again will CLOSE the anchor

// so that it does not accept any new text.

//done anchoring, continue with HTML as usual...

See also:	Built-in WebHub Event Macros


APPDEFAULT Macro

Sets an application default from WebHub-HTML (rather than from the application-level INI file).

Syntax

APPDEFAULT|key=value

Note that you can display any AppDefault value using %=AppDefault.Key=%, e.g. to display the FrontDoor setting, use %=AppDefault.Frontdoor=%.


ASSERTPROTOCOL Macro

Use this macro to force a page to be delivered on HTTP or HTTPS.

Syntax

ASSERTPROTOCOL|HTTPS

This allows for easier integration of WebHub driven forms that need to be on HTTPS but are accessed by means of an http-only capable load-balancing device, such as the Cisco Local Director. Ordinarily one could simply make all jumps go to the secure server, but with a load-balancer in the loop and the certificate belonging to the machine, one needs the ability to switch ports once one has arrived on a data-entry page.

Use this in conjunction with setting the CgiHTTP property to the URL for the load-balancer.

This works with hardware load balancers such as the Cisco router, or with WebHub's Maitre d'Hub feature.

Example

// add this line at the top of a page to switch it to HTTPS if it's not already running on HTTPS

%=ASSERTPROTOCOL|HTTPS=%

See also:

Built-in WebHub Event Macros

This macro is available as of v1.45+.


ASSIGNED, NOTASSIGNED Macros

The ASSIGNED macro shows or expands the VisiblePhrase if the Literal variable has been set.  The NOTASSIGNED macro tests for a blank Literal.

Syntax

ASSIGNED|VarName|visiblePhrase[||elsePhrase]

• VarName	Name of Literal

• VisiblePhrase	W-HTML to send if the condition is true.

• ElsePhrase	W-HTML to send if the condition is false (optional).

Literals are set when a surfer enters data into a form and submits it to a WebHub page.  They can also be set using the W-HTML SET Macro and using Pascal.

Example

%=NOTASSIGNED|inShipToCity|%=SET|errMsg=Please enter the city.=%=%

See also:

Built-in WebHub Event Macros


BOUNCE Macro

Use this macro to immediately bounce the user to another page using HTTP redirection (the LOCATION command).  The URL shown to the surfer will change.  Contrast this with the PAGE macro, which keeps control inside the current WebApp, does not change the URL, and is slightly faster.

Syntax

1. bounce|PageID

2. bounce|AppID:PageID

3. bounce|http://www.href.com/index.html

4. bounce|//LanServerName/index.html

5. bounce|%=macro=%

Syntax variation 5 is supported as of v1.34.  The macro expansion is done via CompareTo, so literals and macros are supported.

Advanced Example

<h1>-Macros</h1>

mcURL=%=cgiHttp=%%=cgiApp=%:homepage:%=Session=%:aCommand

<h1>-Page:BounceTest</h1>

// This will bounce the surfer to the 'homepage' on the current server, within the current App.

%=BOUNCE|%=mcURL=%=%

// %=BOUNCE|homepage,aCommand=%  would be equivalent.

This example works:

BOUNCE|HTTP://%=Command=%

See also:

[? WebOutput.SendBounceTo]


BRANDFILE Macro

Displays a static HTML file, with links expanded to preserve state.  Full macro expansion is performed.  Image Maps are supported. Branding goes beyond including pre-generated pages, server-side includes, macro expansion and refers to a specific technique owned by HREF Tools Corp that adds state to static sites.

For security reasons, all branded files must be located in the BrandDir directory, or below it.

Internally, BRANDFILE calls the TWebApp.BrandHTML method.

Syntax

1. BRANDFILE|Filename[|DefaultFile]

2. BRANDFILE|Command

Use syntax 2 to brand the file specified by the WebHub OptionalCommand parameter.

Implementation

Create a WebHub Page like this:

<h1>-Page:BRAND</h1>

%=FLUSH|=%
%=BRANDFILE|Command=%
%=CLOSE|=%

Use this page within a link like this:

http://www.href.com/iis/webhub.dll?AppID:BRAND:%=Session=%:filename.htm

Or use it with a JUMP macro:

%=JUMP|BRAND,filename.htm|VisiblePhrase=%

Version Release Notes

As of v1.39, BRNDFILE is no longer case sensitive.  As of v1.45 it supports subdirectories.  As of v1.497 it supports framesets.

[? BrandFile method]

[? BrandHtml method]


BrandDir Setting

BrandDir defaults to ExportDir.  To override this value, set BrandDir under AppID|Edit Defaults (HTML|Defaults Panel).

For security reasons, all branded files must be located in the BrandDir directory, or below it.

See Also: ExportURL Setting


BRANDJUMP Macro

Creates a JUMP to the branded version of the PageID.

Syntax

BrandJump|BrandPage,PageIDOrFileName[#<command>][|Tags]|VisiblePhrase

BrandPage: This is the PageID within your application that uses the BRANDFILE macro, e.g. BRAND or SHOWFILE.

PageIDorFilename: If the PageIdOfFileName parameter of the macro does not refer to a PageID with an exportfilename as defined in your application, the macro will pass the parameter as the filename to be branded.  Branded files must exist in or under the BrandDir.


CGIHTTP Macro

Use the CGIHTTP macro to control whether HTTP:// is included in the links on your web page, and if so, what it will equal.  Generally, the HTTP://domain/ is omitted to allow for quicker speed.  However, during export, branding, or in some cases when you are using a hardware load-balancer and secure certificates with a server cluster, it can be extremely advantageous to specify HTTP://domain.

Syntax

1. cgihttp|true

Sets TWebApp.CgiUseHTTP=true

2. cgihttp|false

Sets TWebApp.CgiUseHTTP=false

3. cgihttp|<any string>

Sets TWebApp.CgiUseHTTP=true and sets the CgiHTTP property to the given value.  'string' runs through CompareTo and so may reference a checkbox in special cases; usually one would parameterize with an appdefault from a page-header.

4. cgihttp|<blank string>

 sets CgiUseHTTP=false and Clears/Resets to the default, the CgiHTTP property

By using this macro you can make sure that JUMPs off a given page are directed to a specific domain. For example, let's say you have a Cisco Local Director for load balancing and you want to use HTTPS with secure certificates.  Furthermore, let's say that the surfer is currently on https://machine1.href.com and the secure certificate is tied to that machine name. If an ordering JUMP link is used, a security alert may be raised by the web browser - falsely - but nonetheless confusing to the surfer.  By using syntax 1 you will make all JUMPS include a complete http link to machine1 and avoid any alerts in the web browser.  As a side effect, you will bypass the Cisco Local Director by doing this.

Example

%=CGIHTTP|http://www.href.com/=%

See also: [? UseCGIHTTP Property of TWebApp]


CHECK Macro

Sets a single boolean variable to true. The data is stored in TWhSession.Checked, i.e. as a checkbox equivalent.

Syntax

Check|VarName

• VarName	Name of the checkbox to set to True.

See also:

Built-in WebHub Event Macros


CHUNKID Macro

Sends the current ChunkID.  This is only available while sending the chunk.

Syntax

ChunkID

Example

<H1>-Chunk:Home</H1>
onMouseOver = "rollOver('%=ChunkID=%',true)"
onMouseOut = "rollOver('%=ChunkID=%',false)"
onMouseDown = "rollPress('%=ChunkID=%',true)"
onMouseUp = "rollPress('%=ChunkID=%',false)"
onClick = "rollClick('%=ChunkID=%')">
<IMG NAME="%=ChunkID=%" SRC="%=mcImageDir=%%=ChunkID=%up.gif" WIDTH=50 HEIGHT=50 BORDER=0 ALT=%=ChunkID=%>

For Pascal programmers, use WebApp.CompareTo('ChunkId') or access WebApp.ChunkID. Remember -- ChunkID is only relevant while expanding chunks. It does not nest. It is temporary and best for the above purpose.


CLEAR Macro

Use this macro to remove a Literal or Checked item from the list kept on TWhSession for the current surfer.

Syntax

1. Clear|<comma seperated list of form variables to clear>

2. Clear|textarea.varName

Specify multiple variables by name, or use wildcards to remove groups of literals.  To clear a textarea, use the .textarea prefix (not case sensitive, v1.40+).

Examples

CLEAR|userpassword

CLEAR|lit*

CLEAR|ImagesOkFlag

CLEAR|textarea.txtMemo

CLEAR|cb_*,textarea.txtMemo

See also:

Built-in WebHub Event Macros


CLOSE Macro

Closes the file and ends the page right there.

Syntax

Close|

The '|' is required; any parameter is sent.

See also:

Built-in WebHub Event Macros


CMD Macro

Use this macro to display a chunk based on the Command.

Syntax

CMD|[asSource|asChunk]

• asSource	display the WebHub HTML source behind the chunk name.

• asChunk	display the WebHub HTML chunk, fully expanded (as usual).

In both cases, the chunk name comes from the Command on the URL.  The mode defaults to asSource.

Example

%=CMD|asSource=%

See also:

Built-in WebHub Event Macros


CMDHAS Macro
CMDHAS Macros

Sends a chunk if the WebHub OptionalCommand contains the given phrase.  v1.34+

Syntax

1. CMDHAS|string|chunkid[||elseChunkID]

• string	This is the phrase (text string) to check for inside the OptionalCommand.

• ChunkID	Chunk to send if the string is found.

• ElseChunkID	This phrase will be sent if the opposite of the condition is true.

Example

Here is a test chunk that you can use to see how it works.

<h1>-Page:TestCmdHas</h1>
%=JUMP|%=pageid=%,ok|request this page with 'ok' as the command=%<br>
%=JUMP|%=pageid=%,test|request this page with 'test' as the command=%<br>
%=JUMP|%=pageid=%,ok,test|request this page with 'ok,test' as the
command=%<br>
%=JUMP|%=pageid=%|request this page without a the command=%
<hr>
%=CMDHAS|ok|has ok<br>=%
%=CMDHAS|test|has test<br>=%
%=CMDHAS|ok|%=CMDHAS|test|has ok and test<br>=%=%

See also:

Built-in WebHub Event Macros

Understanding WebHub URLs


COOKIE Macro

Use the Cookie macro to send cookies to the surfer.

Syntax

Cookie|key[=value][,rootpath]|[expire][,domain][,secure]

• key	The key is used exactly as entered and may not contain a macro.  Required.

• value	The value may contain a macro. Required.

• rootpath	The path attribute is used to specify the subset of URLs in a domain for which the cookie is valid. If a cookie has already passed domain matching, then the pathname component of the URL is compared with the path attribute, and if there is a match, the cookie is considered valid and is sent along with the URL request. The path "/foo" would match  "/foobar" and "/foo/bar.html". The path "/" is the most general path.

If the path is not specified, it as assumed to be the same path as the document being described by the header which contains the cookie.

• expire	The expires attribute specifies a date string that defines the valid life time of that cookie. Once the expiration date has been reached, the cookie will no longer be stored or given out.  The date string passed in must conform to to ShortDateFormat so it can be evaluated by StrToDateTime/StrToDate.

The date string is formatted as:  DD-Mon-YY HH:MM:SS GMT

This is based on RFC 850, RFC 1036, and RFC 822, with the variations that the only legal time zone is GMT and the separators between the elements of the date must be dashes.

Expires is an optional attribute. If not specified, the cookie will expire when the user's session ends.

Note: There is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path attribute is set explicitly to "/" will be properly saved between sessions if they have an expires attribute.

In WebHub, specifying a value of -1 will cause the cookie to be deleted.

• domain	When searching the cookie list for valid cookies, a comparison of the domain attributes of the cookie is made with the Internet domain name of the host from which the URL will be fetched. If there is a tail match, then the cookie will go through path matching to see if it should be sent. "Tail matching" means that domain attribute is matched against the tail of the fully qualified domain name of the host. A domain attribute of "acme.com" would match host names "anvil.acme.com" as well as "shipping.crate.acme.com".

Only hosts within the specified domain can set a cookie for a domain and domains must have at least two (2) or three (3) periods in them to prevent domains of the form: ".com", ".edu", and "va.us". Any domain that fails within one of the seven special top level domains listed below only require two periods. Any other domain requires at least three. The seven special top level domains are: "COM", "EDU", "NET", "ORG", "GOV", "MIL", and "INT".

The default value of domain is the host name of the server which generated the cookie response.

• secure	If a cookie is marked secure, it will only be transmitted if the communications channel with the host is a secure one.  Currently this means that secure cookies will only be sent to HTTPS (HTTP over SSL) servers. If secure is not specified, a cookie is considered safe to be sent in the clear over unsecured channels.

Defining a Cookie - Examples

This example defines a cookie.  The cookie's name is "SessionCookie" and its value is "Tasty".

Cookie|SessionCookie=Tasty

This example clears the cookie by setting Expire to -1.

Cookie|TodaysCookie|-1

Displaying the Value of a Cookie - Example

This example displays the value of the cookie named x:

%=cookie.x=%

Testing the Value of a Cookie - Example

This example checks whether the cookie named x equals 'yes', and if so, runs the chunk called chCookieYes.

%=MATCH|cookie.x=yes|%=chCookieYes=%=%

See also:

Netscape Cookie Specification

[? TWebApp.AddCookie]

Built-in WebHub Event Macros


Cookie Specification

Cookies are quite useful when used for the right purpose, but they are NOT the appropriate technology for transmitting sensitive data! The pitfalls of Coookies can largely be avoided by using them only for the purposes for which they are best suited--transmission of data that has no need to be protected.

Details on Cookie specifications can be found here:

http://luna.bearnet.com/moz/cookie_spec.html

See also:

COOKIE Macro

[? TWebApp.AddCookie]


COM Macro

Use this macro to activate an OLE in-process server, i.e. a DLL Server that you plug into your web-application. This technique lets you integrate unlimited OLE (also known as Active/X, COM or DCOM) resources.

WebHub includes a demo named 'COM' with source code for three examples.

Syntax

1. COM|Program|Parameters

2. COM|Program|FREE

• Program	the name of a user defined text-substitution macro, defined in this manner: Key=GUID|ProgID[,MachineName[,CommaTextInitialParameters]].  To specify that you want to run on the local machine, leave MachineName blank or set it equal to '.' or 'Localhost'.

• Parameters:	as needed, depending on the interface to the particular COM object.

Instead of a GUID, you may also specify a ProgID of an object having an interface like this:

  ITMemoServer = interface(IDispatch)
    ['{85EE647C-D5C7-11D1-8C06-00C0F0168F2B}']
    function Get_ResultText: OleVariant; safecall;
    procedure Set_ResultText(Value: OleVariant); safecall;
    procedure Execute; safecall;
    procedure AddParam(Value: OleVariant); safecall;
    procedure Reset; safecall;
    property ResultText: OleVariant read Get_ResultText write Set_ResultText;
  end;

Use the second syntax to free the TWebDCom component and close its COM connection.  This needs to be done before the application exits for optimal memory management on your server.

Page Counter Example: The Macros defining the COM server and an error handler

<h1>-Macros</h1>
mcPageCounter=Cntr.htComServer,,TheAppID,PageID
mcPgCntErr=PageCounter Error! [%=WebDCOM_PageCounter.Error=%]

Page Counter Example: Using the COM Macro to call the Counter

<h1>-Page:ComCounter=,,,Page Counter Example</h1>
<!-- FYI: Connecting with %=WebDCOM_PageCounter.ProgID=% -->
<center>The number of page requests is:
<p>
<table border=4 cellpadding=4><tr><td><font size=+3>
%=COM|mcPageCounter|||mcPgCntErr=%</font></td></tr>
</table>
</center>

Technical Details for Programmers

The COM macro will run code like the following (see WebDCom.pas) against the COM object's interface:

fServer.Reset;
with fParameters do
  for i:= 0 to pred(count) do
    fServer.AddParam(strings[i]);
fServer.Execute;
Result:=fServer.ResultText;

The COM macro uses the literal or macro name to create a named TWebDCom component on-the-fly and then uses the value of the literal or macro to initialize the TWebDCom object and its associated COM server.

You can see the new component in the Components menu. The second time it is called, it will already be in memory. Use a chunk like this to display the WebDCom component's current settings, where you replace 'mcPageCounter' with the macro you are using for your COM program definition.

<ul>
<li>Name = %=WebDCOM_mcPageCounter.Name=%<br>
<li>GUID = %=WebDCOM_mcPageCounter.GUID=%<br>
<li>ProgID = %=WebDCOM_mcPageCounter.ProgID=%<br>
<li>MachineName = %=WebDCOM_MmcPageCounter.MachineName=%<br>
<li>Parameters =<ul><li> %=WebDCOM_mcPageCounter.Parameters=%</ul><br>
</ul>

See also:

[? ThtWebApp.DoComCall]

Built-in WebHub Event Macros


CRUNCHKEYS Macro

Rename literals in a named set to remove gaps.

Syntax

1. CRUNCHKEYS|name

Example

%=CRUNCHKEYS|price=%

Given literals named price1,price2,price4 and price5, this would rename price4 to price3, and rename price5 to price4, so that there were no remaining gaps in the numbers.

This macro is available in v1.46+


DBEDIT Macro

Creates an input box for a field.  The HTML-field name follows the same convention as those used in other parts of WebHub such as the TWebDataForm, namely WebDataSource . Fieldname @ PrimaryKey.

Syntax

1. DBEDIT|WebDataSource,FieldName

Examples

1. DBEDIT|wdsFull,EmpNo

See also:

Built-in WebHub Event Macros


DEC Macro

Use the DEC macro when you want to subtract 1 from the value of a literal that contains an integer.  DEC stands for "decrement".

Syntax

DEC|Literal

Implemented by

TWebApp

See also:	INC

Built-in WebHub Event Macros

This macro is available as of v1.48+.


DELKEYS Macro

Use the DELKEYS macro when you want to erase a set of literals whose names follow a pattern.  The literal names must be a prefix followed by an integer, e.g. Price1, Price2, Price3.

Syntax

DELKEYS|a[,b]

Example

%=DELKEYS|a,b=%

This would delete a1, a2.. aN and delete b1, b2.. bN.

Implemented by

TWebApp

See also:	Built-in WebHub Event Macros

This macro is available as of v1.48+.


DYNACTION Macro

This forces a dynamic form-action going to the given PageID.  Use this with exported static pages that need to link back into a dynamic page.

Syntax

DYNACTION|PageID

Implemented by

TWebApp


DYNCHUNK Macro

Send a chunk whose name and content is calculated dynamically.

Syntax

1. DYNCHUNK|ChunkIDPrefix,Macro

2. DYNCHUNK|Macro

3. DYNCHUNK|ChunkIDPrefix,Macro,DynVarName|Params

4. DYNCHUNK|ChunkIDPrefix,Macro|Params

The MATCH macro is useful when you need to create a conditional statement with two alternatives.  The DYNCHUNK macro is easier when there are more than two conditions to support.

Multilingual Example

<h1>-Page:PAGE1</h1>

<FORM METHOD=POST ACTION="%=ACTION|PAGE2=%">

Enter your language:

%=<INPUT TYPE=RADIO NAME=inLanguage VALUE="E"> English

%=<INPUT TYPE=RADIO NAME=inLanguage VALUE="G"> German

%=<INPUT TYPE=RADIO NAME=inLanguage VALUE="S"> Spanish

<INPUT TYPE=SUBMIT></FORM>

<h1>-Page:PAGE2</h1>

We will now say 'hello' in your language:

// the next line will send chHelloG if the person chose German.

%=DYNCHUNK|chHello,%=inLanguage=%=%

<h1>-Chunk:chhelloE</h1>

Hello!

<h1>-Chunk:chHelloG</h1>

Hallo!

<h1>-Chunk:chHelloS</h1>

Hola!

Basic Examples

The following WebHub-HTML code demonstrates all 4 syntax variations.  To try these examples yourself, paste the code into one of your WebHub-HTML Files and then request the page TestDynchunk in your web browser.

<h1>-Page:TestDynchunk</h1>
1. DYNCHUNK|ChunkIDPrefix,Macro<BR>
%=SET|x=California=%
%=DYNCHUNK|chUSA,%=x=%=%
<HR>
2. DYNCHUNK|Macro<BR>
%=DYNCHUNK|%=x=%=%
<hr>
3. DYNCHUNK|ChunkIDPrefix,Macro,DynVarName|Params<BR>
%=DYNCHUNK|chUSACities,%=x=%,y|Sacramento,Santa Rosa,San Francisco=%
<HR>
4. DYNCHUNK|ChunkIDPrefix,Macro|Params<BR>
%=SET|x=ZZZ=%
%=DYNCHUNK|chCanadaCities,%=x=%|Toronto,Quebec=%
%=CLEAR|x=%

<h1>-Chunk:chUSACalifornia</h1>
ChunkID: %=ChunkID=%<BR>
Welcome to California.

<h1>-Chunk:chUSATexas</h1>
ChunkID: %=ChunkID=%<BR>
Welcome to Texas.

<h1>-Chunk:california</h1>
ChunkID: %=ChunkID=%<BR>
get surfin'

<h1>-Chunk:chUSACitiesCalifornia</h1>
ChunkID: %=ChunkID=%<BR>
City 1: %=y1=%<BR>
City 2: %=y2=%<BR>
City 3: %=y3=%<BR>

<h1>-Chunk:chCanadaCitiesZZZ</h1>
ChunkID: %=ChunkID=%<BR>
City 1: %=DYN1=%<BR>
City 2: %=DYN2=%<BR>

Resulting Display

If you test the basic examples, this is what you will see in your web browser:

1. DYNCHUNK|ChunkIDPrefix,Macro
ChunkID: chUSACalifornia
Welcome to California.

2. DYNCHUNK|Macro
ChunkID: California
get surfin'

3. DYNCHUNK|ChunkIDPrefix,Macro,DynVarName|Params
ChunkID: chUSACitiesCalifornia
City 1: Sacramento
City 2: Santa Rosa
City 3: San Francisco

4. DYNCHUNK|ChunkIDPrefix,Macro|Params
ChunkID: chCanadaCitiesZZZ
City 1: Toronto
City 2: Quebec

Version Note

Prior to v1.640 you could use DYNCHUNK|chName,x and it would automatically expand x. In v1.64+ you need DYNCHUNK|chName,%=x=% to make x expand.


DYNJUMP Macro

Use this to link to the dynamic version of a PageID, from an exported page.  For example, you might want to have the first page on your web site be a static page which you maintain within WebHub and then export (http://www.yourdomain.com/index.htm).  From there, you would need to link into dynamic pages within WebHub.  You would use the DYNJUMP macro within the W-HTML for that index.htm page, so that the <A HREF> links would be generated as appropriate for dynamic pages.

Do not use DYNJUMP with Branding.  If you are branding, use the regular JUMP macro.

Syntax

DYNJUMP|PageID[,command][|Tags]|VisiblePhrase

Implemented by

TWebApp


EMBED Macro

Use this macro to embed a VRML file.

Syntax

EMBED|

Generated HTML

<EMBED src="http://www.href.com/scripts/runisa.dll?JumpWorlds:12345"
height=212 width=500 align=left>

Example

There is an example in the VRML demo under Ht\Htdemos\HtmlDemo\.

See also:

[? TWebOutputApp.SendEMBED]

[? TWebOutputApp.SendRandomEMBED]

Built-in WebHub Event Macros


EMBEDR Macro

Same as EMBED macro, but prevents web browser caching by using a Random SessionID.

See also:

[? TWebOutputApp.SendEMBED]

[? TWebOutputApp.SendRandomEMBED]

Built-in WebHub Event Macros


EXCEPT Macro

Terminates production of the page with an errormessage.

Syntax

Except|VisiblePhrase

See also:

Built-in WebHub Event Macros


EXPIRES Macro

Use the EXPIRES macro to tell the web browser when to invalidate the cached copy of the web page.

This executes as soon as the page renders, thus providing security at the page level, as it prevents data from being accessed va the back button.

Syntax

Expires|<expires>

This macro specifies an HTML Expiration header.

• <expires>	Specifying a blank value, or '-1' forces an unconditional expiration.  Use this for added security at the page level, as this will force the web browser to re-request the page if the surfer uses the [Back] button. This is also recommended for pages containing checkboxes whose state you want remembered.

0 indicates "now".

1 indicates "tomorrow"

By default, the TWebApp automatically uses the Expires macro on any page that contains remembered checkboxes, i.e. checkboxes that were set up in the WebHub HTML file using the %= prefix.

You will not see the HTTP header in the web browser, even if you View|Source to see the HTML.  You can see it on your web application, if you have set up a TWebHTMLMemo field on your form.  The TWebOutput component will echo the output document to that memo field if you have its ShowOutput property toggled appropriately.

Simple Example

<h1>-Page:pgTestExpires</h1>
%=EXPIRES|-1=%
%=webserver.time=%
<p>
%=JUMP|pgTestExpires=%
<p>

Click the link a few times to go forward, you will see the time advance.
Now click the back button in your browser. You should see the time go
forward because the page should be recalculated.

More examples with other expiration possibilities:

<h1>-Page:ExpTest</h1>
<ul>
<li> %=JUMP|ENow|Now=%
<li> %=JUMP|ETomorrow|Tomorrow=%
<li> %=JUMP|E2000|2000=%
<li> %=JUMP|EYesterday|Yesterday=%
<li> %=JUMP|E2Ago|2 Days Ago=%
<li> %=JUMP|E2pm|14:00=%
<li> %=JUMP|E215|2:15pm=%
</ul>

<h1>-Page:ENow</h1>
%=EXPIRES|0=%
This expires now, GMT.

<h1>-Page:ETomorrow</h1>
%=EXPIRES|1=%
This expires tomorrow.

<h1>-Page:E2000</h1>
%=EXPIRES|12/31/1999=%
This expires at the end of the century.

<h1>-Page:EYesterday</h1>
%=EXPIRES|-1=%
This forces an unconditional expiration.
<h2>HEADERS</h2>
%=HEADERS=%

<h1>-Page:E2Ago</h1>
%=EXPIRES|-2=%
This should expire 2 days ago.
<h2>HEADERS</h2>
%=HEADERS=%

<h1>-Page:E2PM</h1>
%=EXPIRES|12/31/1999 14:00=%
Should be expiring 12/31/1999 14:00
<h2>HEADERS</h2>
%=HEADERS=%

<h1>-Page:E215</h1>
%=EXPIRES|12/31/1999 2:15 PM=%
Should be expiring 12/31/1999 2:15 PM
<h2>HEADERS</h2>
%=HEADERS=%

Sample Output

The "tomorrow" example would produce this HTML output document:

HTTP/1.0 200 OK
Server: WebSitePro/1.1f
Date: Mon 17 Mar 1997 00:22:57 GMT
Content-type: text/html
Expires: Tuesday, 18-Mar-97 00:22:57 GMT

This expires tomorrow.

The 12/31/1999 example would produce this output:

HTTP/1.0 200 OK
Server: WebSitePro/1.1f
Date: Mon 17 Mar 1997 00:25:50 GMT
Content-type: text/html
Expires: Friday, 31-Dec-99 00:00:00 GMT

This expires at the end of the century.

See also:

[? TWebApp.ExpireMode]

Built-in WebHub Event Macros


FIELD Macro

Displays the contents of a named field for the current record.

Syntax

1. FIELD|DataSource|FieldName

2. FIELD|WebDataSource|FieldName

3. FIELD|DataModule.DataSet|FieldName

Examples

1. FIELD|Datasource1|Notes
2. FIELD|WebDataSource1|Notes
3. FIELD|DataModuleAdmin.DataSource2|Notes

Example Usage in HTML

In this example, wdsFull is the name of a TWebDataSource.  EmpNo is the name of a field in the table pointed to by the TWebDataSource.

<TABLE>
<TR>
 <TH>Employee Number</TH><TD>%=Field|wdsFull|EmpNo=%</TD>
</TR>
<TR>
 <TH>First name</TH><TD>%=Field|wdsFull|firstname=%</TD>
</TR>
<TR>
 <TH>Last name</TH><TD>%=Field|wdsFull|lastname=%</TD>
</TR>
<TR>
 <TH>Phone ext</TH><TD>%=Field|wdsFull|phoneExt=%</TD>
</TR>
<TR>
 <TH>Hire date</TH><TD>%=Field|wdsFull|HireDate=%</TD>
</TR>
<TR>
 <TH>Salary</TH><TD>$%=Field|wdsFull|Salary=%</TD>
</TR>
</TABLE>

See also:

Built-in WebHub Event Macros


FILELINK Macro

Use this macro when you want to link to a file that you will create dynamically, when you want the download-filename to be correct.  (By default, it would equal the name of your runner, e.g. runisa.dll.)  This requires the use of the WebHub Coolness Layer.

Syntax

FILELINK|[AppID:]PageID,Command[|additional tags]|visible phrase

The command should be set to the name of the file you want the person to download.

Example

%=FILELINK|DOWNLOAD,balanceSheet.xls|Download the latest balance sheet=%

See also:

[? TWebOutput.SendFileLink ]

Built-in WebHub Event Macros


FLUSH Macro

Clears the named buffer.

Syntax

Flush|BufferName

Examples

Flush|out

Clear the output buffer.

Flush|header

Clear the HTML Headers accrued so far. (See HEADER macro.)

Flush|summary

Clear the Page-Summary buffer.  (See SUMMARY macro.)

See also:

Built-in WebHub Event Macros


FOR Macro

Use the FOR macro when you want to repeat something N times.

Syntax

1. FOR|LoopVariable,From,To[:Width]|Phrase=%

• LoopVariable is the name of the variable used in the loop, e.g. "i".

• Phrase is the data to display for each iteration of the loop. The phrase may contain macro syntax, and may use the LIT macro to reference a literal named based on the loop variable.

• Width determines the display width of the variable. For example, the value "3" displayed with width 4 will show "0003".

Example

The following W-HTML code demonstrates a for loop. To try this example yourself, paste the example code into one of your W-HTML Files and then request the page pgTestFORMacro in your web browser.

<h1>-Macros</h1>
mcForTest=%=i=%<BR>

<h1>-Page:pgTestForLoop</h1>
%=FOR|i,1,10:3|%=mcForTest=%=%

Resulting Display

If you test the example, this is what you will see in your web browser:

001
002
003
004
005
006
007
008
009
010

Example using the LIT macro

Add this code to your test page:

%=SET|price1=10=%
%=SET|price2=20,price3=30,price4=45,price5=100=%
%=FOR|i,1,5|The price for that item is %=LIT|price,i=%.<BR>=%

Resulting Display

The price for that item is 10.
The price for that item is 20.
The price for that item is 30.
The price for that item is 45.
The price for that item is 100.

Implemented by

TWebApp

Built-in WebHub Event Macros

Version Notes

This macro is available as of v1.484+.  The Width parameter was added in v1.75.


FRAME Macro

Use the FRAME macro when you want a shortcut for the FRAME SRC tag.

Syntax

1.FRAME|PageID

2.FRAME|PageID[,Command]

3.FRAME|PageID[|FrameName]

4.FRAME|PageID[-targetFrame][|FrameName]

The FRAME macro is a shortcut for <FRAME SRC="%=cgiApp=%:PageID:%=Session=%" NAME="MAIN">.

Code that as:

1. FRAME|Homepage|"MAIN"

When the optional third term in included, WebHub prepends 'NAME=' and then adds whatever you specify. If you want the name to be quoted, supply the quotes. For example:

%=frame|add1|"Main" marginheight=0 marginwidth=0=%

Example using a frame name and a frame target

1. FRAME|Homepage-_top|"MAIN"

In this example, the WebHub PageID is HOMEPAGE. The target frame name is the reserved frame name _top.  The name of the frame is MAIN.

Implemented by

TWebApp

See also:

Built-in WebHub Event Macros


GO Macro

Use the GO macro to conditionally create a speedbar entry which will either link to the target page or contain placeholder information.

Syntax

1. GO|PageID|VisiblePhrase||ElsePhrase

See JUMP for more syntax variations.

.

If the target PageID is different from the current PageID, then the macro expands the VisiblePhrase.  If the target is the same, then either of two things happen:  (a) if there is an ElsePhrase, that is expanded; otherwise (b) the VisiblePhrase is sent without creating a link, so it becomes just placeholder text.

Use GO instead of JUMP whenever you want to make a speedbar (any group of links) for your site, and you like the idea of having placeholder text for the current page.

Example

<h1>-Chunk:chSpeedBar</h1>

| %=GO|Homepage|Home=%

| %=GO|Feedback|Send Feedback=%

| %=GO|Sitemap|Site Map=% |

Implemented by

TWebApp

See also:

GOR Macro (prohibits browser caching)

HIDE macro (removes the reference entirely if it's going to the same page)

Built-in WebHub Event Macros


GOR Macro

Use this macro instead of GO when you want to be sure that the web browser can not cache the target page.  RandomSession is used instead of Session.

Implemented by

TWebApp

See also:

Built-in WebHub Event Macros


HEADER Macro

Use this macro to add a line to the HTTP header (aka "Prologue") which is sent out as a prefix to the dynamic web page.

Syntax

Header|HeaderName: HeaderValue

The HeaderValue shows up under Extra Headers in the cgi environment data.  The colon and space are required.

Example

Header|SecurityCode: A1234

See also:

Built-in WebHub Event Macros


HIDE Macro

Use the HIDE macro to conditionally create a speedbar entry which will either link to the target page or disappear if the target page matches the current page.

Syntax

1. HIDE|PageID|VisiblePhrase||ElsePhrase

See JUMP for more syntax variations.

If the target PageID is different from the current PageID, then the macro expands the VisiblePhrase.  If the target is the same, then either of two things happen:  (a) if there is an ElsePhrase, that is expanded; otherwise (b) nothing is expanded.

Use HIDE instead of JUMP whenever you want to make a shared speedbar chunk (any group of links) for your site, and you like the idea of having the link disappear if the person is already on the given page.

Example

<h1>-Chunk:chSpeedBar</h1>

| %=HIDE|Homepage|Home=%

| %=HIDE|Feedback|Send Feedback=%

| %=HIDE|Sitemap|Site Map=% |

Implemented by

TWebApp

See also:

HIDER Macro

GO Macro

JUMP Macro

Built-in WebHub Event Macros


HIDER Macro

Use this instead of HIDE when you want to be sure that the web browser can not cache the target page.  RandomSession is used instead of Session.

Implemented by

TWebApp

See also:

Built-in WebHub Event Macros


HREF Macro

Use the HREF macro to create an <A HREF> hypertext link, typically to a non-WebHub resource.

Syntax

1. HREF|targetURL|visiblePhrase

• TargetURL : URL the link to, e.g. http://www.href.com.  The TargetURL may contain a macro, and that macro may contain an HTTP or HTTPS portion.

• VisiblePhrase : HTML rendered for the link.

Example

%=HREF|http://www.href.com/pub/|HREF's public static files area=%

would expand to

<A HREF="http://www.href.com/pub/">HREF's public static files area</A>

Example using AppRoot

 %=href|%=approot=%index.html|index page=%

If you had AppRoot set to "/", then the example above would expand to:

<A HREF="/index.html">index page</A>

Implemented by

TWebApp

Version Notes

Prior to v1.76, the TargetURL was not expanded prior to sending it, so it could not include an HTTP or HTTPS portion.

See also:

JUMP, GO, HIDE macros for linking within WebHub Apps.

([? AppRoot property of TWebBasicApp])

Built-in WebHub Event Macros


HUBAPP  Macro

Use this to remotely change the App being served by the Hub.

Syntax

HUBAPP|AppID

This tells the Hub to switch to the new AppID.


IFDYNAMIC Macro

Sends the phrase if you are making a dynamic HTML page.

Syntax

IFDYNAMIC|phrase[||ElsePhrase]


IFINACTIVEFORSEC Macro

Use this macro to trigger conditional actions based upon the amount of elapsed time between page requests.  The IfInactiveForSec macro tracks the time elapsed between page requests and allows you to control what happens if the session has been inactive for a given number of seconds (determined by the programmer).

 The HTSC demo uses IfInactiveForSecHere in an example of an automatic logout sequence after a preset period of inactivity;  here is the description:

Select your timeout length, either as a number, or as a macro:     "mcLoginLifeSec=5"

Use the IfInactiveForSec macro to force expiration of the password:

%=IfInactiveForSec|%=mcLoginLifeSec=%|%=CLEAR|_bLoginOk=%=%

Put in a REQUIRES macro:     %=REQUIRES|_bLoginOk|pgTimedOut=%

Synchronize the user record:  %=WebLogin.Update=%

Syntax

IfInactiveForSec|seconds|visiblephrase[||elsephrase]

See also:

Built-in WebHub Event Macros

This macro is available as of v1.45+.


IFSTATIC Macro

Sends the phrase if you are making a static HTML file.

Syntax

IfStatic|phrase[||ElsePhrase]


IF, IFNOT Macros

Use these macros to conditionally display a phrase based on a checkbox setting.

Syntax

1. IF|CheckedItemName|VisiblePhrase

2. IF|CheckedItemName|VisiblePhrase[||ElsePhrase]

3. IFNOT|CheckedItemName|VisiblePhrase

4. IFNOT|CheckedItemName|VisiblePhrase||[ElsePhrase]

• CheckedItemName	This must be the name of a checkbox, i.e. an entry in the TWebSession.Checked array.

• VisiblePhrase	This can be regular HTML or a WebHub macro.

• ElsePhrase	This phrase will be sent if the opposite of the condition is true.

Example

%=IF|ckbImagesOk|<img src=/giant.gif>||(gif removed)=%

See also:

Built-in WebHub Event Macros


INC Macro

Use the INC macro when you want to add 1 to the value of a literal that contains an integer.  INC stands for "increment".

Syntax

INC|Literal

Implemented by

TWebApp

See also:	DEC

Built-in WebHub Event Macros

This macro is available as of v1.48+.


INCLUDE Macro

Use this macro when you want to include an entire text file on a page.

Syntax

INCLUDE|Filename

The filename must be fully qualified.  The data will be sent and the page will continue.

Example

%=INCLUDE|c:\temp\copyright.html=%

%=include|c:\autoexec.bat=%

See also:

[? TWebOutput.SendFile ]

Built-in WebHub Event Macros


INPUTCHECKBOX Macro

Use the INPUTCHECKBOX macro to create an INPUT TYPE=CHECKBOX tag within an HTML form.

Syntax

INPUTCHECKBOX|checked[|other tags]

If you use this macro, you do not need controlled HTML in addition.  You do need to use .CKB as the command in the form's ACTION tag.

Example

%=INPUTCHECKBOX|bShowGraphics=%

Assuming the checkbox were checked, this would expand to:

<INPUT TYPE=CHECKBOX checked NAME="bShowGraphics" VALUE="Yes">

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.46+.


INPUTFILE Macro

Use the INPUTFILE macro to create the syntax that lets the surfer select a file for upload.  If you want to process the uploaded file, use Object Pascal to processing the uploaded file(s) on the page indicated by the form action tag.

Syntax

InputFile|name[,AcceptType][|other tags]

• name : name of the field

• AcceptType : optional mime type of files to accept, e.g. text/html

• other tags : any additional html, e.g. SIZE=30

Example

%=InputFile|aFile=%

General Information on TYPE="FILE"

This input widget automatically creates a text field and a "Browse" button that the user can click in order to select a file to upload from their local hard drive.  It then associates the file contents with the NAME defined in the <INPUT>.

The input tag also takes an ACCEPT attribute that defines which media types are acceptable for upload. By default, any type of file can be uploaded.

Example for Uploading Text/Html Files

<h1>-Page:pgUpload</h1>
%=INPUTFORM|pgUploaded|multipart|name=aform=%
File to Upload %=INPUTFILE|YourFile,text/html|size=30=%
%=INPUTSUBMIT|,Upload the File=%
%=INPUTFORM|close=%

<h1>-Page:pgUploaded</h1>
You uploaded:<br>
%=WebServer.FormFiles=%

Implemented by

TWebApp

See also:	OnUploaded Event

Built-in WebHub Event Macros

This macro is available as of v1.48+.


INPUTFORM Macro

Use this macro to create <FORM> and </FORM> tags.

Syntax

1. InputForm|AppID:PageID[,cmd]|{post,get,multipart}[|other tags]

2. InputForm|close

If AppID:PageID is omitted, the current PageID will be used as the target.

If "multipart" is specified, it will generate 'enctype="multipart/form-data"'.

.CKB must be specified as the cmd if the form contains checkboxes or inputchecked macros.

When uploading files, be sure to use "multipart" or specify a different encoding type using 'other tags'.

Example

%=InputForm|MyAppID:MyPageID,.CKB=%

Example

%=InputForm||multipart=%

Example

Syntax #2 ends the form with </FORM>.


INPUTHIDDEN Macro

Use the INPUTHIDDEN macro to create an INPUT TYPE=HIDDEN tag within an HTML form.  Hidden fields are not visible in the browser unless the surfer uses a View|Source command to inspect the HTML code, in which case the information is plainly visible.

Syntax

INPUTHIDDEN|literal|other tags]

Example

%=InputHidden|Session=%

would expand to

<INPUT TYPE=HIDDEN NAME="session">

The VALUE will be filled in if available.

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.48+.


INPUTIMAGE Macro

Use the INPUTIMAGE macro to create an INPUT TYPE=IMAGE tag within an HTML form.  Use these macros when you want to use a graphic for submitting a form (instead of a standard textual "submit" button.)

Syntax

INPUTIMAGE|name,src[|other tags]

If the button name contains the '@' character, the data will go to the TWebServer.dbFields array instead of literals. Therefore it will only be available within Delphi, and the value will be forgotten.  Use '@' in button names when you do not want to track their values.

Example

%=INPUTIMAGE|btn@home,/images/btn/home.png=%

This would expand to:

<INPUT TYPE=IMAGE NAME="btn@home" SRC="/images/btn/home.png">

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.46+.


INPUTNUMBER Macro

Use the INPUTNUMBER macro to create an INPUT TYPE=NUMBER tag within an HTML form.

Syntax

INPUTNUMBER|literal|other tags]

Example

%=InputNumber|aNumber=%

would expand to

<INPUT TYPE=NUMBER NAME="aNumber">

The VALUE will be filled in if available.

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.48+.


INPUTPASSWORD Macro

Use the INPUTPASSWORD macro to create an INPUT TYPE=PASSWORD tag within an HTML form.

Syntax

INPUTPASSWORD|literal|other tags]

Example

%=InputPassword|aPassword=%

creates

<INPUT TYPE=PASSWORD NAME="aPassword" Value="">

where the value is filled in, if available as a Literal.


INPUTRADIO Macro

Use the INPUTRADIO macro to create an INPUT TYPE=RADIO tag within an HTML form.

Syntax

INPUTRADIO|literal,value[|other tags]

If you use this macro, you do not need controlled HTML in addition.

Example

%=INPUTRADIO|radioCreditCardType,Mastercard=%

Assuming the radio button were checked, this would expand to:

<INPUT TYPE=RADIO checked NAME="radioCreditCardType" VALUE="Mastercard">

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.46+.


INPUTRESET Macro

Use the INPUTRESET macro to create a RESET button within an HTML form.

What's a RESET button? In some cases, you will want to give the user the ability to reset an entire form so that it is cleared completely back to its default state.   To do this, you would use a  RESET button, which works similarly to the SUBMIT button, except that rather than telling the browser to send the form data to the server, it instead instructs the browser to clear the form.

As with the SUBMIT button, the RESET button can have a NAME and a VALUE, though you'd never use the NAME for anything since it is never sent in to the server.

Syntax

INPUTRESET|name,value[|other tags]

Example 1

%=INPUTRESET|=%

This would expand to:

<input type=reset>

Example 2

%=INPUTRESET|,Reset=%

This would expand to:

<input type=reset value="Reset">

Implemented by

TWebApp

See also:	Built-in WebHub Event Macros

INPUTSUBMIT

This macro is available as of v1.496+.


INPUTSELECT Macro

Use the INPUTSELECT macro to create a SELECT statement within an HTML form.

Syntax

INPUTSELECT|name,listname,size[,IsMultiple][|other tags]

• name - name of the field.   Do not use underscores in the name of the field.

• listname - the name of a macro containing a comma separated list of 'RealValue-DisplayValue' pairs in a string, or the name of a chunk containing key-value pairs separated by carriage-return linefeed.  See mcList and chList examples below.

• size - height of the select box (default 1)

• IsMultiple - enter Yes to allow selection of multiple items from the list (default No)

Select lists with multi-word values

If you use values with spaces, the space is translated to a plus sign.  Your Delphi code must change it back to a space if that's what you want. (new in v1.670)

Example using a Macro to define the list

<h1>-Macros</h1>
// 'a' is the RealValue.  'appples' will be displayed in the drop down.

mcList=a-apples,b-bananas,c-cherries

<h1>-Chunk:chExample</h1>

%=INPUTFORM|pg2=%

Fruit:

%=INPUTSELECT|inFruit,mcList,1,YES=%<BR>

%=INPUTSUBMIT|=%

</FORM>

The chunk would expand to this, with your path, runner, appid and pageid filled in:

<FORM method="POST" action="/path/runner.ext?AppID:pg2">

Fruit:
<SELECT name="inFruit" size=1 MULTIPLE>

<OPTION VALUE="a">apples

<OPTION VALUE="b">bananas

<OPTION VALUE="c">cherries</SELECT><BR>
<input type=submit>
</FORM>

Example using a Chunk to define the list

<h1>-Chunk:chList</h1>
a-apples

b-bananas

c-cherries

The Result of Using a SELECT Tag

WebHub will create a "literal" whose name equals the select field's name.  The value of that literal will equal the HTML value tag, with commas separating multiple values.

For example, if apples is selected in the example above, the literal 'inFruit' will contain 'a'.  If MULTIPLE is enabled and the surfer chooses apples and bananas, it will contain 'a,b'.

Version Note

Support for using a chunk to define the list was added in v1.680.

Implemented by

ThtWebApp (see htWebApp.pas)

See also:	Built-in WebHub Event Macros

INPUTRESET

This macro is available as of v1.46+.


INPUTSELECTCHECKBOX Macro

Use the INPUTSELECTCHECKBOX macro to create a series of checkboxes within an HTML form.

Syntax

INPUTSELECTCHECKBOX|name,valuename[,before[,after]][|other tags]

• Name - Name of the field

• ValueName - a list of key-value pairs, defined in a macro or a chunk.

• before - W-HTML to send before each checkbox

• after - W-HTML to send after each checkbox

• other tags - any additional W-HTML

ValueName defined as a Macro

<h1>-Macros</h1>
mcList=a-apples,b-bananas,c-cherries

ValueName defined as a Chunk

<h1>-Chunk:chList</h1>
a-apples

b-bananas

c-cherries

Example

<h1>-Page:pg1</h1>
%=chExample=%

<h1>-Macros</h1>
mcList=a-apples,b-bananas,c-cherries

<h1>-Chunk:chExample</h1>
%=INPUTFORM|pg2=%
Check one or more fruits:<BR>
%=INPUTSELECTCHECKBOX|bFruit,mcList,*&nbsp;&nbsp;,<BR>=%<BR>Choose a fruit:<BR>
%=INPUTSUBMIT|=%
</FORM>

The chunk would expand to this, with your path, runner, appid and pageid filled in:

<FORM method="POST" action="/path/runner.ext?AppID:PG2">
Check one or more fruits:<BR>
*&nbsp;&nbsp;<input type=checkbox name="bFruit_1" value="a">apples<BR>
*&nbsp;&nbsp;<input type=checkbox name="bFruit_2" value="b">bananas<BR>
*&nbsp;&nbsp;<input type=checkbox name="bFruit_3" value="c">cherries<BR>
<BR>
<input type=submit>
</FORM>

Implemented by

TWebApp

See also:	INPUTSELECT, INPUTSELECTRADIO

Built-in WebHub Event Macros

Version Notes

This macro is available as of v1.46+.

Support for ValueName coming from a chunk was added in v1.68.


INPUTSELECTRADIO Macro

Use the INPUTSELECTRADIO macro to create a series of radio buttons within an HTML form.

Syntax

INPUTSELECTRADIO|name,valuename[,before[,after]][|other tags]

• Name - name of the field

• ValueName - a list of 'key dash value' pairs, defined in a macro or a chunk.

• before - text to display before each radio button

• after - text to display after each radio button

• other tags - any additional  HTML to put inside the SELECT tag.

ValueName defined as a Macro

<h1>-Macros</h1>
mcList=a-apples,b-bananas,c-cherries

ValueName defined as a Chunk

<h1>-Chunk:chList</h1>
a-apples

b-bananas

c-cherries

Example

<h1>-Page:pg1</h1>
%=chExample=%

<h1>-Macros</h1>
mcList=a-apples,b-bananas,c-cherries

<h1>-Chunk:chExample</h1>
%=INPUTFORM|pg2=%
Choose a fruit:<BR>
%=INPUTSELECTRADIO|inFruit,mcList,*&nbsp;&nbsp;,<BR>=%<BR>
%=INPUTSUBMIT|=%
</FORM>

The chunk would expand to this, with your path, runner, appid and pageid filled in:

<FORM method="POST" action="/path/runner.ext?AppID:PG2">
Choose a fruit:<BR>
*&nbsp;&nbsp;<input type=radio name="inFruit" value="a">apples<BR>
*&nbsp;&nbsp;<input type=radio name="inFruit" value="b">bananas<BR>
*&nbsp;&nbsp;<input type=radio name="inFruit" value="c">cherries<BR>
<BR>
<input type=submit>
</FORM>

Implemented by

TWebApp

See also:	Built-in WebHub Event Macros

Version Notes

This macro is available as of v1.46+.

Support for ValueName coming from a chunk was added in v1.680.


INPUTSUBMIT Macro

Use the INPUTSUBMIT macro to create a SUBMIT button within an HTML form.

Syntax

INPUTSUBMIT|name,value[|other tags]

If the button name contains the '@' character, the data will go to the TWebServer.dbFields array instead of literals. Therefore it will only be available within Delphi, and the value will be forgotten.  Use '@' in button names when you do not want to track their values.

Example 1

%=INPUTSUBMIT|=%

This would expand to:

<input type=submit>

Example 2

%=INPUTSUBMIT|,Submit=%

This would expand to:

<input type=submit value="Submit">

Example 3

%=INPUTSUBMIT|btn@home,Click to Send Feedback=%

This would expand to:

<input type=submit name="btn@home" value="Click to Send Feedback">

Implemented by

TWebApp

See also:	Built-in WebHub Event Macros

INPUTRESET

This macro is available as of v1.46+.


INPUTTEXT Macro

Use the INPUTTEXT macro to create an INPUT TYPE=TEXT tag within an HTML form.

Syntax

1. INPUTTEXT|literal

2. INPUTTEXT|literal,size

3. INPUTTEXT|literal,size,maxlength

4. INPUTTEXT|literal[,size[,maxlength]][|other tags]

Examples

%=INPUTTEXT|surfername=%

%=INPUTTEXT|surfername,20,30=%

%=INPUTTEXT|surfername,20,30|onMouseOver="function"

The second example would expand to

<INPUT TYPE=TEXT NAME="surfername" VALUE="%=surfername=%" SIZE=20 MAXLENGTH=30>

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.46+.


INPUTTEXTAREA Macro

Use the INPUTTEXTAREA macro to create a TEXTAREA tag within an HTML form.

Syntax

INPUTTEXTAREA|name,rows,cols[|other tags]

Example

%=INPUTTEXTAREA|txtMessage,4,40=%

This would expand to:

<TEXTAREA NAME=txtMessage ROWS=4 COLS=40>

(If txtMessage is non-blank, its contents would be here)

</TEXTAREA>

Example

%=InputTextArea|txtMessage,5,20|wrap virtual=%

This would expand to:

<TEXTAREA NAME=txtMessage ROWS=5 COLS=20 wrap virtual>

(If txtMessage is non-blank, its contents would be here)

</TEXTAREA>

Implemented by

TWebApp

Built-in WebHub Event Macros

This macro is available as of v1.46+.


JS Macro

Creates an A HREF link which calls a JavaScript function.

Syntax

JS|functionName[(params)]|VisiblePhrase

Example

%=JS|DoOnLoad|Click here to run the generated JavaScript Code.=%

See also:

Built-in WebHub Event Macros


JUMP Macro

Use the JUMP macro to create a link to a page within a WebHub application.  When the HTML for the page is created, WebHub will expand the macro as needed.

Syntax

1. JUMP|PageID|VisiblePhrase

2. JUMP|AppID:PageID|VisiblePhrase

3. JUMP|PageID(ServerID)|VisiblePhrase

4. JUMP|PageID,<comma separated list of commands>|VisiblePhrase

5. JUMP|PageID-targetFrameName [more HTML]|VisiblePhrase

6. JUMP|PageID|more HTML|VisiblePhrase

7. JUMP|[AppID:]PageID[(ServerID)[,<comma separated list of commands>][;otherTags]|VisiblePhrase

8. JUMP||VisiblePhrase

9. JUMP|:PageID|VisiblePhrase

• PageID	Target PageID, including any built-in pages or the DO page.  You can use %=Macros=% here.

• VisiblePhrase	This is the information used to create the "visible" part of the link.  In the case of a graphical link, the graphic itself is visible.

• AppID	 ApplicationID.  Use this when you want to jump to a page that is within a different WebHub App.

• ServerID	Use this when you want to jump to a page on a different ServerID.  ServerID covers http address, port, runner path and name.  ServerIDs are declared on the TWebInfo component.

• Commands	A command is a string of characters which will be passed to the TWebAction components on the target page, and is accessible through the TWebApp.Command property.  Multiple commands may be specified in a comma-list.

• TargetFrameName	Use this to specify a target frame name.  Use -_top for the top level frame.

• MoreHTML	Use this for additional HTML tags and JavaScript.  When specifying these after the PageID, use a ; separator.

Examples

1. %=JUMP|feedback|Send Us Feedback=%

If you are using the runisa.dll runner, this macro could expand to

<A HREF="/scripts/runisa.dll?AppID:feedback:12345">Send Us Feedback</A>

The expansion is handled differently if you are exporting pages.  In export mode, JUMPs expand based on the CgiHttp and ExportFilename properties:

<A HREF="feedback.html">Send Us Feedback</A>

Alternate example, using graphics:

<h1>-Macros</h1>

mcFeedback=<img src=/images/feedback.gif>

<h1>-Chunk:chPageFooter</h1>

<HR>

%=JUMP|feedback|%=mcFeedback=%=%

2. %=JUMP|WEBMAIL:feedback|Send Us Feedback=%

This link would go to the AppID "WEBMAIL".

3. %=JUMP|feedback(SSL)|Send Us Feedback=%

This link would run on ServerID "SSL", which could be a secure channel.  This technique affects only this JUMP and no others.  If you want to cause ALL links to a given page to run on a certain server, put the ServerID directly into the page definition.  [? TWebPage.PageDestination.]

4. %=JUMP|feedback,CKB|Send Us Feedback=%

The "CKB" command tells the target page to process checkboxes.

5. %=JUMP|feedback-MAIN|Send Us Feedback=%

This link would place the content in the frame named "MAIN".  Note that Netscape is case sensitive on the _top and _parent keywords.  Use lowercase letters!  And make sure that you prevent WebHub from forcing the text to uppercase -- put at least one character, even a space, before the %= tag on a line.

6. %=JUMP|feedback|onMouseOver="window.status='Send Us Feedback';return true"|Send Us Feedback=%

Note the 3 vertical bars. In this example, the last parameter becomes the VisiblePhrase, and the one before that is sent as additional HTML, before the > in the A HREF link.  So this might generate:

<A HREF="/scripts/runisa.dll?AppID:feedback:12345:" onMouseOver="window.status='Send Us Feedback';return true">Send Us Feedback</A>

8. If no AppID or PageID is given, it will go to the Default AppID for the server (see WebAppID), and the HOMEPAGE within that app.

9. The leading colon indicates that a PageID is being specified. The jump will go to the default AppID for the server, and the specific PageID within that app.

Implemented by

TWebApp

See also:

JumpR Macro

GO Macro

HIDE Macro

DYNJUMP Macro

Built-in WebHub Event Macros


JumpR Macro

Same as JUMP, but uses RandomSession so that the web browser can not cache the page link.

Implemented by

TWebApp

See also:

Built-in WebHub Event Macros


Pages, Built-In

The following PageIDs are built into WebHub.

ERRORS	list errors encountered when starting the app.

INDEX	list of all pages in the WebApp, presented in a simple list..

INDEXT	list of all pages in the WebApp, presented in a table.

SPEED	timing test page

STATUS	statistics about the WebApp

DO	Use to execute a WebAction component directly.

The following command string is recognized by all WebHub runners:

ECHO	echo all cgi environment and system data

Usage

To run the echo test, you would request:

http://localhost/scripts/runisa.dll?echo

To run the speed test, you would request:

http://localhost/scripts/runisa.dll?AppID:Speed

You can not override the echo test.  However, you can override all built-in pages by defining your own replacement page in the HTML file. For example, this would replace the Speed page:

<h1>-Page:Speed</h1>
This is the replacement page.

<h1>-Page:Speed</h1>

// This is also a replacement page; it adds security by

// bouncing the surfer to the login page.

%=BOUNCE|pgLogin=%

Overriding the Index and IndexT Pages

To override the entire Index, replace it with a page as shown above for Speed.

Overriding a Single Entry in the Index Page

To override a single page, put a hyphen (-) before the page description:

<h1>-Page:Admin=,,,-Admin Page</h1>
The Admin page will not show up in the Index.


SPEED Page

All WebHub apps have a built-in page called 'SPEED.'  Use that to determine pages-per-hour and pages-per-day for your configuration.  The number from the speed page tells you how many new surfers you can support per hour, given enough machines in a cluster of web servers.

Browser

We strongly recommend testing the SPEED page with a Netscape Navigator browser, not Microsoft Explorer. IE has bugs relating to caching.  In any case, you definitely need a web browser that supports the META REFRESH command.


Navigational Macros, Notes

Some navigational macros have an optional R after their name.  When accessed in that form, they will return a random session number instead of just the surfer's session number. This helps to overcome the problems inherent in browser's caching of dynamically changing pages that come from the same URL.

Microsoft Internet Explorer caches much more often than Netscape browser, and if you don’t use the R, surfers may end up viewing old data on pages that you have just calculated dynamically.

Example: JUMP vs JUMPR


JUMPBACK Macro

Use this to jump back to the prior AppID and PageID as defined on TWhSession.

Syntax

JumpBack|visiblePhrase

VisiblePhase is what the surfer will see for the link. It can be a graphic.

See also:

JUMP macro

Built-in WebHub Event Macros


LIT Macro

Use the LIT macro to return the value of a numbered literal.  A numbered literal is a literal consisting of a prefix plus an integer, e.g. Price2.

Syntax

LIT|LiteralPrefix|Number

Example

%=LIT|price|3=%

This would return the value of the literal named Price3.

Example

%=LIT|price|i=%

The number can be a variable.  This example would work so long as i is the name of a literal containing an integer.

Implemented by

TWebApp

Version Notes

This macro is available in v1.48+.  In v1.7+, use a bar separator between the literal name and the variable (as shown above). The original syntax specified a comma separator.

See also:	FOR Macro, Built-in WebHub Event Macros


MAILTO Macro

Use the MAILTO macro to generate a mailto link.  If the VisiblePhrase is omitted, it defaults to the emailAddress.

Syntax

MAILTO|emailAddress[|VisiblePhrase]

Example

%=MAILTO|ann@href.com|send email to Ann=%

This would generate <A HREF="mailto:ann@href.com">send email to Ann</A>

Implemented by

TWebApp

Added in WebHub v1.27.


MATCH, NOMATCH Macros

Use these macros to conditionally display information based on a string. The result is sent if the match succeeds, and the alternative result is sent if the match fails.

NOMATCH returns the opposite of MATCH.

Syntax

1. MATCH|string1<operator>string2|result[||alternativeResult]

2. NOMATCH|string1<operator>string2|result[||alternativeResult]

String1 and String2 can be W-HTML expressions.  Before being compared to each other through the operator, they are run through the CompareTo function.  The result may use W-HTML as well.

= operator

%=MATCH|string1=string2|thenSendThis=%

The match clause is true if there is a case sensitive match between string1 and string2.

%=NOMATCH|Username=Superuser|%=PAGE|login=%=%

If the username literal does not equal 'Superuser' then switch the surfer to the LOGIN page.

~ operator

%=MATCH|string1~string2|thenSendThis=%

The match clause is true if there is a case insensitive match between string1 and string2.

! operator

%=MATCH|string1!string2|thenSendThis=%

The match clause is true if string1 starts with string2 (case insensitive). When using the ! symbol, string2 may contain the '?' wildcard to match a single character.  In all cases, a trailing '*' is implied, meaning that any number of additional characters at the end are ignored/ok.

[ operator

%=MATCH|string1[string2|thenSendThis=%

The match clause is true if string2 contains string1 on a case insensitive basis, with partial matches accepted. String2 may be a comma-separated list as shown in the example for the $ operator.

$ operator

%=MATCH|string1$string2|thenSendThis=%

The match clause is true if string1 is in string2, with only complete matches being accepted.  Here are some examples:

%=MATCH|red$green,red,white,blue|thenSendThis=%  // true because 'red' is one of the items in string2

%=MATCH|red$greenredwhiteblue|thenSendThis=%     // false because 'red' is not a distinct item

%=MATCH|red$green,redwhite,blue|thenSendThis=%   // also false

// display the full speedbar unless the page is pgEnter or AboutFAST.
%=NOMATCH|PageID$pgEnter,AboutFAST|%=chSpeedBar=%=%

Delphi note: both the [ and $ operators use the tPack IsIn function, with a comma as the separator character.

Version Notes

Prior to v1.64, the MATCH macro was limited to one line. That limitation was lifted in v1.64.

The [ and $ operators were added in v1.47.

See also

Built-in WebHub Event Macros


PAGE Macro

Use the PAGE macro to immediately switch the surfer to a different page, without the surfer having to do anything.  It is conceptually like a 'GOTO' command.  It clears any page contents created thus far, and then starts on the indicated new page.

Syntax

PAGE|PageID[,command]

PageID must be within the current AppID.

The PAGE macro was conceived for use in page-sections, where the system can detect the "abort" exception and then can restart outputting either the same or a new page.  This works fine in conjunction with conditionals that you may have set up for the page section.

As of WebHub v1.2x, you can send the PAGE macro from within Pascal or C++ as long as you are not within WebPage.OnExecute or WebPage.OnSection. For example:

Send('%=PAGE|homepage=%');

Here is an alternate way to change the PageID within your code:

WebApp.PageID:='homepage';	// set to WebHub PageID

// whose content you want to display

abort;	// stop the current page.

See also:

Built-in WebHub Event Macros


PAGEDEFAULT Macro

Sets a page default.

Syntax

PAGEDEFAULT|key=value

You can set page defaults by setting extra flags on the files list, as well. That has the advantage of tagging all pages within a file with the same defaults.

[TWebApp.Files]

pages=pages.htm,secure=yes

entrance=entrance.htm,secure=no

All pages within pages.htm would have PageDefault of secure set to yes.

Version Notes

Page defaults are forced to uppercase, at least through v1.720.


PARAMS Macro

The PARAMs macro sends a macro or chunk, passing parameters that may be used within that macro or chunk.

Syntax

1. PARAMS|ChunkID|ParameterValueList

2. PARAMS|ChunkID,TempVarName|ParameterValueList

3. PARAMS|ChunkID,TempVarName,SeparatorChar|ParameterValueList

Use commas between items in ParameterValueList.

The ChunkID may be a chunk, page or macro.

The PARAMS macro will treat each element in the ParameterValues list as a macro, i.e. expand it by running it through compareto, and then creates temporary literals in the current session to store these expanded values. These literals are named automatically; in syntax 1, the name is assigned: it will always be 'DYN' plus the item number, e.g. DYN1, DYN2, etc.  In syntax 2, you determine the value of the TempVarName, and the name will then be that string, plus the parameter number.

Using Commas in the Data

If you want to include a comma as part of the data you are passing, use the HTML to render a comma (&#44;) instead.  For example, "red&#44;blue" will display as "red,blue".

Using a Different Separator Character

Set SeparatorChar to the character you wish to use.

Example using ^ as a separator:

%=PARAMS|chExample,DYN,^|data^data2^data3=%

Example

Say you are putting out an on-line Spring Sportswear Catalog, which includes colorful sundresses and shorts.  You could use the PARAMS macro to include price, size, and color info for each product:

%=PARAMS|chSpringLine|Sundresses,S/M/L,$28,pink and lilac,=%

%=PARAMS|chSpringLine|Shorts,S-M-L-XL,$18,red and teal=%

You would need to define a chunk named chSpringLine:

<H1>-Chunk:chSpringLine</H1>
%-DYN1=% are available in sizes %=DYN2=% for %=DYN3=%, and come in the following colors: %=Dyn4=%.

Example with a Named Variable

This is the same example, using the named variable "ProdInfo" instead of the default variable name "Dyn."

%=PARAMS|chSpringLine,ProdInfo|Sundresses,S/M/L,$28,pink,lilac,=%
%=PARAMS|chSpringLine,ProdInfo|Shorts,S-M-L-XL,$18,red,teal=%

<H1>-Chunk:ch SpringLine</H!>
%-ProdInfo1=% are available in sizes %=ProdInfo2=% for %=ProdInfo3=%, and come in the following colors: %=ProdInfo4=%.

Version Notes

This macro is available in v1.46+

[? TWebApp.Parameterize method ]


POPPAGE Macro

Use this macro when you want to bounce the surfer to the PageID which was already stored in the named Literal.

Syntax

PopPage|LiteralName

The literal is automatically cleared after this runs.  The target PageID must be within the current AppID.

Unlike the PAGE macro, POPPAGE does not change or clear the WebApp.Command.

See also:

Built-in WebHub Event Macros


PROLOGUE Macro

Use this macro to change the web document type on the fly.  For example, use this to generate a TEXT page instead of an HTML page.

Syntax

PROLOGUE|PrologueType

PrologueType may be: 'skip', 'html', 'text', 'vrml', 'ssi' or a custom string.  The PrologueType is not case sensitive.

If a custom string is encountered, WebOutput.prologue becomes proCustom and WebOutput.ContentType becomes that parameter.

Example

PROLOGUE|text

See also:

Built-in WebHub Event Macros

This macro is part of WebHub v1.45+.


PUSHPRIOR Macro

Use the PUSHPRIOR macro in conjunction with POPPAGE to implement pages or sequences that act as subroutines.

Syntax

PushPrior|LiteralName

If it was blank, the named literal is set to PriorPageID.  [? TWebSession.PriorPageID]

See also:

Built-in WebHub Event Macros


PUSHTHIS Macro

Use the PUSHTHIS macro in conjunction with POPPAGE to implement pages or sequences that act as subroutines.

Syntax

PushThis|LiteralName

If it was blank, the named literal is set to the current PageID. [? TWebApp.PageID]

See also:

Built-in WebHub Event Macros


REFRESH Method

This method makes the application object (TWebApp) refresh -- the one inside the application running on the server.  Use this when you are maintaining a site remotely, and want the application to use newly posted HTML or INI files.

Syntax

ComponentName.REFRESH

Example as used in a regular web application

<H1>-Page:DoRefresh=,,,Refresh the Site</H1>

%=htwebapp.refresh=%

Example as used inside the Hub

<H1>-Page:DoRefresh=,,,Refresh the Site</H1>

%=hubapp.refresh=%

This is equivalent to using the menu to say AppID|Refresh.  The response page will vary depending on your version of WebHub. As of v1.34+, you will get a short, simple page with text that says the application is refreshing, with a link back to the "HOMEPAGE" for the web application.

To use this remotely, make yourself a bookmark or web page with a link to the DoRefresh page, e.g. http://www.mydomain.com/scripts/runisa.dll?AppID:DoRefresh


REQUIRES Macro

Requires the named literal or checkbox.  Can check for a specific value.  Optionally bounces the surfer to another page if the literal is undefined.

Syntax

1. REQUIRES|checkbox[|PageID]

2. REQUIRES|literal{=,!,~}value][|PageID]

• check	name of the checkbox that must be checked

• literal	name of the literal that must match a value

• =	exact case sensitive match

• ~	case insensitive match

• !	key must start with value

• PageID	PageID to take surfer to if required value is not found.  This must be within the current AppID.

If the value is absent or does not match, the surfer is bounced to:

• the Page specified,
• the FrontDoorPageID, if one is specified
• the HomePageID, if one is specified
• otherwise the request is ignored

Example

Requires|UserName=Superuser|LOGIN

Requires|chkAccess|LOGIN

The following example means "require that ccNumber be non-blank; if it is blank, take the surfer to the ORDERFORM page."

Requires|ccNumber!|orderform

See also:

Built-in WebHub Event Macros


SENDFILE Macro

Use this macro when you want the dynamic response document to consist of a single file, and you want to hide the file location from the surfer.

Syntax

SENDFILE|Filename[,MIME-type][,DELETE]

The filename will be analyzed to see whether it is an absolute file reference or should be considered relative to the server base path. When this macro is used, there will be no regular HTML response page. Instead, the file will be sent.  The web browser's response will depend on the MIME type.  The file's actual location will be known only inside the WebHub HTML file and never seen by the surfer.

   If you specify DELETE, then the file will be deleted after it is sent.

The SENDFILE macro works with the Microsoft IIS web server only.

Examples

%=SENDFILE|c:\temp\store.gif,image/gif=%

%=SENDFILE|c:\temp\tempxx17.jpg,image/jpg,DELETE=%

%=SENDFILE|/planet/gif/new.gif,image/gif=%

To clear any headers or leading text that might be in the buffer, use FLUSH before SENDFILE:

%=FLUSH|=%

%=SENDFILE|c:\temp\store.gif,image/gif=%

See also:

[? TWebOutput.SendFileIIS]

SendFile demo project

Built-in WebHub Event Macros


Absolute file reference

WebHub considers a string to be an absolute file reference if:

• it starts with \ or \\

• the second character is a :

If the file is to be used for a URL, then a leading / character also qualifies the string as an absolute reference.


SESSION Macro

Use this macro to control what happens to the session object when the session data is saved to disk.

Syntax

1.SESSION|Save[|DateTime]

2.SESSION|Delete[|DateTime]

3.SESSION|Touch[|DateTime]

4.SESSION|PlaceHolder[|DateTime]

5.SESSION|Time[|DateTime]

6.SESSION|HouseClean

7.SESSION|Ignore

In all cases, DateTime (the date string passed in) must be in the same format (ShortDateFormat) used within the Expire setting  for the COOKIE Macro, so it can be evaluated by StrToDateTime/StrToDate.

  ShortDateFormat: DD-Mon-YY HH:MM:SS GMT

1. Save: This saves the session object (as usual), optionally setting the datetime.  Assuming that the Hub's Background Delete feature has been enabled on the Session Panel, the session file will be deleted once the datetime is reached. (v1.46+)

2. Delete: When the session ends, this deletes the session object and thus all the transaction data.  This guarantees that anyone returning with that same session number will be treated as a new surfer just arriving on the site.  Use this to enforce security at the session level.

3. Touch: This sets the timestamp on the object without saving any data. Any changes to literals, checkboxes etc. from the most recent page request will be lost.  Use this with care.

4. Placeholder: This creates an empty (0-byte) session file with the given timestamp. This reserves a session number for later use.

5. Time: This sets the date-time without changing the mode, where the mode is Save/Delete/Touch/Placeholder.

6. Houseclean: Compacts the memory used by the sessions and expires old sessions from memory.  This executes immediately, rather than when the session is written to disk.

7. Ignore: Do nothing after the session finishes.

See also:

Built-in WebHub Event Macros

[? SessionEndWith property of TWebApp]

This macro is available as of v1.46+.


SET Macro

Use the SET macro to set the value of a Literal from within the WebHub HTML.

Syntax

1. Set|<key=value>[,<key=value>]

2. Set|textarea.varName=value

Specify a list of variables and what you'd like to set them to. You may use wildcards in Key to reassign multiple existing variables. Value may be a WebHub macro.  To set textareas, use the textarea. prefix (not case sensitive, v1.40+).

NOTE:  If the value itself contains a comma, the data from that point forward (including the comma) will be ignored.

Example

%=SET|SurferName=Unknown=%

%=SET|textarea.txtMemo=hello there=%

See also:

Built-in WebHub Event Macros


SHELL Macro

Use this macro to run another program and wait for it to finish.

Syntax

SHELL|Program|Parameters

This macro runs Program, passing Parameters.  It will wait for Program to finish.  If you are calling a BAT file to call another program, use the DOS START command in the BAT file.

See also:

START macro

Built-in WebHub Event Macros

Version Notes

As of v1.650, the Shell Macro no longer displays the "working" message, and parameters are expanded automatically.


SOURCE Macro

Use this macro to display the WebHub HTML source behind a chunk, for training purposes.

Syntax

SOURCE|{chunkName}

This macro is used extensively in the SHOWCASE demo, to let surfers "view source" and see how features are created in the chunk files.

Example

%=SOURCE|chSystemInfo=%

See also:

Built-in WebHub Event Macros


START Macro

Use this macro to start an external program.  This macro returns immediately; it does not wait for the program to finish.

Syntax

START|Program|Parameters

See also:

SHELL Macro

Built-in WebHub Event Macros

Version Notes

As of v1.650, the Start Macro no longer displays the "working" message, and parameters are expanded automatically.


STATICJUMP Macro

Creates a jump to the static version of the page. This is intended to take you from the dynamic version of your site to the static pages that were exported. The macro will link to ExportURL+ExportFileName.

Combine this with the STATIC tag to make the link "brand-resistant."  Use the ExportURL setting to have an additional path inserted before the filename.

Syntax

StaticJump|PageID[,command][|Tags]|VisiblePhrase

Example:

%=STATICJUMP|CREDITS|Credits for this site=%

%=STATICJUMP|Welcome|STATIC|Welcome to this site=%

STATIC tag

The STATIC tag insures that links in exported pages which are later branded will continue to lead to static pages. WebHub will strip 'STATIC' from <A> links in dynamic mode.  The static tag is ignored by browsers.

<A HREF="welcome.html" STATIC>Welcome to this site</A>

Implemented by

TWebApp


ExportURL Setting

The ExportURL defaults to blank ('').  To override, set it under AppID|Edit Defaults or the HTML|Defaults panel.

The ExportURL is used when WebHub creates links to static pages (see STATICJUMP).  The ExportURL is inserted before the page's ExportFilename.

Example

[TWebApp.Defaults]

ExportURL=/htdemo/brnd/branddir/

Given a page defined like this:

<h1>-Page:pgTest=,apath/afile.htm,,A Test Page</h1>

A STATICJUMP to pgTest with the ExportURL defined as shown above, would give you:

<A HREF="/htdemo/brnd/branddir/apath/afile.htm">A Test Page</A>


SUMMARY Macro

This adds text to the WebHub page footer (after all sections are sent).

Syntax

Summary|SummaryText

Example

Summary|A quick brown horse jumped.

See also:

Built-in WebHub Event Macros


TOGGLE Macro

Toggles the value of the named Checkbox between True and False.

Syntax

Toggle|VarName

Use this to reverse the value of a checkbox.

Example

%=TOGGLE|ImagesOkFlag=%

See also:

Built-in WebHub Event Macros


Component Properties

WebHub macro syntax can be used to display certain types of properties of certain types of components.  See how macros are decoded for the general rules.

Examples

%=AppRoot=%	-- used for graphics directory root

%=WebServer.Webtime=%	-- current time in GMT

%=WebServer.CgiRemoteAddress=%	-- surfer's IP number

%=Session=%	-- surfer's session number

For information on any property, search for that property in this help file.  All component properties are included in the searchable index.


Hub Panels

Connected	See which modules are connected.

Sessions	Work with surfer session data.

Requests	See traffic request statistics.

HTML 	Customize the HubApp.

Input/Output	See the input and output relating to your web application -- highly recommended for use during development.

Mail	Customize the TWebMailForm component in the HubApp.

Options	Set options for the Hub and runners.

The Hub was designed to be convenient on a wide range of monitor sizes.  Use the slider bars to optimize the display for your own situation.  Check Save Settings on the Options panel to retain your slider positioning.

You can control which Hub panels are included via command line parameters or through an optional setting. (v1.47+)


Hub: Connected Panel

| Overview | Current Panel | Setups Panel | Edit Setups Panel |

About the Hub and the Connected Panel

The Hub is the "process controller" or "traffic cop" within the WebHub System.  The Connected Panel provides an overview of which applications are running.

Use the Connected|Edit Setups Panel to an AppID for your application.  Then set the TWebApp.AppID property to match one of those.  (Do this inside Delphi, or using the AppID|Pick AppID verb at run time.)  You'll see that when the EXE containing the TWebApp component runs, it will load the files associated with the AppID and list itself on the Connected panel as the process responsible for the given AppID.

TWebInfo.WebSetups · AppID definition · TWebApp.AppID · EXE runs · Connected Panel knows to route requests to that EXE

When page requests come in from new surfers, the Hub does the following:

1. The Hub assigns a SessionID to the new surfer.
2. Based on the URL, the Hub determines which process the surfer should be routed to.  If there are multiple instances of the same AppID running, it takes that into consideration and routes the surfer to the least busy instance.

Special Cases

•	If no apps are available within the timeout period, the runner will return an error message.

•	If the AppID is left blank, the [WebSetups] are searched for the first available match on runner 	name.  If one is found, that AppID is assigned.

•	If the runner isn’t listed in [WebSetups], the hub defaults the AppID based on the WebAppID 	setting, as defined on the Hub's Options|Defaults panel.

•	If the AppID is equal to the HubAppID, the process will be HUB.EXE and the Hub will process 	the request internally.


Hub: Connected: Current Panel

| Overview | Current Panel | Setups Panel | Edit Setups Panel |

The Connected|Current panel shows the apps that are currently running and shows statistics on each app.

Connected Panel Columns

[#]     	The [#] counts the number of updates received from the custom EXEs and the runners, which inform the hub of their status every 1.5 seconds. The number's value has no significance.

[Process]	Name of .exe containing the TWebCommandLine component

[AppID]	AppID to be routed to that process

[Handle]	Handle to process

[LastAvg]	Average time in milliseconds between the last 10 page requests.

[Calls]	Total calls since WebApp started

[Running]	Number of page requests currently being served by WebApp

[Errors]

[Exceptions]

[Elapsed]	Number of seconds since WebApp started

Toolbar

Many of the following features apply to the currently selected process.  Use the mouse to select a process.

	Click this button to Exit the Hub.
	Click this button to Change the toolbar mode between "Toolbar" and "Verbbar."  The Toolbar is context sensitive to which Panel you are on.  The Verbbar shows the verbs for a particular component.  Programmers who want this functionality in their own applications should use the TtpComboBar component.
	Click this button to activate the selected process on the Connected|Current Panel.  The process will be brought into focus.  This is handy when you are running a lot of processes.
	Click this button to minimize the selected process on the Connected|Current Panel.  If the process was running in the tray, it will return to the tray.
	Click this button to terminate the selected process on the Connected|Current Panel.
	Click this button to delete the selected process from the Connected|Current Panel. If the process is hung, it will not reappear.  If it is active, it will appear again within 1.5 seconds.
	Click this button to reset the statistics for the selected process or runner.
	Click this button to toggle the display of the runner details.
	Click this button to toggle the display of the traffic details.  Traffic details are displayed for the selected process.


Hub: Connected: Setups Panel

| Overview | Current Panel | Setups Panel | Edit Setups Panel |

This panel itemizes your active WebHub AppIDs, i.e. those that apply to your SetupID. This list is essential to the entire organization of WebHub. Each AppID connects to an INI file, which defines the application.

To select an application, click on its row in any column except the first raised one.

Toolbar

	Click this button to Refresh the entire list of setups by reading it from the hubmain.ini file.  Use this when you have manually edited that INI file.
	Click this button to run the selected application as the HubApp, temporarily.  The selected application's pages will be served directly.  When next time the Hub starts, it will revert to running the default HubAppID.
	Click this button to run the selected application as the HubApp, permanently.
	Click this button to set the WebAppID property equal to the selected application.
	Click this button to run the selected application.  For this to work, the Path\AppEXE must be filled in.  By default, the application will be run once.  If # is set to a higher number, then the application will be launched more times, as specified.
	Click this button to terminate all instances of the selected process.
	Click this button to toggle the display of full details for the selected process in a separate panel (below).  Use this on narrow screens to see everything about the selected process.

Speed Menu

Select an AppID and then right-click to get these options.

Run as HubApp	(above; same as on toolbar)

Edit INI File	Edit the INI file for the indicated AppID.

Edit Setups	Switch to edit mode.

Start Application	(above)

Stop Application	(above)

Default HubApp	Sets the HubAppID to the selected AppID.  This will also load the app into the Hub and make it available.  The HubAppID setting is persistent so the next time you run the Hub, the same AppID will load.

Default WebApp	Sets the default WebAppID.  The default WebAppID is used when the surfer doesn't specify an AppID on the URL.

[? TWebInfo.WebSetups]

[? SetupID]


Hub: Connected: Edit Setups Panel

| Overview | Current Panel | Setups Panel | Edit Setups Panel |

To make a new AppID, right-click on the panel and choose New Setup.  You can also add a row and enter this information manually:

• AppID The ID for the web application.  Example: TEST  [? TWebApp.AppID]

• AppDir The directory for the application.  If you are running the application as an NT service, this must be on a local drive.  Otherwise, you may use UNC notation.  The AppDir is where the application-level INI file must be stored, and it is the default location for WebHub-HTML files. Example: c:\webs\test\whubhtml\   [? TWebApp.AppPath]  [? ChunkDir]

• AppIni The name of your application-level INI file. Example: test.ini

The remaining entries are optional.

• AppRun If a runner comes in with this name and does not have an AppID specified, the page request will be routed to the indicated WebApp. You should generally leave this blank.

• AppClass This is the Delphi object class for your app object.  The default is TWebApp.  The TWebApp component uses this information to look for its Default settings in the application-level .ini file.  It will look first for its own type, and if not found, it goes back up the object hierarchy until it gets to TWebApp.  If it still hasn't found a .Defaults section, it will try to use the AppClass named here.  You may leave this blank.

• #  Number of instances of your WebApp to load when the Hub starts.  Blank is treated as zero.  Set this to 1 or more to have the Hub load your applications.  If the Hub is running as a service, the launched apps will also run as services.

• Path\App Param Full pathname to your .exe plus any parameters required.  Every element of the path must be in good 'ole DOS 8.3 format -- no spaces, no long names.  If you are running the Hub as a service, the file must be on a local drive.  Example: c:\ht\htexe\webapp.exe /ID:SHOWCASE.

The setup configuration is stored permanently in ht\hubmain.ini, in the [WebSetups] section.

Toolbar

	Click this button to Refresh the entire list of setups by reading it from the hubmain.ini file.  Use this when you have manually edited that INI file.
	Click this button to edit the href.ini file using Notepad.
	Click this button to edit the hubmain.ini file using Notepad.  Do this if you want to quickly delete several AppID definitions, or do a search and replace operation on your setups.
	Click this button to edit the INI file for the selected application.  You must have an AppID's row selected; you must have a valid INI file name defined by path and filename, and the file must exist.
	Click this button to associate the AppID with a different INI file.
	Click this button to associate the AppID with a different EXE file.
	Click this button to duplicate the selected AppID and INI file under a new name.
	(reserved) Click this button to create a new AppID and INI file.
	Click this button to delete the AppID definition and its associated INI file.
	Click this button to toggle the display of full details for the selected process in a separate panel (below).  Use this on narrow screens to see everything about the selected process.

See also: Steps for creating a new AppID


Hub: Sessions Panel

| Overview | Literals | Checked  | TextAreas  | StateInfo | Uploaded |

About the Sessions Panel

The purpose of the Sessions panel is to let you see the data associated with currently active sessions, e.g. their Literals, Checkboxes, TextAreas, and so on.

The WebHub Developer Package includes a shared panel called whSessio.pas which you can include in your own applications to put a Sessions panel in your own application.


Hub: Sessions: Literals Panel

| Overview | Literals | Checked  | TextAreas  | StateInfo | Uploaded |

Use this panel to view the Literals array for any Session ID. This allows you to "spy" on your site's visitors as they navigate through your site, and allows you to troubleshoot your literals settings.

To see the literals panel in action, load the FORM demo into Aserver and navigate through the demo. Watch the literals panel expand as WebHub saves your data.

Toolbar

	This button determines whether the list of session files is displayed. Turn this on during debugging, and off for best performance.
	If you have the first button turned on, you can additionally use this one to make the display of Literals, etc. change in real time.  Use this only when you need to see changes as they happen.
	Click this button to select session #0, which is the default session object.  You can then see the Literals, etc. for session 0.  This is for development/debugging.
	Display the Run Time Type Information dialog for the current session object.
	Save any changes you made to the Literals to the session object.
	Erase the current session object. You can highlight multiple session files in the list, and then erase all the selected files.
	This button turns on background deletion of session VAR files.  This is important for security reasons.  Configure the sweep interval and timeout on the Options|Defaults Panel. [? TWebVarsDelete class]
See Also:

[? TWHSession.Literals]


Hub: Sessions: Checked Panel

| Overview | Literals | Checked | TextAreas  | StateInfo | Uploaded |

You can view the Checked array for any surfer number. This allows you to "spy" on your site's visitors as they navigate through your site, and allows you to troubleshoot your checkbox settings

To see the checked panel in action, load the FORM demo and navigate through the demo. Watch the checked panel expand as WebHub saves your data.For more information about using the demos, visit:

http://demos.href.com/

See Also:

[? TWHSession.Checked]


Hub: Sessions: TextAreas Panel

| Overview | Literals | Checked | TextAreas | StateInfo | Uploaded |

You can view the TextAreas array for any surfer number. This allows you to "spy" on your site's visitors as they navigate through your site, and allows you to troubleshoot your TextAreas settings

To see the TextAreas panel in action, load the FORM demo and navigate through the demo. Watch the TextAreas panel expand as WebHub saves your data.For more information about using the demos, visit http://demos.href.com/

Toolbar

	Click this button to save changes to the textarea.
	Click this button to search for text within the textarea.
	Click this button to search and replace text.
	Click this button repeat your most recent search, or search and replace, operation.
	Click this button to toggle your search mode between single-file and all-files.  If it is on single file (icon shows single document), only the selected textarea will be searched.  If it is on all-files (icon shows three documents), then all textareas in the session will be searched.
	Click this button to change the font used in the editor.
	Click this button to decrease the font size.
	Click this button to increase the font size.
See Also:

[? TWHSession.TextAreas]


Hub: Sessions: StateInfo Panel

| Overview | Literals | Checked  | TextAreas  | StateInfo | Uploaded |

Use this panel to view Save-State data for each SessionID. Save-State data is the combination of the SaveState property for all TWebAction components used in the web application.

Toolbar

n/a
See Also:

[? TWHSession.SavedStates]


Hub: Sessions: Uploaded Panel

| Overview | Literals | Checked  | TextAreas  | StateInfo | Uploaded ||

If there have been any files uploaded during the last session, you will see them here.

Toolbar

	Delete the selected file, which has just been uploaded, from disk.
See Also:

[? TWebApp.UploadedFiles]


Hub: Requests Panel

| Overview | Latest | Recent | Hub | HubApp |

Toolbar

	When turned on, Hub traffic statistics are calculated and displayed.  Turn this off for faster performance.
	This button clears the statistical data.


Hub: Requests: Recent
Hub: Requests: Recent Panel

| Overview | Latest | Recent | Hub | HubApp |

This panel shows information about recent surfer page requests.

Date 	9/20/97

Time 	4:48:25 PM

Runner	runwin.exe

Session Number	1000

Complete CGI query string 	APPID:PAGEID:SESSIONNUMBER:

(the text after the ? in the URL).


Hub: Requests: Latest
Hub: Requests: Latest Panel

| Overview | Latest | Recent | Hub | HubApp |

This panel shows information about the most recent surfer's page request.

Runner:	name of the runner, e.g. runwin.exe.  If runner is (Nil), you may be using an obsolete runner.

Input: 	identifier for input stream

Output: 	identifier for output stream.  With cgi-win, this should end in .out.

AppID: 	Application ID as requested

PageID: 	Page ID as requested

Session#: 	Surfer's Session# as assigned

Command: 	Optional command string.  In this URL, the command is 'AnimationOff': http://www.abc.com/cgi-win/runwin.exe?SHOWCASE:speed:123:AnimationOff

Status:	• Sent -- sent to WebApp for processing

• Bounced -- bounced to another server.


Hub: Requests: Hub Panel

| Overview | Latest | Recent | Hub | HubApp |

Calls	Total number of calls from new surfers to any app, including the those running inside and outside the Hub.

Running	Number of active page requests.

TripTime 	This is defined as the number of milliseconds between page requests from the same surfer.  Use this with a :speed page for performance testing.  ppd stands for Pages Per Day.  FYI, you can view this status information using a web browser.  See the built-in page called Status, e.g. HUBAPP:STATUS. All stats are calculated for 10-in-a-row to minimize reporting of highly unusual cases.

TripLast10	Speed for last ten page requests

TripPeak10: 	Highest speed; reset when you Clear.

TripMax10: 	Highest speed; reset only when Hub starts.

Overall Average: 	As stated!

ExecutionTime 	This is defined as the number of milliseconds required to create the page by the WebHub components.

CloudFactor: 	This is equal to TripTime divided by ExecTime and indicates how much of the trip time is based on network transmission relative to actual web page calculation time.

BusyRate:

Exceptions: 	Number of exceptions.

Debug:


Hub: Requests: HubApp Panel

| Overview | Latest | Recent | Hub | HubApp |

This panel displays the same information as the Hub panel, except that these statistics apply only to pages served by the App running inside the Hub.  The App-Inside-The-Hub is known as the HubApp.

See also: HubAppID Setting


Hub: HTML Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The HTML panel gives you access to the commonly used features associated with building a WebHub application.  As the chart below indicates, the component associated with the HTML panel is the TWebApp — the web application object.

Panel	Associated Property	Purpose

Files	[? TWebApp.Files]  	Define and edit HTML files containing the web pages of the application.

Pages	[? TWebApp.Pages]	Reference to all pages defined in the application

Chunks	[? TWebApp.Chunks]	Reference to all HTML chunks defined in the application.

Macros	[? TWebApp.Macros]	Reference to all macros defined in the application.

Media	[? TWebApp.Media]	Reference to cycling list / media servers.

Defaults	[? TWebApp.Defaults]	Define defaults for the web application.

Errors	[? TWebApp.Errors]	Reference to errors found in the application.

See also:

WebHub HTML Editor

Built-in WebHub Macros


Hub: HTML: Files Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

Use the Files panel to maintain the list of files that contain HTML data for the web application, and also to edit the contents of those files.

Toolbar

	Click this button to refresh the web application, reprocessing all files listed. This is equivalent to AppID|Refresh.  This will read all the files from disk, updating the definitions of pages, chunks, macros and events.  Refreshing the application always makes the page definitions on the Pages list synchronized with the information in the HTML file.  Simply saving the HTML file does not update the Pages list.
	Click this button to export all web pages that are associated with static HTML filenames.  This is equivalent to AppID|Export Pages.
	Click this button to edit the application's INI file with notepad. This is equivalent to AppID|Edit INI File.  Use this when you want to see behind the scenes to find out exactly what is being stored about your application.
	Click this button to display the HTML editor.
	Click this button to zoom the HTML editor to its largest size.  This will hide the detail about the file names listed.
	This button applies if you are not "zoomed" and therefore have room to display more information about the files.  Click this button to display the page defaults that are being assigned to all pages in the selected file.  You can also edit defaults by using AppID|Edit Ini File and editing the [TWebApp.Files] section in notepad.
	Click this button to make the panel sizes adjust automatically for optimal display of the files list and the HTML editor.  Alternatively, move the slider bars manually to resize the panels.
	Use this button to change or add entries to your files list.   Note that this button acts differently depending on what is currently selected in the file list grid.  If you are on a row that lists a FileID, it will let you browse your directory to find a file to link to.  The selected file will be assigned to the current FileID.  If you are on a blank row, you will also browse, but when you select the file, it will automatically add a corresponding FileID.
	Use this button to delete the selected row from the files list.  This does not delete the file, it just removes it from the list.
	Use this button to delete the selected row from the files list and from disk.

Whenever you add, change or delete entries in the Files list, you should press the [Save] button to save your work.  Otherwise the change is only temporary and the next time you run the program, the prior Files list would appear!

Note: the Files panel is the property editor for [? Files Property of TWebApp].  This property editor is accessible under AppID|Edit Files and also in the Delphi design environment, under the TWebApp's right-click menu.

See the HTML Editor help screen for information about the interface for editing the content of the files.

See [? Files Property of TWebApp] for information about defining FileIDs, filenames and file-level defaults.


Hub: HTML: Pages Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The Pages Panel displays all the PageIDs within the active web application.

Toolbar

	Click this button to refresh the page list. Use this when you change the [TWebApp.Pages] list, or the page section definitions, in the INI file manually.
	Click this button to export all web pages that are associated with static HTML filenames.  This is equivalent to AppID|Export Pages.
	Click this button to jump to the file which defines the selected page.  It is equivalent to selecting the page, right-clicking and selecting Goto File from the speed menu.
	Click this button to display the details for the selected page, the page defaults, and the content for the page-chunk.
	Click this button to export the selected page.  This requires that the ExportFilename be filled in, and that you have defined the ExportDir default.
	This button tests the selected page.  If you have the Output display on, you will see the result in the Output panel.  If you have previewing on, you will be able to browse the result in the Preview panel.  In any case, output will be sent to the sample output file as configured on the Options|Defaults Panel.
	Click this button to browse the exported file associated with the selected page.  This requires that the ExportFilename be filled in and that you have exported the page already.
	Use this button to edit the exported file.
	Use this button to browse your local directory and choose a filename for exporting the selected page.

If you click the Save button, you will write the page definitions as-is to your application-level INI file.  That is handy if you have just customized the settings, for example, if you filled in export filenames for all pages.  NB: the saved pages list will override any page definition you subsequently make in your HTML files.  If you accidentally save your pages list and later decide you need to recalculate it based on information in your HTML file(s), just edit the INI file manually and delete the entire [TWebApp.Pages] section.

Detail - Page Sections Panel

Use this panel to view or edit the page section definitions.  The page section definition determines what chunks comprise the web page.  Select the PageID you want to examine; its data will display on the right.  Right-click in the page section area for more features including reordering page sections.

If you change the page definition, click the [Save] button to write the definition to the application-INI file so that it will be available the next time you load/run the application. [? TWebPage.Sections]

Detail - Page Defaults Panel

Use this panel to view or edit the defaults for the page object.  These are optional and often blank.  Page defaults are a way of setting attributes for a page. You can then generate your HTML conditionally, based on those attributes.  See the PAGEDEFAULT macro.   [? TWebPage.Defaults]

Detail - Chunk Panel

Use this panel to view the contents of the page/chunk.  If you want to edit, use the Goto File icon on the toolbar.


Hub: HTML: Chunks Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The Chunks Panel displays the chunks currently defined in your web application.

All pages are considered chunks (but not vice versa).  You can include the content of one page on another by calling its ID, e.g. %=pgFEEDBACK=% would include the feedback page's content.

The most important difference between the two is that only a page can be invoked directly from the URL.  A chunk can only be called from within a page. So a surfer can request the page "pgFeedback" but not the chunk "chPageHeader."

Toolbar

	Click this button to refresh the page.
	When the button looks like this, you will see only chunks displayed in the list.
	When the button looks like this, you will see chunks and pages displayed in the list.
	Click this button to go to the file where the chunk/page is defined, so that you can edit it..

[? TWebApp.Chunks]


Hub: HTML: Macros Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The Macros Panel displays the text-substitution macros currently defined in your web application.  This includes macros defined in HTML and in the INI file.

The definitions are read first from the HTML files and then overridden if duplicates are found in the INI file.

The advantages to defining macros in HTML are that you can share the HTML file and its definitions across multiple web applications, and that you can place the definitions near the chunks where the definitions are used.  On the other hand, some people prefer the convenience of editing the macro definitions through the Macros Panel.

[? TWebApp.Macros]


Hub: HTML: Media Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The Media Panel lets you maintain a cycling list. While this was originally designed to support multiple multi-media web server machines in a cluster, it can be used for any situation where you want to rotate through a list.  See the ADV demo for an example using ad rotation.

Use %=media=% to reference the list.

See [? TWebApp.Media] for a complete example that shows how to use a media list for ad rotation.


Hub: HTML: Defaults Panel
HTML|Defaults Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

How to Configure Application Defaults

Use the HTML Panel, Defaults tab, or select AppID|Edit Defaults, or use the TWebApp.Defaults property editor.

Settings

AppPath	Path to application INI file.  As of WebHub v1.36, this is no longer written to the application-level INI file.  If you have an AppPath entry from a prior version, you should delete it.

  AppPath will always equal the location of the INI file.

AppRoot	Optional setting which defines the TWebApp.AppRoot property. It is typically used to define the root path for static files such as graphics, audio, video, etc.  AppRoot supports SetupID, and if you have to support multiple machines with different paths, that is the easiest way to handle varying paths.

[TWebApp.Defaults]

AppRoot.Home=/customerA/	// SetupID = Home

AppRoot.Public=/	// SetupID = Public

<h1>-Macros</h1>

mcImgDir=%=AppRoot=%images/

BrandDir	Files displayed by the BRAND macro must be located relative to this directory

CgiHideHandle	Sets the TWebApp.CgiHideHandle property when the application object refreshes.

CgiUseAppID	Sets the TWebApp.CgiUseAppID property when the application object refreshes.

CgiUseFilter	Sets the TWebApp.CgiUseFilter property when the application object refreshes.

CgiUseHandle	Sets the TWebApp.CgiUseHandle property when the application object refreshes.

ChunkDir	Path to the HTML files.  By default this will equal the AppPath, i.e. the location of the INI file.  ChunkDir respects SetupID.

[TWebApp.Defaults]

ChunkDir.Home=f:\customerA\whubhtml\	// SetupID = Home

ChunkDir.Public=d:\whubhtml\	// SetupID = Public

ExportDir	Exported HTML files will be written to this directory.

Frontdoor	Defines the PageID that a new surfer will go to, regardless of what PageID is specified on the URL.

Homepage	Defines the PageID that will be used if none is specified in the URL. It's the "default home page" for the application.

ImportPageFooter	Name of the chunk which will be used for section #3 on each page, by default.  May be left blank.

ImportPageHeader	Name of the chunk which will be used for section #1 on each page, by default.  May be left blank.

MacroChunkBegin	This defines the tag which indicates the beginning of a Chunk.

MacroEndBuffer	This defines the tag which indicates the end of a page or chunk.  You do not have to mark the ends of your pages and chunks unless you want to ensure that there are no trailing blank lines.

MacroEndMarker	This defines the tag which indicates the end of a chunk or page definition.

MacroPageBegin	This defines the tag which indicates the beginning of a Page.

MacroSectionBegin	This defines the tag which indicates the beginning of macro definitions.

Next	This phrase is used for automatic sequence buttons, for the 'next' link.

Prev	This phrase is used for automatic sequence buttons, for the 'previous' link.

Shutdown	This defines the keyword which will shut down the application if passed as the WebHub OptionalCommand. It is case sensitive.  Recommended: change this to anything other than the default for security reasons.

Stop	This phrase is used for slide show sequences, including the speed test.

Up	This phrase is used for automatic sequence buttons, for the 'up-to-higher-level' link.

YesNoString	This phrase determines what is displayed for Checked/boolean values.

Where the Data is Stored

Values are written to the [TWebApp.Defaults] section of the application-level INI file. At run time, the data is on the TWebApp object, Defaults property.

See Also

[? Defaults Property of TWebApp]


Hub: HTML: Errors Panel

| Overview | Files | Pages | Chunks | Macros | Media | Defaults | Errors |

The Errors Panel provides a reference to errors found in the web application, including:

• Files from the [TWebApp.Files] list that do not exist.

• Errors found when refreshing the app

• Additional custom errors defined by the programmer.

Toolbar

	Click this button to refresh the web application, reprocessing all files listed. This is equivalent to AppID|Refresh.
	Click this button to update the errors list.
	Click this button to erase the errors list.

[? TWebApp.Errors]


WebHub HTML Editor

WebHub provides its own HTML text editor which allows you to quickly make changes to your HTML files. It offers a variety of features to make it easy for you to create and maintain WebHub-HTML files.  The features are accessible through the toolbar and through the right-click menu.

Saving and Editing Features

	Save	Writes the file to disk.
	Edit	Allows you to edit your HTML file using the HTML editor of your choice (like FrontPage, Fusion, etc.)
	Reload	Reloads a file you edited with a custom HTML editor back into WebHub.

Text Searching Features

	Search	Allows you to search for a particular text string.
	Replace	Searches for a particular text string and replaces it with another.
	Repeat	Repeats the Find or Replace option you just performed.
	Multi-File Search	Toggles between applying Find and Replace changes to only the current file or all files in the app.
	Go To File	The webhub editor can take you from where you're using a chunk to where it's been defined.  Press [Ctrl-G] for this feature.
	Back	Press [Ctrl-B] to go back where you were before using Ctrl-G.
Typing Shortcuts

Ctrl-I	The Insert Markup feature provides shortcuts for all common WebHub requirements.  The templates are fully extensible.
Ctrl-H	Insert Chunk reference: this will popup the chunks editor while you're editing a file, allowing you to speed-search a chunk and insert a reference to it in macro syntax.
Ctrl-Up/Ctrl-Down	Scroll through the file without moving the cursor.
Ctrl-T	Delete word at cursor.
Ctrl-Y	Delete line at cursor.
[F4]	Duplicates the current line.
Appearance Features

	Font	Allows you to search for a particular text string.
	Decrease	Decreases the font size by two points.
	Increase	Increases the font size by two points.
Color Syntax Highlighting

	Paint	The Webhub files editor (v1.10+) features color syntax highlighting.  The colors are fixed to red for special lines, green for HTML tags, blue for WebHub macros and fuscia for WebHub Comments.  The Editor's paintbrush icon lets you toggle between colorizing all text, only "special" lines, or nothing at all.  Color syntax highlighting is not supported in NT 3.5x


Markup Templates
Markup-Templates

The Webhub HTML editor v1.10+ features templates which can be easily customized and switched on the fly.

Using a Template Shortcut

Use the right-click menu, select Insert|Markup and then choose the desired item from the list.

Alternatively, if you know the keyword for the shortcut you want to access, use [Ctrl-I] as follows.  If the cursor was positioned on a shortcut letter or word that you've specified in the markup template, the shortcut word is replaced by the template text. You need not select shortcut words, the cursor just needs to be on or next to them. If you were not near a shortcut word, a popupmenu will appear to let you choose from the available code fragments.  If you select text before pressing Ctrl-I and the text is not a template shortcut you'll be able to pick from the popup menu and have the markup wrap around your selection.

WebHub templates are inserted WITHOUT breaking the line you were on.

Setting the Template

During installation, the default template is set to ht\htexe\webhub.txt.  You can change that from the right-click menu within the editor.  Select

Insert|Markup Template...

Writing your Own Template

The syntax for the template files was inspired by Borland's .DCI files.  One difference is that WebHub uses the '`' character to specify the cursor insertion point.

To get blank lines at the end of your code fragments, use one or more lines containing just '-' a single dash.

Template Entry Syntax

[keyword | Description]

template text

Example Template Entry

[full | Page declaration (full)]

<h1>-Page:`id,alias,exportfilename,,description</h1>


Event Macros Property Editor

The TWebApp|Edit Events verb displays a dialog box from where you can maintain the list of event macros associated with an AppID.  Select AppID|Edit Events to access this feature from a running WebHub application.

The corresponding INI file section in the application-level INI file is [TWebApp.Events].


Hub: Input/Output Panel

| Overview | Input | Output | Preview |

The Input/Output Panel shows you the Input and Output related to the current page request.


Hub: Input/Output: Input Panel

| Overview | Input | Output | Preview |

Toolbar

	Click this button to toggle whether the input information is displayed.   If you are testing pages from a web browser, then the input comes dynamically from that test.  If you are testing pages using the Test verb, then the input comes from the InputSample file (ht\samplews.ini by default).  The InputSample filename is set on the Options|Default Panel.
	Click this button to erase the input panel.
	Click this button to edit the InputSample file with Notepad.

The WebHub VCL Package  includes a file named whAppIn.pas,

 which you can use to add an Input Panel to your own application.


Hub: Input/Output: Output Panel

| Overview | Input | Output | Preview |

If the [Show Output] button is on, the memo field will display the final HTML generated for the web page, exactly as it would be sent to the surfer.

Toolbar

	Click this button to toggle whether the output information is displayed.  You can test pages using a web browser, or using the TWebPage|Test verb.
	Click this button to turn on tracing/debugging of WebHub macro syntax.
	Click this button to synchronize the default browser with any output shown in the output panel.  Each time you test a page, the web browser will display the output.  Use this when you are testing with the TWebPage|Test verb to see the HTML fully rendered, i.e. when you are testing without an active web server.
	Click this button to erase the HTML from the output panel.
	Click this button to write the contents of the output panel to a temporary file, and then automatically load the file for display in the default web browser.
	Set the default browser used by WebHub equal to the default web browser on your workstation.
	Set the default browser to Microsoft Internet Explorer.  "Shell Execute" is used to control this browser.  If .htm and .html file extensions are not associated with IE then this approach may not work.
	Set the default browser to Netscape Navigator.  "DDE" is used to control this browser.
The WebHub VCL Package includes a file named whAppOut.pas which you can use to add an Output Panel to your own application.


Tracing/Debugging Macro Syntax

This feature lets you see "backstage" into WebHub's expansion of macro syntax, so that you can more easily trace the behavior of your W-HTML code.

The trace will be displayed on the Output Panel.

To activate this feature, turn on the the [Trace] button on the Input/Output|Output Panel.  You will then see this extra toolbar at the top of the output panel:

• Macros : Trace into text-substitution macros.

• Chunks: Trace into WebHub chunks, including those you would think of as pages.

• Components : Trace into WebHub component calls.

• Text : Display the HTML "text" between macro calls.  This will add "the content" of your site into the display.  Try keeping this unchecked for a simple trace.

• Tails: Displays the "end" message that corresponds to the end of each macro, chunk or component.

Trace Modes

• If Trace is on, and Show Output is off, you will get a brief overview without any extra HTML.

• If both Trace and Show Output are on, you will see the full HTML, with comments describing the trace data.  Note: this can break perfectly good HTML and JavaScript, so use it with care, during testing only.  This feature is included so that you can view the trace information remotely (see below).

What can "break" due to tracing

Anything that depends on an HTML comment can be "broken" by tracing. In addition, you may not be able to submit forms from a page containing trace- output of a form built using the %=WHERE=% or %=ACTION=% macros (use the INPUTFORM macro to avoid this particular scenario) .

To avoid getting stuck, you might want to add a %=CLEAR|WantToTrace=% to your homepage or some other central page so that you can easily turn off tracing.

Another option is to put %=TraceOff=% before tags that would get broken by the trace and to re-enable the trace thereafter by repeating the %=IF|WantToTrace|%=TraceOn=%=% in your document. This will let you trace everything on a page while protecting javascript or form sections.

For Remote Use of Tracing

The macro %=TraceOn=% will activate the Trace button.  The macro %=TraceOff=% will deactivate the button. You can use these in combination with a admin-only page to conditionally enable or disable tracing.  Consider adding the following logic to your page header, where "wantToTrace" is a checkbox that you set up:

%=IF|WantToTrace|%=TraceOn=%=%

The CMDHAS macro provides a good way for you to integrate remote tracing into a WebHub app. By using %=CMDHAS|Debug314|%=TraceOn=%=% you could conditionally enable a remote trace from afar. (In this example, it would be enabled if the URL included the command string 'Debug314'.)  For security reasons, be careful to invent obscure names for any "admin-level" commands, and it is advised that you use them only on protected pages.

v1.497+


Hub: Input/Output: Preview Panel

| Overview | Input | Output | Preview |

If the [Show] button is on, this panel will act like a web browser - showing you the web pages as they are created, letting you follow links and even post data.

If you have a large screen, pop out the Preview Panel so that you can have it on the screen next to the HTML|Pages panel.

Toolbar

	Click this button to toggle whether the output information is previewed.  You can create output by requesting pages from a web browser, or using the Pages|...|Test menu option, or by going to the HTML|Pages panel, choosing a page, and clicking the lightning bolt.
	Click this button to erase the preview panel.
	Click this button to delete any data stored for the current session.  Session #1000 will be used by default.
	Click this button to reload the page.
	Use this button to go back to the prior page.
Once you start using the preview panel, you will see that a URL  history is maintained in the drop-down list:

You can enter an AppID:PageID request in this box, and you can also select items from the history.

The WebHub VCL includes a form named fmHtmlVw.pas which you can use to add a Preview Panel to your own application.  It requires the THtmlViewer component, written by David Baldwin. This component is available through HREF's online store.  See http://www.href.com/HTMLVIEW

v1.497+


Hub: Mail Panel

Use this panel to configure and test the TWebMailForm component.

When the TWebMailForm component executes, it sends an e-mail message.  In its simplest configuration, the message contains HTML form values ("literals").  The Mail Panel enables you to configure the TWebMailForm component for the various messages you might want to send.  It also adds two features to the native capability of the component:

• logging of surfer data that was e-mailed

• the ability to send "form letters" that use your own style for the message.  The form letters may use WebHub syntax to include %=firstname=% or execute web action components.

Note that the Mail panel works with both static and dynamic web sites.  You can launch into it from a static or a dynamic web page, and you can return to a static or a dynamic web page when processing is complete.  There are several WebHub demos that show how to use this component: FEEDBACK, HTEM and HTLS.

Make sure that the TWebMailForm component is passed a command that tells it which configuration to use.  You can do this in either of two ways.

1. Pass the command when the component executes.  This is recommended when you have only one configuration, or when you are using dynamic response pages that are different for each configuration.  ("easier" "less flexible")

%=webmailform.execute|keyword=%

2.  Pass the command via the WebHub OptionalCommand in the URL.  This is recommended when you want a generic "Sendmail" page that supports multiple configurations. ("slightly harder" "more flexible")

<FORM METHOD=POST ACTION="%=ACTION|SENDMAIL,keyword=%">

Regardless of which approach you choose, configure the 'keyword' as shown below.  You may have as many different keywords (for different messages) as you want.

Complete Examples/Instructions for the second approach: For use with Static HTML Files | For use with Dynamic Web Pages

Toolbar

	Click this button to reload the configuration information from an INI file that you changed manually.  This will cancel any changes you may have made.
	Click this button to test the TWebMail component. (reserved)
	Click this button to test the sending a message based on the currently selected configuration.  Recommended: turn on the display button when you do this.
	Click this button to display the dialog between the TWebMail component and the mail server.  Use this when troubleshooting.
	Click this button to erase the displayed dialog.
How to Configure a Keyword

  To enter settings for a keyword (for example, "feedback"), enter that keyword into the drop-down list and press Enter.  Then fill out the rest of the form. The required fields have uppercase prompts.

Host	Your mail host, e.g. mail.sonic.net

Port	The port number for email with your host. Use 25 if you are not sure.

From	The email address of the sender.

Name	The name of the person sending the message.

To	The email address of the recipient.

Subject	The message subject.

Cc	Carbon copy to this email address.  Use semicolon to separate multiple cc's.

Bcc	Blind carbon copy to this email address.  Use semicolon to separate multiple bcc's.

Template	Name of text file which will be used as the basis for the message.  Enter an absolute filename or one that is relative to the ChunkDir for the web application.  Example: letters\quote.txt

Include	List of data categories to include in standard messages.  This does not apply if you use a template.  See the hints for syntax.

TextAreas	List of textareas to include in standard messages.  This does not apply if you use a template.  Use 'ALL' to include all textareas.

ExcludeLiterals	List of literals to exclude from standard messages.  This does not apply if you use a template.

NextPage	Optional web page to bounce to when email has been sent.  Use an HTTP:// address or specify a WebHub PageID within the current web application.

LogToFile	Yes/No

LogFilename	Enter a complete filename to be used for logging.  Recommended: use a .txt or .log file extension.  Example: c:\htdocs\logs\feedback.txt

LogLiterals	List of literals to log.  Use a semicolon as a separator between literals.  You will get the date and time in the log file automatically.

Redirection using ^

If you want a value to be filled in based on a literal, use a ^ after the literal name.  For example, to set the NAME to the literal named "lastname", use NAME=lastname^.

 As soon as you start typing data into a configuration, the Save button will get a dark outline to remind you that there is something to save.  Remember to click Save so that your settings are written to the INI file for later use.

If you need to cancel your typing, use the Undo button.

To delete obsolete configurations, use this Delete button.  It will delete the currently selected configuration.

Note to programmers: WebHub maintains a section called [WebMailForm.Settings] with the list of configuration keywords.

The WebHub Developer Package includes a shared panel called whMail.pas.  Include this in your own applications when you want a MAIL panel.

[? TWebMailForm Class]


TWebMailForm used with Static Files
TWebMailForm used with Static HTML Files

The "launch" page

This is your feedback page, which you design with your HTML editor of choice.  Here is a bare bones example:

<HTML><HEAD><TITLE>Feedback</TITLE><BODY BGCOLOR="#FFFFFF">

<FORM METHOD=POST ACTION="http://href.com/cgi-win/runwin.exe?hubapp:sendmail::feedback">

Enter message:

<TEXTAREA NAME=txtMessage ROWS=5 COLS=40>

</TEXTAREA>

<INPUT TYPE=SUBMIT>

</FORM></BODY></HTML>

About the ACTION tag

The ACTION tag determines what happens when someone submits a form on the web. It needs to point at your web application.  See Understanding WebHub URLs if you need information on constructing a URL for your situation.

Be sure to use double colons after the PageID as a placeholder for the session number.  The final phrase ('feedback') is the OptionalCommand which should match one of your configuration keywords.

The SENDMAIL page

You may use any PageID; SENDMAIL is just a suggestion.

The SENDMAIL page has to be within the web application called by your form action.  It should look like this:

<h1>-Page:SENDMAIL=,,,trigger the TWebMailForm component</h1>

%=webmailform.execute=%

Configuring the Feedback Keyword

You may use any keyword; Feedback is just a suggestion.

Follow the instructions here, or just read the hints as you go along.  Be sure to set NextPage equal to the full URL to your "thank you" web page, e.g. http://href.com/thanks.htm

We recommend that you use templates for your messages.

The THANK YOU page

Create this page using your regular HTML editor.  The surfer will arrive on this web page after the message has been sent. Here is a simple example:

<HTML><HEAD><TITLE>Thanks for the Feedback</TITLE><BODY BGCOLOR="#FFFFFF">

Thank you for sending us that feedback message!!

</BODY></HTML>


TWebMailForm used with Dynamic Web Pages

The "launch" page

This is your feedback page, which you design using the WebHub HTML editor.  Here is a bare bones example:

<h1>-Page:Feedback=,,,Feedback Page</h1>

<FORM METHOD=POST ACTION="%=ACTION|sendmail,feedback=%">

Enter message:

<TEXTAREA NAME=txtMessage ROWS=5 COLS=40>

%=txtMessage=%

</TEXTAREA>

<INPUT TYPE=SUBMIT>

</FORM>

About the ACTION tag

The ACTION tag determines what happens when someone submits a form on the web. It needs to point at your web application.  See Understanding WebHub URLs and the ACTION macro for background information on constructing a URL for your situation.  In the example above, the target PageID is 'sendmail' and the OptionalCommand is 'feedback'.  The OptionalCommand must match one of your configuration keywords.

The SENDMAIL page

You may use any PageID; SENDMAIL is just a suggestion.

The SENDMAIL page has to be within the web application called by your form action.  It should look like this:

<h1>-Page:SENDMAIL=,,,trigger the TWebMailForm component</h1>

%=webmailform.execute=%

Configuring the Feedback Keyword

You may use any keyword; Feedback is just a suggestion.

Follow the instructions here, or just read the hints as you go along.  Consider the NextPage prompt carefully.  You can either leave it blank and put the thank you message below the %=webmailform.execute=% line on the SENDMAIL page, or you can enter the PageID of a thank you page.  The latter is much better when you have to support multiple keywords that might need slightly different response messages.

To use the THANK YOU page shown below, set NextPage equal to THANKS.

We recommend that you use templates for your messages.

The THANK YOU page

Create this page using the WebHub HTML editor.  The surfer will arrive on this web page after the message has been sent. Here is a simple example:

<h1>-Page:THANKS=,,,Thanks for the Feedback</h1>

The following message has been sent to the webmaster:

<p>

%=txtMessage=%

<p>

<b>Thanks!</b>


TWebMailForm template
TWebMailForm Template Files

By using template files, you can completely control the content of the email message.  You may use WebHub macro syntax, and thereby expand macros, literals, textareas, and even trigger web action components.

Example: Simple Feedback Message (sent to webmaster)

FEEDBACK MESSAGE

From:    %=EMail=%
Subject: %=Subject=%

%=txtMessage=%

###

Example: Customer Service Message

Dear Customer,

Thank you for filling out our survey.  We will send
you information about %=radioProduct=% within
24 hours.  Thanks again for visiting our web site.

Customer Service

Example: Form Letter (sent to webmaster, cc to surfer)

%=webserver.webtime=%

Dear %=FirstName=%,

We have received the following feedback message from you.  While we can not respond to each message individually, we do read all messages and thank you for your time.

Message:
%=txtMessage=%

Bye for now,

webmaster@mail.href.com

HREF Tools Corp.

Example: New Technotes Question (sent to technical support department)

%=txtQuestion=%

--
This message came through the HREF Tools Corp. TechNotes Web Application
at http://www.href.com.

Originator: %=Fullname=%
Mailto:%=email=%


TWebMailForm Logging
Using a Log File

The purpose of the log file is to provide historical data on each message that is sent. Here are example settings:

LogToFile=yes
LogFileName=c:\log\names.txt
LogLiterals=inEMail;inName

The log file will look something like this:

11/1/97 10:29:17 PM "ready","info@href.com","Michelle","555-555-1212"
11/1/97 10:30:17 PM "ready","ben@mail.href.com","Benjamin","707-542-0844"


Hub: Options Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

The Hub's Options Panels help you set the properties of Hub itself, plus those of the TWebInfo component.  You will find these settings saved in href.ini and hubmain.ini.

You can also configure the properties of the TWebInfo component by using the menu — Components|WebInfo.


Hub: Options: Startup Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

WebHub Central

Visible to Runners	Controls whether the Hub accepts incoming requests or not (default on).  If this is checked, the Hub functions normally and requests are processed.  If this is unchecked, you will get an error message as if the Hub were not running at all.

Accept New Surfers	Controls whether the Hub will accept new surfers (default on).  If this is unchecked, you will get an error message saying that the Hub has been suspended.

HubApp

Visible to Runners	Controls whether the Hub accepts incoming requests for the HubApp (default on).  If this is checked, the HubApp functions normally and requests are processed.  If this is unchecked, you will get an error message as if the HubApp were not running at all.

Accept New Surfers	Controls whether the Hub will accept new surfers coming into the HubApp (default on).  If this is unchecked, you will get an error message saying that the HubApp has been suspended.

Share Sessions	If this is checked, session data will be written to disk and may be shared between the HubApp and other modules on the system.  Those custom EXEs should have TWebApp.ShareSessions set to true.

Hub Startup

Start WebApps	If this is checked, the Hub will start your custom WebApps when it starts.  WebApps are itemized on the Setups panel. The Hub will try to start the indicated number of instances, but will not keep that number running or do any additional processing/error checking. Depending on your configuration, starting numerous webapps in this fashion may cause trouble, as they all try to read from the href.ini file simultaneously when the system starts up.  You may be better off writing a simple .bat file with a wait command between each call.

Start HubLog	If this is checked, the Hub will run HubLog.exe when it starts.

Fast Stringlists	The Hub will use a non-standard optimization for handling all TStringLists.

Hub Shutdown

Close WebApps	If this is checked, the Hub will send a message to all connected WebApps telling them to shut down when it exits.

Close HubLog 	If this is checked, the Hub will close HubLog when it exits.

Save Settings	If this is checked, your settings will be restored the next time the Hub runs. This includes settings on other panels as well.

Toolbar

	Click this button to refresh the TWebInfo component, reading in any changes you might have manually made to href.ini and hubmain.ini.
	Click this button to edit the hubmain.ini file with Notepad.
	Click this button to edit the href.ini file with Notepad.
	Click this button to edit the tpack.ini file with Notepad.  Settings for the Hub's form size and location are stored in this file.
	Click this button to change the font used throughout the Hub's user interface.


Wait Utility

The purpose of the wait utility is to create an intentional delay, typically from within a BAT file that is called when your system starts up.  For example, you may want to start one application, wait 10 seconds so that it has time to initialize, and then start another application.

Source Code

This will compile to a console application.  The filename is wait.dpr.

program wait;

{$APPTYPE CONSOLE}
{$A+,B-,D-,E-,F-,G-,I+,L-,N-,O-,P-,Q-,R-,S+,T-,V+,X+}

uses
  Windows,
  Sysutils;

begin
  writeln('Waiting '+ParamStr(1)+' seconds... (hit Ctrl-C to cancel)');
  sleep(StrToIntDef(ParamStr(1),0)*1000);
end.

Precompiled Version

Posted at http://www.href.com/pub/source/wait/.


Hub: Options: Default Options Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

How to Configure Defaults when the Hub is Running

Go to the Options Panel, Defaults page.  Or use Components|WebInfo|Edit Defaults.  Be sure to click [Save] to save any changes you make on this panel.

How to Configure Defaults in the Design Environment

Select the TWebInfo component. Right-click and choose Edit Defaults.

Definition of Settings

AppLoading	System Message displayed when application is loading but not ready to serve pages.

CgiHttp	Used when exporting static web pages.  This should generally be set to '/'. [? CgiHttp property of TWebApp]

CgiPath	Used when exporting static web pages that link back into a dynamic WebHub system.  This should equal the path to your runner, e.g. 'scripts/'.

DemoRoot	Used to locate database files within the WebHub demos.  This setting may be deleted if you are not running the demos.

Digits	Number of digits in Session numbers.  See Understanding WebHub URLs.

EditTemplate	Name of the template file which gives you shortcuts when you use the HTML editor's right-click Insert Markup menu option.

HubAppID	Default HubAppID loaded when the Hub starts.

HubDirectory	Location of hub.exe.

HubNoSuchApp	System Message displayed when an AppID is request that is not defined on the Setups Panel.

HubSuspended	System Message displayed when the Hub is suspended from the Options|Startup Panel.

HubUI	Indicates which panels should be included as part of the Hub UI.   The choices are: Sessions,Traffic,HTML,InOut,Mail,Runners,MOTD.  You may include as many or as few as you like, comma separated, no spaces. You may also control panel choices via command line parameters. (v1.47+)

IniFilename	Name of the "hubmain" INI file.  You can point this at the href.ini file if you want to eliminate one file from your configuration.

InputSample	Name of the input file which is used during testing without a web server.

OutputSample	Name of the temporary output file used during testing.

Runner	Name of the WebHub runner used during exporting static web pages.  This should equal your runner name, e.g. 'runisa.dll'.

SessionLifeMinutes	Number of inactive minutes that Session VAR files exist before they are deleted by the Session Panel's background-delete cleanup process.  The default is 1440 minutes (24 hours).  Set this to a lower number to increase security.

SessionsDir	Location of Session VAR files.

SessionSweepIntervalMS	How often, in milliseconds, the background-delete process which check for outdated session VAR files .

SetupID	WebHub's name for the machine.  Work with this when you want to share application-INI files between machines with different directory structures.

whBrowserInfo.IniFileName

The name of the browser capabilities INI file, e.g. c:\ht\brwsrcap.ini.  This file initializes the TWhBrowserInfo component.

SetupID

Some of the settings respect the SetupID modifier.  See AppRoot for an example of a setting that respects SetupID. [? AppRoot property of TWebApp]

Settings are Saved in href.ini

Values are saved in the [WebHub] section of the windows\href.ini file.

[? TWebInfo Properties -- WebDefaults]


HubAppID Setting

The HubAppID setting defines the AppID which the Hub will serve.  This works because the Hub contains a TWebApp component, just like the one used in Delphi to build custom web applications.

By default, the HubAppID equals 'HubApp'.

Picking an AppID to Run Temporarily

The quickest way to run an AppID in the Hub is to go to the AppID menu. (The name of that menu changes depending on which AppID is loaded, but you can find it because it's always the one between 'File' and 'Components'.)  Select Pick AppID.  From the resulting list, choose the desired AppID and click [Ok[.

Changing the HubAppID "Permanently"

Go to the Hub's Connected|Setups Panel.  Find the AppID that you want to use inside the Hub.  Select that row in the grid — make sure the row is outlined to indicate that it has been selected.  Right-click and notice two choices: Run as HubApp and Default HubApp on the menu.

Run As HubApp — this is temporary.  Then next time you restart the Hub, it will revert to the default HubAppID.

Default HubApp — this is permanent.  The next time you restart the Hub, it will use this AppID.

Checking your HubAppID

Go to the Hub's Options|Defaults Panel or select Components|WebInfo|Edit Defaults from the menu.  Look for the setting called 'HubAppID'.

Recommended HubAppIDs

HubApp — small app, quick to load. The SYSTEMINFO page is useful for testing.

AppID — empty app, quickest to load, zero features.  Use this when you don't want the Hub doing anything extra.

Your Own ID — use when you want your AppID to run inside the Hub, or when you want to use the Hub to edit the HTML files associated with this ID.  Do not use when you want your AppID to be dynamically served outside the Hub.

Common Mistake

The most common mistake is to have the same AppID running inside and outside the Hub.  This happens to Delphi programmers who meant to use the Hub temporarily as an editor and forgot to reset the HubAppID.  The problem is that when a surfer requests a dynamic page, the Hub will serve that page itself (ignoring the custom EXE).  Although the HTML will appear, no custom components will execute and it will appear that the application is broken.  The solution is to set the HubAppID permanently back to 'HubApp' as described above.  Check the Hub's Connected|Current Panel to see make sure that your HUB process is running a different AppID from any custom processes.

Limitations for Apps Running Inside the Hub

You can not add any custom code to the Hub, so HubApps are not appropriate when you want database and other advanced features.  Furthermore, you can only run 1 HubApp.

Running more than 1 AppID

If you are wishing you could run multiple HubApps, use webapp.exe.  You may run webapp.exe multiple times, up to the capacity of your Hub.  The source code for webapp.exe installs to ht\htdemos\webapp.  You may also download a precompiled copy of webapp.exe from http://www.href.com/demo-exe/.  Use the /ID parameter to set the AppID on the command line as follows:

c:\ht\htexe\webapp.exe /ID:AppID


Hub: Options: ServerIDs Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

ServerIDs let you name a combination of URL, path and runner for use in page definitions and JUMPs.  Use ServerIDs when you want to add a secure certificate to your site, or you want to support multiple web servers on the same machine, or you want to simplify linking to a WebHub application on another machine.

Explanation of Prompts

ServerID	This is the name of the ServerID.  Use any word.  Examples: PLAIN, SSL, SECURE, DEMOS, REMOTE.

Http	You only need to include the port in the URL if it is not already the default for the specified protocol.  For example, HTTPS inherently means using port 443, so adding it is unnecessary.  But while HTTP implies port 80, your web server may run on port 8010, thus you would need to specify this by including the final :8010/.

Examples: http://www.href.com/, https://www.href.com/, http://demos.href.com:8010/

cgi-path	This is the path to the runner, including the trailing slash.  Examples: cgi-win/, scripts/

webhub-runner.exe	This is the name of the WebHub runner, including the file extension.  Examples: runisa.dll, runwin.exe, runbin.exe

Example, for use with the "FASTCAR" demo

The FASTCAR demo requires that the following two ServerIDs be set up on your Hub.  You will need to fill in the Http, CgiPath and Runner settings based on how you have set up your machine. If you have a secure web server running HTTPS on your machine, use that for the SSL definition.  Otherwise, just use HTTP, so that you can see the FASTCAR demo work.

ServerID	Http	CgiPath	Runner

PLAIN	http://localhost/        scripts/	     runisa.dll

SSL	https://localhost/	scripts/	runisa.dll

The settings shown above are the default settings for use with Microsoft IIS.  If you are using O'Reilly's WebSite, use cgi-win/ for the CgiPath and use runwin.exe for the runner.  If you are using different paths or different runner names, make those adjustments as well.

Defining a Page to run on a ServerID

By using the PageDestination property, you can tell WebHub that a given page should run on a certain ServerID by default. Here is the general syntax:

<h1>-Page:PageID=(ServerID),,,description</h1>

The following examples show how you would set up two pages to use the ServerIDs set up above.

<h1>-Page:OrderForm=(SSL),,,description</h1>

// HTML for the Order Form here...

<h1>-Page:Welcome=(PLAIN),,,description</h1>

// HTML for the Welcome page here...

If you define a WebHub page with a PageDestination that includes a ServerID, as above, then all JUMPs (or GOs, HIDEs, or ACTIONs) to that page will run on the given server.

Jumping to a Page on a ServerID

%=JUMP|OrderForm(SSL)|Order Form on secure line=%

This is good if you want to give the user a CHOICE of which server to run on.

Subsequent WebHub page links will stay on the new server, until another explicit change.

[? TWebInfo.WebServers]


Hub: Options: Bounce-To Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

How to Set Up Maître d'Hub Mode

1. Define a ServerID for each machine in the cluster using the Options|ServerID Panel or Components|WebInfo|Edit Servers..

MACHINE1=http://secure.href.com/,bin,bin.exe
MACHINE2=http://www.href.com:80/,scripts,runisa.dll
MACHINE3=http://www.robmart.com/,scripts,runisa.dll

2: On the Options|BounceTos Panel, Indicate which of those should be cycled through for each AppID.  For example:

SHOWCASE=MACHINE1|MACHINE2|MACHINE1|MACHINE3

For AppID 'SHOWCASE,' this would place twice the load on machine 1 as on the others.

Put an asterisk (*) after a machine name to indicate that this ServerID is on the current machine and therefore the Hub need not issue an official bounce (to itself!) for this new session, but instead can just run the page request immediately.  This was implemented using a * rather than a list of IPs because you may be changing IPs for multi-homed setups.


Hub: Options: Runners Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

Use the Runners Panel to define a "runner override" when you want the name of a runner to determine which AppID is used for a new surfer request.

• You can give any runner a new name.

• You can install a runner in any directory that your web server respects.

For example, the runner named "services.dll" could be associated with AppID=OurServices and thereby take new surfers into the OurServices application.

Having separate runners for certain purposes enhances security and lets you publish shorter URLs.  If you use a runner override, you do not need to specify the AppID on the command line.

Using runner overrides is more flexible than setting WebAppID, because you can have an unlimited number of defaults.


Hub: Options: Messages Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

System Messages are sent when problem conditions are encountered.

Definition of Settings

Runner Timeout	After this number of seconds, the runner will return a timeout message if the web application has not yet completed the output document.  The default is 30 seconds.

Runner Options	(reserved)

Administrator E-Mail	Enter a phrase which will be used in the timeout messages.  Surfers will be told to contact this person in case of timeout.  Example: <A HREF="mailto:info@href.com">info@href.com</A>.

HubLog Machine	Windows-NT Name of Machine that runs the HubLog module.  Use a period ('.') to refer to the current machine.  If you are not running HubLog, this setting is irrelevant.

WebHub Machine	(reserved)

TimeOut Msg	This message is displayed when runner times out after N seconds.

NoHub Msg	This message is displayed if Hub.exe is not running.

Hub-Loading Msg	This message is displayed when the Hub is loading.

Hub-Suspended Msg	This message is displayed when the Hub is suspended.  See the [Activate Hub] button on the main Hub toolbar. *

No-Such App Msg	This message is displayed when an AppID is requested that can not be found under WebSetups. *

App-Loading Msg	This message is displayed when the custom EXE has started but is not fully ready yet.

App-Suspended Msg	This message is displayed when the custom EXE is suspended.   [? TWebCommandline.UseWebHub]

App-Shutdown Msg	This message is displayed when the EXE shuts down.   [? TWebApp.Defaults, Shutdown]

How to Customize the Message Files

If you just want to edit a single message, use Notepad or any text editor to edit the contents of the file. If you want to edit all of them, you can edit the files directory, or use the HtSys project to edit the chunks and re-export the files. We recommend you customize the message files to use your own domain name, graphics and font styles,  and adjust the page header and page footer to include your logo or other identifying information.

You can also delete the filename entirely and just put in a one-line message.

You can also enter a URL to bounce to when the error condition occurs. Start the URL with http:// or just a leading /.

Who Needs to Run the HubMsg service?

Anyone running a high-traffic production (live) server using a web server gateway interface other than ISAPI should download and install a copy of the HubMsg service.  The file is FREE to registered customers.  You should run it as a service that starts automatically when your system boots. It will ensure that the above system messages are available between the time that NT starts and the time that either your WebHub application server or The Hub starts, whichever comes first.  This is a very short amount of time, generally less than 10 seconds.  If you are not concerned about providing formatted messages during that time, then you do not need to run the HubMsg service.

Users of the ISAPI interface who have a runner dated prior to March 1999 should either run the HubMsg service or upgrade to a new ISAPI runner.

Macro Expansion capability

Because the message files are expanded during error conditions, only limited macro expansion is possible.
The following macros are available; see the chart below for specifics:

WHERE -- the URL that the surfer requested which led to the problem
ADMIN -- the Administrator as defined on the same panel
TIMEOUT -- the number of seconds set for the runner timeout. This is only available for messages sent by the runner.
APPID -- the AppID. This is only available for messages generated by The Hub or the application server, not the runner.


HubMsg Service - Installing
Installing the HubMsg Service

Usage

hubmsg -install	// installs the service

hubmsg -remove	// removes the service

After installing HubMsg, go to the Windows Control Panel and open Services.  Set the WebHub Service to start automatically on system boot, and then manually start it once.

How the Messages Work

A shared memory region is set up by the first process to run.  When an error condition is reached, the process will look in that shared memory region to find out which message to send.  If the memory region has not been set up, then a default short message string is sent.

The following processes will initialize the memory region if that has not already occurred:

• hub.exe,

• hubs.exe,

• runisa.dll dated after March 1, 1999, and

• any WebHub application server built with the v1.5+ components.

Page Code-Name	URL to bounce to	Dynamic File                             (Recommended)	Settings  Saved In	Message Sent by
HubTime	/HubTime.htm	\htdocs\htsysmsg\HubTime.txt	Registry	Runner
HubNone	/HubNone.htm	\htdocs\htsysmsg\HubNone.txt	Registry	Runner
HubLoad	/HubLoad.htm	\htdocs\htsysmsg\HubLoad.txt	href.ini	Hub
HubSusp	/HubSusp.htm	\htdocs\htsysmsg\HubSusp.txt	href.ini	Hub
HubNoApp	/HubNoApp.htm	\htdocs\htsysmsg\HubNoApp.txt	href.ini	Hub
AppLoad	/AppLoad.htm	\htdocs\htsysmsg\AppLoad.txt	href.ini	Web Application
AppSusp	/AppSusp.htm	\htdocs\htsysmsg\AppSusp.txt	href.ini	Web Application
AppShut	/AppShut.htm	\htdocs\htsysmsg\AppShut.txt	href.ini	Web Application
Where the file references are stored in href.ini:

[WEBHUB]

HubLoading=c:\htdocs\htsysmsg\hubload.txt

HubSuspended=c:\htdocs\htsysmsg\HubSusp.txt

HubNoSuchApp=c:\htdocs\htsysmsg\HubNoApp.txt

AppLoading=c:\htdocs\htsysmsg\AppLoad.txt

AppSuspended=c:\htdocs\htsysmsg\AppSusp.txt

AppShutDown=c:\htdocs\htsysmsg\AppShut.txt

Where the file references are stored in the registry

[HKEY_LOCAL_MACHINE\SOFTWARE\HREF Tools\WebHub\Runner]

"TimeoutMsg"="c:\htdocs\htsysmsg\HubTime.txt"

"NoHubMsg"="c:\htdocs\htsysmsg\HubNone.txt"


Hub: Options: MOTD Panel

| Overview | Startup | Defaults | ServerIDs | BounceTo | Runners | Messages | MOTD |

MOTD	Message of the Day.  The text in this field can be displayed in your HubApp using %=MOTD=%.  Use this for quick messages that you want the webmaster to be able to insert.  This is limited to one line of text.

STRINGS	Same idea, but you may enter a much longer message.  Display this using %=STRINGS=% within your HubApp.

The WebHub Developer Package includes a shared panel called whMOTD.pas which you can include in your own applications to put a MOTD panel in your own application.


Pop out this panel
Pop out this panel!

If you have a large screen, you may find it very helpful to "pop" some of the panels out of their positions in the tabbed notebook, so that you can put them next to each other. For example, you might want to be able to see both the HTML|files panel and the Input/Output|Preview panel at the same time.

The way to pop out a panel is to put the cursor in the grey area just below the tabs. A special cursor (arrow with a rectangle) will appear as shown in this picture:

Click, and the panel will pop out.  You can return it later by clicking on the [x] close box for the popped-out panel.


Hub Combobar
ComboBar

The ComboBar is a combination of a Speedbar and a Verbbar.  The View menu lets you toggle between them, as does the change icon.

By default, the Combobar does not show in the Hub.  Turn it on with the View menu.

Programmers should note that you can add these controls into your own applications using the TtpComboBar component from TPack.


Hub Speedbar

Exit	The red door gives you a File|Exit shortcut.  Closing the Hub can trigger additional features, depending on what you have set on the Options|Startup panel.

Toggle	The "change" icon toggles the speedbar type between 'tool bar' and 'verb bar'.  The tool bar gives you access to a few handy 'verbs.'  The verb bar gives you access to all verbs, for all components.


Verbbar

The verb bar displays buttons for all the verbs for the current component.  You may need to widen the window to see all of them.

The current component is indicated by the third button; you should see its name as the button label.

To change the current component, click on that third button.


Hub Menus

• File Menu

• HubApp Menu

• Components Menu

• Pages Menu

• View Menu

• Help Menu


Hub: File Menu

The first section of this menu lists all TtpMemo components included in the .EXE.

WebMailLog	This refers to the memo field on the WebMail tab.

WebIniFileMemo	This refers to the right memo field visible on the HubApp Tab, which displays the contents of the .ini file coming from the web server for the current surfer.  You may want this turned on during testing, but never during production.  From this menu you can easily clear the contents of the memo field.

WebHtmlMemo	This refers to the left memo field on the HubApp tab.

DownWebApps	Stop all applications listed on the WebApps Tab

Start HubLog	Tells the Hub to start the logging module.

Down HubLog	Tells the Hub to stop the logging module.

Terminate All 	Exit, closing the Hub, all WebApps and HubLog, regardless of option settings.

Terminate Hub Only	Closes the Hub only, leaving everything else running..

Exit	Close the Form


Hub: HubApp Menu

The name of this menu depends on the current HubAppID, which is set under Components|WebInfo|Edit Defaults.  The default is HubApp.

The HubApp menu gives you access to all the verbs for the HubApp.  Search for ThtWebApp and look at its Verbs...


Hub: Components Menu

The purpose of the components menu is to give you access to the verbs and properties of all the web components except the web-application and pages, which have their own menus.

All components are explained in the webhub.hlp file.  Search for them individually by class name.  Here are the must-know items for someone wanting to use a HubApp:

WebInfo   configures the Hub

•	Edit Defaults -- configuration info is here, including HubAppID.
•	Edit Setups -- you need a Setup entry for each AppID to be served
•	Edit Servers -- use this to support multiple web servers by port and/or by machine
•	Edit Browsers -- define how WebApps should react to various web browsers

WebOutput	controls output-to-HTML

•	Properties -- use ShowOutput to control where the output goes, and Prologue to set the type of prologue used.  The buttons on the HubApp panel give you quicker access to the same features.


Hub: Pages Menu

The Pages menu only contains entries if you have a HubApp running.  In that case, the Pages menu lists all the pages defined for that AppID, and provides access to their verbs.

Most notable is the Edit Sections verb, which lets you easily view and modify page section definitions.


Hub: View Menu

This menu toggles the visibility of a few user interface elements.

The toolbar is the default panel just below the menu, and displays the Exit door, the change icon, and a few speed buttons.  The change icon toggles tool bar and verb bar

The Verb bar has speed buttons for all the verbs for the current component.  The current component is set by clicking the third icon.  Many components have lots of verbs.  Widen the form to see more speedbar icons.

The so-called Idle Dot can be turned on for entertainment.


Hub: Help Menu

Registration/Capacity

As shipped, the Hub supports 1 custom WebApp (EXE or DLL).  To increase the Hub's capacity, you need an unlock code from HREF Tools Corp.  The Hub may be unlocked to 5-, 10-, 20- or unlimited- capacity.  The Hub is licensed per machine, not per developer.

License Info	This option provides informaiton about your license agreement with HREF Tools Corp.


Registering and Unlocking Your Hub

Registering Your Hub

You can purchase and register your copy of the Hub by visiting our online form at:

http://www.href.com/webhub/register.htm

When you purchase and register your hub you will need to tell us the capacity you need.

Unlocking Your Hub

To unlock the hub choose Help|Registration/Capacity. Select the number of spaces you've chosen and enter your unlock code in the box.

See Also:

Contacting HREF Tools Corp.


Command Line Options
Command Line Options for HUB.EXE

?	Lists command line options

/Restore	Show the form on load, when using tray.  This is the default on NT 3.51.

/Tray	Tells the application to run in the tray.

/NoTray	Prevent the Hub from going in the tray  -- useful if you have no mouse available. (Applicable on Win95 and NT 4+ only.)

/Hide	This overrides /Tray.  The application will be invisible until it is explicitly restored.

/Minimized	Loads and shows the form minimized.  /Min also works.

/NS	No splash screen.

/PanelName	Causes the named panel to be included in the Hub's user interface.  The default is to include all panels.

Panel names: Sessions, Traffic, HTML, InOut, Mail, Runners, and MOTD.

See also: HubUI default. v1.47+

/NoPanelName	Causes the named panel to be excluded from the Hub's user interface.  For example, running hub.exe /NoMail would prevent the mail panel from loading. v1.47+

Command line options are not case sensitive.

Command Line Options for Web Applications

Web applications built with the WebHub components plus the standard whMain.pas unit will respect these options:

/AppINI:filename	Set the application-level INI file, overriding anything in Web Setups.  v1.38+

/HttpColon:[On|Off]	Set this to On for use with Apache and Netscape servers and cgi-bin. Default is On.

/ID:AppID	Set the AppID when the application loads.

/Minimized	(above)

/NoMenu	Run the application without a menu.  This saves resources and is recommended on production servers.

/NoTray	(above)

/NS	(above)

/Quit 	If you run the same EXE a second time with this flag, the first instance will be forced to quit. (requires ucOnce.pas unit).

/Restore	(above)


WebHub Application Icon Colors

The WebHub demos and the shared panels are set up to indicate their state by changing the icon.  Each state has its own color:

State	Icon Name	Color
In the tray	Parked	Transparent
Serving a surfer	Busy	Yellow
Serving surfer #1000-1010	Ping	Green
Suspended or not connected to The Hub	Stopped	Red
Form opened on the screen	Restored	Blue

The "ping" mode is intended for use with web site monitoring programs which should then request URLs with a session number in that range. That let's the webmaster visually tell traffic coming from the monitoring software versus live surfers.

You can have the same features in your own application as long as you include a resource file (*.res) in your project, containing icons with the names listed above.  Sample files are provided in the ht\lib32 directory:

whAppDpr.ico	WebHub application icon which shows up in Explorer next to the EXE filename. Associate with a DPR through Project|Options|Application icon.

whAppDpr.res	WebHub application icon which shows up in Explorer next to the EXE filename -- stored in a RES file. If you have no other settings in your project's RES file, you can copy whAppDpr.res onto your project's RES filename, and rebuild your project to put the icon into effect.

whAppIco.res	Resource file containing the five (5) colored state-icons listed in the chart above.  Include this file in your DPR if you want to use the standard WebHub icons.

htDemos.res	Resource file containing the five (5) colored state-icons, customized with the word "DEMO" and used by all the WebHub demos.

Version Notes

The ability to use multiple icons has been in WebHub all along.  The standardization of icon names and colors was added in v1.77.


HubLog

HubLog is a traffic analysis module designed specifically for WebHub.  It ships separately and has its own Help File.  It is available to registered customers.

Alternatively, use the regular logging feature of your web server, and then run the LogFixup utility to convert the log data to a format that a standard package (like WebTrends) will be able to analyze.

LogFixup is FREE, with full Delphi source, and downloadable here:

ftp://href.com/shareware/LogFixup.


Running as a Service

The v1.45+ Hub can be run as a regular application or as a service. Running it as a service means that its features will be available regardless of whether someone is logged into the machine (higher security).  The only drawback is that the file paths can no longer use UNC. You can use any drive letter that is local to the machine, and for most situations, that is sufficient.

Getting Started

1. Locate hub.exe.  The default installation location is c:\ht\htexe\hub.exe.

2. Run HUB -INSTALL to install the service or HUB -REMOVE to remove it.  The Hub will be installed as a service that starts itself automatically when NT starts, and it will start itself immediately.

3. See the .bat files called hub-on and hub-off for subsequent stopping and starting of the Hub.

Running Custom Web Applications as Services

It is possible to build custom web applications that also run as services. Further Info...

See also: HubMsg Service


Running as a Service, Custom Apps
Writing Custom WebHub Applications that Run as a Service

This requires additional units from HREF Tools Corp . These units (NtObj, SvcApp, SvcComp and SvcObj)  are available to registered customers upon request. E-Mail customerservice@mail.href.com.

• Install all units to the ht\lib32 directory.

• Save a copy of the files because you will need to copy them into ht\lib32 again, the next time you install the WebHub VCL.

• Make sure that the Hub has been installed to run as a service (See "Running As A Service").

• In your project's DPR file, replace 'Forms' with 'SvcApp'.  Recompile your project and it will then work both as a service and as an application.

Once your application has been compiled you have various options for running it:

1) To run your application as a service that autostarts when the server boots, go to the command line and type MyApplication - install.  This will register the application as a WindowsNT service that can be managed from Control Panel|Services.  WebHub and the application will start without a login required on the server.  Note that applications configured to start in this manner SHOULD NOT be set to autorun (AppInst>0) in the Edit Setups panel of The Hub as discussed in Item 2 below. If you wish to autostart more than one instance of an application, you will need to create multiple copies of your application, each with a unique filename, but sharing a single AppID.  Each unique instance of the application must be installed to run as a service.

2) To start and run your application as a service that autostarts on login, but continues to run after logout, go to the Edit Setups Panel of WebHub, locate your application and indicate the number of instances that you would like to have automatically start in the AppInst column.  Also make sure that the full page to the application is set in the AppPath\AppExe AppParam column.  Applications configured in this manner will start upon login.

3) To run your application normally (not as a service), start the application as usual.


WebHub Coolness Layer

The Coolness Layer is an add-on ISAPI filter (htFilter.dll) which lets you create special effects with the URLs.  You will be able to shorten the URLs used to get into your site, as well as those generated by WebHub macros as pages are output from your site. It is available to registered customers through our site at:

  http://www.href.com/COOLNESS

WebHub v1.42+ fully supports this filter.


.ini Files
About the WebHub INI Files

• href.ini -- information about all HREF Tools applications on the machine

• hubmain.ini -- information about all WebHub applications on the machine

• Application-level .ini file -- information about a single WebHub application


ini files - href.ini
href.ini

This is the only WebHub .ini file that is required to be in any specified location.  This file must be located either in the Windows directory or in the same directory as hub.exe.

Purpose

This is the control file for all HREF Tools packages installed on your server, including WebHub and TPack.

Details on Where to Put this File

Since EEP 8.86, the HREF.INI file can be stored in whichever directory contains hub.exe. If it is found in the same directory, it will be used.  If not, it will be expected/created in the windows directory.  If you move href.ini out of \windows, you will need to move ALL Webapp.exes to that same location.

  (This placement of href.ini is recommended for people maintaining multiple WebHub versions, as you   now can keep everything about one version under one directory tree.)

The [WebHub] section contains constants made available through TWebInfo.Defaults, which is why the location of href.ini is important to hub.exe and any custom .exes.

Variables containing File/Path names respect the SetupID variable to support full portability of your applications, e.g. AppRoot.Production is distinct from AppRoot.

Please note that over time, href.ini will contain other sections besides [webhub] and [href].  These sections are created in this file by HREF Tools Corp. programs to remember startup parameters and window positions.  These are all optional sections and can be deleted to restore the original defaults.

Combining href.ini and hubmain.ini

href.ini contains an entry which defines the name and location of the .ini file for webhub.  This defaults to ht\hubmain.ini as follows:

[WEBHUB]
IniFileName=c:\ht\hubmain.ini

However, this can also point back to href.ini so that you only have a single main .ini file for the whole system:

[WEBHUB]

IniFileName=c:\winnt\href.ini


ini files - hubmain.ini
hubmain.ini

The default name for this file is ht\hubmain.ini.  You may change the name and location in href.ini, [WebHub] section, iniFileName setting.

Purpose

The hubmain.ini file contains information which applies to all WebHub applications running on the machine.

Sections

These are all properties of the TWebHubInfo/TWebInfo component.

• [WebSetups] is a required section. It lists all the AppIDs that the machine knows how to handle.  Use Components|WebInfo|Edit Setups to get there from the Hub.

• [WebBrowsers] defines rules for web browsers.  [? TWebBrowserList class]

• [WebRunners] defines runner overrides.  [? Edit RunnerList]

• [WebBounceTos] defines list of http:// addresses to bounce new requests to.  By creating this list you are enabling the Hub to work as Maitre d'.  [? Edit BounceTos]

• [WebServers] defines aliases for http:// addresses, for use in JUMP commands to facilitate cross-application links.  [? Edit Servers]


ini files - application-level
Application-level .ini file

This file's name and location depends on AppID as configured in hubmain.ini, [WebSetups] section.  Please note that multiple WebApps may share the same application-level .ini file.  This can be convenient but be sure you do not have overlapping PageIDs.

Overview

Each web-application must have an ini file which defines the application in terms of the pages, files, chunks and macros and optionally configures additional components, typically for database or e-mail work.

In order to make the shipping WebHub files as portable as possible, none of the optional INI file elements are set in the shipping files. This means that if you’re just poking around, you might not see an entry to configure for something that is optional in a section .  However, if you use the Edit Defaults verb, you will see all the automatically-created entries.   An example would be the absence of AppPath under TWebApp.Defaults.

Categories of Sections

There are four categories of sections that can appear in the application-level .ini file.

• Sections Prefixed by TWebApp Class Name

Several sections are prefixed with the name of the class for your web-application object.  This could be TWebApp, TWebDemoApp, TFishApp, or any custom type.  The component will look for its own class name first.  If it can't find it, it will go up the object tree, as far back as TWebApp, looking for a match.  As a last resort, it will use the class name listed under WebSetups.

Examples from the .ini file, with their verbs, would be:

[TWebApp.Defaults]	TWebApp|Edit Defaults
[TWebApp.Macros]	TWebApp|Edit Macros
[TWebApp.Files]	TWebApp|Edit Files

• WebAction component specs

Each WebAction component has its own specific requirements in terms of the properties that it needs configured.  TWebDataGrid needs [.ButtonSpecs], for example.

Not all WebApps use WebAction components, and therefore this type of section may not appear in your .ini file.  See The Fish Store and the query demos for examples.

• Sections Prefixed by Page Name

Some sections are for a specific page and define how that page will be constructed in terms of its sections and other features.

A section such as [Homepage] itemizes the page sections.  The best way to maintain this information is with the Pages|Homepage|Edit Sections verb.

The [HomePage.defaults] section is optional and defines features such as animation and automatic page sequencing.

Note that the quickest way to set up defaults for a new group of pages is by putting the qualifiers in the [.Files] section for the app, e.g.

[TWebApp.Files]

htx=htx,sequence.on

This would make all pages defined in htx.htm receive the 'sequence.on' default.  All special page features are off by default.

• Custom Sections

You may add unlimited custom sections.  Use the TWebIniLink component to easily access custom sections and entries.


Property Editors

use common sense

read the hnts

right click for context-sensitive features


How Macros are Decoded
How Macros are Decoded by TWebApp

See Also

Built-in WebHub Macros

Requirements

Macros must be completed on one line.  Even when sent within Pascal, they must be sent as one line.

Terminology

The basic macro entry looks like this:

[TWebApp.Macros]

myname=Michael

and is called a macro constant.  All it does is text substitution.  Anything more complicated looking than this example is no longer a macro constant, but a macro.

Macro Recognition

Macro recognition begins when %= is found in an outgoing string. If the next character is a '<' and there is a '>' on the same line, the part in between is considered Controlled HTML. If the next letter is not '<' then TWebApp looks for '=%' to determine if what you are sending is a macro at all.

Macro Processing

Given that there is an end-macro marker, TWebApp processes it according to these rules:

1. Every macro can have a parameter. If there is a '|' in the macro name, that bar is considered the divider between the macro and the parameters.  Parameters are optional.

2. If there is a parameter, the string is tested to see whether it requests a built-in macro, and if so, is immediately handled.

3. Test for a custom event macro, as itemized under TWebApp|Edit Events.

If so, the OnEventMacro event is called.  You are passed the macro name, parameters and the 'group code.'

4. Test whether the string contains a period.  If so, assume it is a request for a component's property value. Note that TStringLists are sent according to the TWebApp.ListAsMemo and CrLfMode properties.

In #4 parameters are ignored.

5. Test for macros listed under TWebApp|Edit Macros -- i.e. simple text substitution macros.

You must avoid defining macros with infinite recursion.

6.  Test for chunk or page.

7. Test for WebSession.Literals.

8. Test for properties on the following components, in this order:
a) TWHSession.Vars

b) TWHSession

c) TWebPage

d) TWebApp

e) TWebServer

f) TWebOutput

g) TWebInfo

This is all surprisingly swift and allows you to get by without using prefixes for basic properties you might want to reference.

9. Lastly, look for a TWebAction component by name and execute it should one be found.

10. If still no match, call TWebApp.OnMacroNotFound.  By default, the handled parameter is True, so error messages are suppressed.  You may want to change that for testing purposes.

When expanding parameters, WebHub uses its own internal function called CompareTo.


Contacting HREF Tools Corp.

Main office

HREF Tools Corp.

300 B Street

Santa Rosa, CA 95401

USA

Web: http://www.href.com/contact

Direct Sales

http://www.href.com/salesdesk

Registering Your Copy of WebHub

If you bought WebHub through a reseller, register to obtain program updates and other news. http://www.href.com/register

Technical support

http://www.href.com/techhelp


Recommended VCL Products

The products on this page were all created by people/companies that have strong alliances with HREF Tools Corp.  We recommend these products very highly.

From Peter Hyde at South Pacific Information Services Ltd

http://www.spis.co.nz and http://usa.spis.co.nz/

TCompress - File and Database Compression Components

TCompLHA - LHArc/LHA Archive Management

TWebCompress - Site Management Component for Delphi and WebHub

From Jason Wharton

http://www.ibobjects.com

Interbase Objects - direct access to the Interbase API, from Delphi.  Fast, reliable, easy to use.

From David Baldwin

http://www.pbear.com

THtmlViewer and TFrameViewer, Professional Version - Delphi controls for rendering HTML.

From Peter Tiemann

http://www.href.com/scoder

SourceCoder utility for analyzing your source code and application performance.


WebHub Add-On Products

The products on this page were all created by people/companies that have strong alliances with HREF Tools Corp.  We recommend these products very highly.

From Peter Hyde at South Pacific Information Services Ltd

http://www.spis.co.nz

TurboPress Web - software for online publications

Webview - Offline Browser

WebWatch - Site Monitor

From Robert Martin at Windsor Web Development

mailto:rob@robmart.com

File Upload Utility


AdjDpr Utility

This utility is for use by programmers installing the WebHub demo projects to a location other than C:\HT\. It is called automatically during installation.  If you subsequently move your projects, you can rerun this utility to adjust all the project paths.  It also sets the Project Output Directory to the corresponding ht\htexe\ subdirectory.

Utility location: ht\htutil\adjdpr.exe

Run it from Explorer or File Manager, with ht\htutil as the working directory.

It touches projects under htdemos\ only.

v1.02+


Form to HTML Converter

The TWhForm2HTML component lets you take a form and quickly convert it to WYSIWYG HTML.  It will save you hours of design time if you have existing forms, especially if you have nested panels and controls.

It is an add-on VCL component available for $99.00 from HREF Tools Corp.  A trial version is included in the WebHub VCL.  The trial version supports a limited number of controls.  When you register, you receive a version that supports an unlimited number of controls.

Install the registered version in ht\lib32 so that it replaces the trial files, and then rebuild your component library or packages.  The file ht\lib32\f2h.txt contains documentation on the component properties and general usage guidelines.

There is an online demo at http://www.href.com/dfm2html which shows the component used live over the web, where you can change form attributes and see the resulting change in your web browser.


Creating a new Delphi Project without the Wizard

Instructions

• Define an AppID using the Hub's Connected|Edit Setups panel, or use an existing AppID.

• Start Delphi

• File|New Application

• Add in the ThtWebApp component.

Tip: if you don't know what palette a component is on, but you know its name, use View|Component List and then select the component alphabetically.

ThtWebApp is on the WebHub palette.

• Set the ThtWebApp.AppID property to your desired AppID.

• Right-click on the ThtWebApp component and select Refresh from the menu.

During this process some additional components will be automatically added to your project, and automatically linked up.  You may want to drag them around to line them up.  If you like things to be neat, add a TtpComponentPanel to your project, and put the non-visual components inside that. It's a special panel that will disappear at run-time, so you can visualize the rest of your form being the final size that a user would see.

• Add a TWebCommandline component.

• Add a TWebMenu.

• Compile and run your application.  It should connect to the hub and be able to serve pages.

• Test with a URL like this from your browser :

http://localhost/scripts/runisa.dll?appid:index 	-	for ISAPI

http://localhost/cgi-win/runwin.exe?appid:index 	-	for cgi-win

http://localhost/cgi-bin/runbin.exe?appid:index 	-	for cgi-bin

The index page is a built-in page and should show you something, depending on whether ThtWebApp.BuiltInsEnabled is true, and what you have defined in your W-HTML.

• Go back into Delphi and add a TWebAction component.

• Set its DirectCallOk property to True.

• Add 'webapp' to the USES clause for your unit.  That's required when you want to use the global pointer, pWebApp, which happens next.

• Program the webaction's OnExecute event like this:

pWebApp.WebOutput.Send('Hello there, this is a test.');

pWebApp.WebOutput.Send('<p>It is now '+WebServer.WebTime);

• Compile and run.

• Test with a URL like this:

http://localhost/(path)/(runner)?appid:do::webaction1

The "DO" page is a special page in WebHub that lets you quickly test a web action component.

When you test it, you should see the test message.

• Now use the AppID|Edit Files menu option and find one of your pages. If you don't have any pages defined yet, create a page.

• Add this W-HTML to one of your pages:

%=webaction1.execute=%

Save that, and return to your web browser.

• Test again, using the PageID that you were just working on, e.g.

http://localhost/(path)/(runner)?appid:pageid

That should run the page and include the test message.

Good, you have now built a simple, dynamic web application.  You have seen how the URL relates to the W-HTML page definitions, and how calling a web action component by name relates to the Delphi code in the OnExecute method.  From here, you can expand what you "Send" through that web action component, or you can start experimenting with other twebaction components.


Importing Existing HTML Files

If you have an existing web site with more than 2 or 3 pages of HTML, use the FREE wizard to import your HTML into WebHub format.  The wizard will create your pages automatically, and convert all the links to macros for you.

The wizard also optimizes files made with FrontPage and Net Objects Fusion.

On the CD: \whtmlwiz directory

Download: http://www.href.com/whtmlwiz


UNC
Universal Naming Convention

(according to Microsoft)

Syntax: \\servername\sharename\path\filename.extension

Example: \\webserver\webroot\abc\abc.ini


DO page
Exception to the Rules -- the 'DO' page

Within WebHub, a web site is generally discussed as a strict "collection of defined pages."  There is a notable exception to this which enables you to make pages that are totally dynamic, based on a WebAction component specified on the URL.  Grids, email, and other 'actions' can execute without a supporting page construct.

To accomplish this, use the built-in page named 'DO'.  Place the name of the action component and any parameters in the Command position on the URL.  For example:

http://www.abc.com/scripts/runisa.dll?test:DO::webaction1

This URL executes the component named webaction1.  Its output would create the page.  TWebAction.DirectCallOk must be set True for the action component in order for this to be enabled.

Setting to cover bad URLs

One more step -- if you route blank pages to DO, there would be an error if the action component name were missing.  To cover this case, set NoDoPage to the PageID you ordinarily think of as your homepage, and any spurious URLs will route there.  An example would be ?:#.

[twebapp.defaults]

homepage=do

noDoPage=homepage


RFC 850
RFC-850 has been updated and replaced by  RFC-1036

Go to the following URL for more information:

http://www.w3.org/Protocols/rfc1036/rfc1036.html


RFC 1036
RFC 1036--Standard for Interchange of USENET Messages

For more information, see:

http://www.w3.org/pub/WWW/Protocols/rfc1036/rfc1036.html

Excerpt from the above page:

Standard for Interchange of USENET Messages

This document defines the standard format for the interchange of network News messages among USENET hosts. It updates and replaces RFC-850, reflecting version B2.11 of the News program. This memo is disributed as an RFC to make this information easily accessible to the Internet community. It does not specify an Internet standard. Distribution of this memo is unlimited.


RFC 822

RFC822: Standard for ARPA Internet Text Messages

Go to the following URL for further information:

http://www.w3.org/pub/WWW/Protocols/rfc822/