WebHub VCL: F.A.Q.

Let's start from the fact that the WebHub components are unusual. You will definitely notice that if you experiment with them in Delphi. The purpose of this FAQ is to help a Delphi programmer quickly understand WebHub's uniqueness.

Question: What's going on with the complex interrelationships between the components? I add one component in the Delphi IDE, and the next thing I know, several others have appeared on my form. Why?

Answer: Yes, this is very much on purpose. The capability stems from TComponentExtended, which is one of the base-base-base classes inside tPack, which is part of WebHub. TComponentExtended was invented in January 1995, and was written about in the Delphi In-Depth book which was published in 1996. That's why everyone at HREF totally takes this very unusual behavior totally for granted.

The idea is that components need to interrelate. This is true of all Delphi components, but most of them require you to do something. When components are built from TComponentExtended instead of TComponent, they can hook themselves up automatically, in the IDE and at run-time.

Let's look at the most extreme example. You start with an empty application and you put in ThtWebApp. You set the AppID property, to DEMOS or anything else you have handy. The OnSet event handler for the AppID property will notice the change and go update other aspects of the component. For example, it wants to set the INIFilename associated with the AppID. To do that, it needs to reference TWebInfo.WebSetups, which is a TStringList derivative. Well, maybe TWebInfo doesn't exist yet.

Instead of giving an error, TWebApp goes and creates TWebInfo for you. TWebInfo refreshes itself upon coming to life, and then TWebApp can get the information it needs.

This plays out for several other linked components: TWebServer, TwhSession, etc. Basically all the properties that are on the TWebApp that need to be linked to other components will trigger creation of the relevant components.

By the way, that leaves 2 components that you need to add manually, because they are not linked directly: TWebCommandline and TWebMenu.

Question: How do I figure out what the components do?

Answer: For a quick description, check the end of Chapter 7 in the manual. There is an alphabetical list of the components there.

For more detail, look up the class name in the webhub.hlp file, e.g. "ThtWebApp Class."

Question: Where should I edit the properties?

Answer: Let's break this into a few categories:

• Properties that you try to edit in the IDE but nothing changes
  Don't bother. Those are properties that are "published" on the component so that their values can be retrieved through W-HTML (WebHub HTML). They are not meant to be set interactively. For example, TWebApp.IniFilename.

• Properties on components that are used in units stored in the ht\lib32 or ht\htfrm directory
  Such units are part of WebHub, and you really should not change them. Your choices are to make a copy, use form inheritance, link in a separate unit, or set the properties via the DPR file.

  Let's look at this in detail because it's very important. We'll look at one property and one event.

  A property, TWebApp.AppID: You've probably noticed that changing this one property makes a whole lot of things change. It's really central. And, it's on the ht\htfrm\dmWhApp.pas datamodule, so you're not supposed to touch it.

  If you don't need to make any other refinements to that datamodule, it's not worth maintaining a copy. Just add code like this to your project's DPR file:

  uses
    webapp;   // add webapp if it's not already in your USES statement
  ...
  with pWebApp do begin
    AppID:='MyAppID';
    Refresh;
    end;
  ...
  

  An event, TWebApp.OnUpdate: It's entirely possible that you might want to customize this event handler. If you're new to Delphi, the easiest thing to do is to copy the datamodule and then change the copy. However if you are pretty familiar with Object Pascal, here's a cool twist -- add an event handler on the fly.

  The ThtWebApp component defines procedures which let you easily add event handlers for OnUpdate and other events. In one of your custom units, define the event handler, e.g.

  procedure TMyForm.WebAppUpdate(Sender: TObject);
  begin
    // code here
  end;
  

  In your DPR file, after the dmWhApp unit has been created, add this code to add in your custom event handler:

  pWebApp.AddAppUpdateHandler(MyForm.WebAppUpdate);  
  

  This "AddAppUpdateHandler" method will add your OnUpdate handler to the list of update handlers the ThtWebApp will respect. It'll run whatever shared code is in dmWhApp, plus your code.

  This technique of adding handlers was developed so that WebHub programmers could build self-contained panels which would plug into other applications without modification of any sort, regardless of whether the key events had already been used. This is a really big deal, think about it slowly!

• Properties that can be set in the IDE but whose settings get changed at run-time
  Ah, there are a few of these, like twebdatasource.displayset. These settings are surfer-specific and they will be changed dynamically depending on the current surfer. The way to impact these settings is usually through a literal. You'll need to check the help file for particulars.

• Properties on the application object that you might want to reconfigure without recompiling, such as CgiUseHandle, which routes the surfer back to the exact instance of the EXE, which can be important when you have multiple instances running.
  Set those properties through the INI file in a section like this:

  [TWebApp.Defaults]
  CgiUseHandle=true
  

• Everything else
  All other cases can be handled normally.

Question: Then what is the Properties verb for ?

Answer: It is for run-time inspection of properties, sort of like a run time object inspector. You can only use it to change BOOLEAN values, and you do that by double-clicking on the item. That is sometimes very helpful for quickly testing out an idea, such as finding out whether TWebOutput.HttpColon should be true or false with your web server.

By the way, the properties verb is another thing that comes from TtpComponent. Anything with a 'tp' in the component name is something that is defined in tPack, and available with full source.

Question: What is the order in which I need to drop components on a form? 

Answer: You should put in ThtWebApp first, then add TWebCommandLine and optionally TWebMenu.

The TWebAction components can be added in any order, and can be put on any form or datamodule. If you include a TtpDataModule component with them, they will announce themselves to the TWebInfo component at run-time and thereby become fully available to the running application.

Question: Why do the pop up menus of components work sometimes and not other times? 

Answer: The pop up menus, also known as "speedmenus" or "verbs", only work when the component is ready. Ready is defined as the components isUpdated property is true.

Most WebHub components depends on the TWebApp, and if it's not updated, they won't be, either.

Often by running your application, everything will refresh itself and then you can use the verbs through the menu system, which works just as well because you're entering data that goes into an INI file anyway. For example, if you put TWebDataSource into a form and try the Edit Display Sets verb, it won't work unless you have everything refreshed. However if you just run the application and have a valid AppID, the components will refresh themselves and then you can use the menu: Components|WebDatasource|Edit Display Sets to accomplish the same thing.

Question: What is the minimum configuration of components that would allow me to write a database enabled application? 

Answer: ThtDBWebApp and everything it brings in when you double-click it, plus TWebCommandline and a TWebAction component. You would then have to program the twebaction component to do your bidding.

Question: Why can I make changes in INI files that are reflected in the object inspector and not vice versa?

Answer: That's a bug. You are supposed to be able to use TWebInfo|Edit Setups in the IDE to edit that list, and the save button is supposed to write to the INI file.

Question: What is the BEST way to write a simple dynamic website?

Answer: If you just want something simple so that you can see all the moving parts, start with an empty form, put in ThtWebApp or ThtDBWebApp depending on whether you plan to do database work, double-click it. Add TWebCommandLine and TWebMenu. Add TWebAction. Program TWebAction's OnExecute method like this:

pWebApp.WebOutput.Send('hi there');

Set the TWebApp's AppID to anything you have that's valid.

On one of your pages, in the W-HTML file, call webaction1.execute.

Now test in the browser. That will give you a totally simple dynamic page that uses your web action.

###