This is part 2 of the article published in magazine 101.
How Exactly does a Team Cooperate?
The user manual for the WebHub extension for Dreamweaver discusses the topic of team cooperation in great detail, and includes best-practice advice for file organization, naming conventions, and so on (see http://www.href.com/edeliver:whdw).
Nonetheless, I can give you an overview here now.
We have already talked about the fact that the WHTEKO files are kept separate from the WebHub application. Generally, a graphic design person would be given access to those files, plus the images, css and javascript files. All such files can be easily maintained in version control.
Refreshing when files change
If the designer changes an image or a CSS file, reloading the web page in the browser should be enough to see the change.
If the designer changes a WHTEKO file and wants to see the effect in a web browser (without using Dreamweaver), he or she needs to get the WebHub application to refresh. There are many ways to do this, including using WebHubAdmin on the server, right-clicking and selecting Refresh from the tray menu of the running app on the server, or using a browser to trigger a special page with a refresh command for this purpose. I find that using the browser is usually quickest.
The special page would be declared as shown in listing 1,
<whpage pageid="remoterefresh">
(~app.refresh~)
</whpage>
Listing 1: A page used to tell the app to reload WHTEKO and config details
and called from Firefox or IE using
http://www.mydomain.com/scripts/runisa.dll?appid:remoterefresh
Of course, you might add security to make sure the remoterefresh page was only called from certain ip numbers or only on a restricted subdomain.
From sketch to actual
A designer often needs to put in some placeholder content, before the Delphi programmer can create a perfect web action to generate the content dynamically. WebHub supports this process with a <whsketch_tag>. Listing 2 shows an example, where part of a page banner is built.
<whsketch show="yes">
<table id="banner">
<tr>
<td><img src="/sitedesign/ABCCompanyLogo.png" /></td>
<td>A.B.C Company … the best, since 1885 </td>
</tr>
</table>
</whsketch>
Listing 2: A sketch, showing sample data in position, for design purposes
When the developer sees the sketch, he or she could realize that only two variables are needed to make that section work for any company. At that point, the sketch would be copied to a droplet, expecting two parameters, as shown in Listing 3:
<whdroplet name="drBanner">
<whdoc for="drBanner">
DYN1 – name of image used for the logo
DYN2 – company slogan/text
Usage: call via web action named 'waBanner'
</whdoc>
<table id="banner">
<tr>
<td><img src="/sitedesign/(~DYN1~)" /></td>
<td>(~DYN2~)</td>
</tr>
</table>
</whdroplet>
Listing 3: A droplet, expecting two parameters to fill in variable data
The developer could then make a web action to find the data and display it. There are many approaches. Listing 4 shows how it can be done by calling the PARAMS command, which runs a droplet, passing in parameters.
uses
webApp;
procedure TForm1.waBannerExecute(Sender: TObject);
var
OrgImageFilename: string;
OrgSlogan: string;
begin
// do some database lookup to find these values
OrgImageFilename := 'abc.jpg';
OrgSlogan := 'A.B.C. Company, the best since 1885';
pWebApp.SendMacro(Format('PARAMS|drBanner|%s,%s',
[OrgImageFilename, OrgSlogan]));
end;
Listing 4: Web action component loads data then calls the drBanner droplet, passing two parameters which become available as DYN1 and DYN2)
When that was in place, most likely the Delphi programmer would disable the sketch by changing show="yes" to show="no", and adding
(~waBanner.execute|~)
Once that was in place, the designer could make further adjustments to the drBanner droplet (listing 3) to add CSS tags, etc., independently from the Delphi programmer.
The <whdoc_tag> in listing 2 is optional. We recommend using it whenever droplets expect parameters, so that everyone knows what is required. In some future version of WebHub, we hope to make the web action components more self-documenting, so that they could report their usage automatically. For now, coders should use the <whdoc_tag> or a WebHub comment to annotate tricky sections of the file.
Text Substitution Macros
WebHub supports unlimited text substitution macros. The restrictions on macros is that each must fit on one line (but that can be a long line). A droplet, by contrast, can include unlimited lines. Listing 5 shows imaginary macros.
<whmacros>
mcAssetRoot=/files/
mcLegalDir=(~mcAssetRoot~)/misc/legal/
mcTrademarkPic=<img src="(~mcLegalDir~)trademark.jpg"
alt="tm" />
</whmacros>
Listing 5: Text substitution macros can be defined in any WHTEKO file.
You may have already realized that calling a macro is accomplished in W-HTML by putting its name inside parentils:
(~mcLegalDir~)
Page Settings
Internally, WebHub has an object for each page in the application, a TwhPage component. Each page can carry some configuration detail, known as Page Settings. That is basically a TStringList that can be used to write generic code.
The following example (listing 6) shows how page settings can be used to enter details which are later used to generate a Google sitemap file.
(The Google sitemap feature is included as a standard module in WebHub. It works as-is for sites where every page has its own PageID. It requires modification for sites that use WebHub pages as templates and need Google to a wide range of database-driven content.)
<whpage pageid="Login" desc="Customer Login">
<whpagesettings>
googlesitemap=include_all_lingvo
googlechangefreq=monthly
googlepriority=0.7
metarobot=index,nofollow
metadescription=Customers may login here.
metakeywords=login; interactive; dynamic
</whpagesettings>
…
</whpage>
<whpage pageid="HomePage" desc="Distribution">
<whpagesettings>
googlesitemap=include_all_lingvo
googlechangefreq=monthly
googlepriority=1.0
metarobot=index,follow
metadescription=Full service east-coast distribution
metakeywords=courier service; trucking;
</whpagesettings>
<whoutput>
(~mcDocType2006~)
<html>
<head>
<title>(~PageDesc~)</title>
(~drHead~)
</head>
…
</whoutput>
</whpage>
<whdroplet name="drHead">
(~HEADER|Content-Type: text/html;
charset=utf-8~)(~waLingvo.execute~)
<meta name="robots" content="(~pagesetting.metarobot~)" />
<meta name="description"
content="(~pagesetting.metadescription~)" />
<meta name="keywords"
content="(~pagesetting.metakeywords~)" />
<link rel="stylesheet" type="text/css"
href="/css/common.css" />
</whdroplet>
Listing 6: Page settings defined, then used to generate sitemap and shared header tags
Application Configuration
You may be wondering about custom settings needed for the application as a whole, such as a database name or the path to some utility used during processing. This is handled through the application-level configuration file. In that file, you can have settings which are again basically a stringlist, although they are stored in XML format. Listing 7 shows a few sample settings and how they could be referenced in Delphi and in WebHub-HTML.
In XML:
<AppSettings>
<AppSetting name="DemoGraphic" value="yes" />
<AppSetting name="DBName" value="alias123" />
</AppSettings>
In PAS:
ShowMessage(pWebApp.AppSetting['DemoGraphic']);
ShowMessage(pWebApp.AppSetting['DBName']);
In WHTEKO:
(~AppSetting.DemoGraphic~)
(~AppSetting.DBName~)
Listing 7: Application settings in the config file; used in Delphi; used in WHTEKO
Dozens of aspects of the application can be configured. Some people like to use Notepad to edit the XML file directly. Beginners will find that the configuration utility, ZMAdmin.exe, is very convenient for exploring and changing settings. Figure 1 shows AppSettings as they look in ZMAdmin.
Fig. 1: ZMAdmin provides the GUI for configuring the application; hints are often more detailed!
Live Content in Dreamweaver
If the page layout expert on your team uses Dreamweaver, I highly recommend that you look through the user guide for the WebHub Extension for Dreamweaver. That manual contains many screen shots showing exactly how it works. Remember, the big difference between WebHub's live content and that from ASP, PHP, etc., is that the WebHub content is generated specifically for Dreamweaver and provides 100% of the HTML for each WebHub expression. Other plug-ins use approximations for many of their dynamic pieces, especially for database content.
If you are not a Dreamweaver fan, do not despair! People have built extreme sites using the WHTEKO editor provided with WebHub, or even their favorite text editor.
Content Management
Straight "out of the box," WebHub supports simplistic content management. A WebHub site is easier to maintain than a static web site because one usually shares all the headers and footers across the pages. However, if you want to use a database to store content, and manage users and permissions, you need to build something for that purpose. One of the demos provides a simple example for doing so.
One of our customers, www.netcat.com.au, has built a full-featured CMS using WebHub. Another customer, www.webcentre.co.nz, built a CMS specifically for magazine and "news" content, and that is used on the award-winning site, www.scitechdaily.com.
Web Apps that look like Delphi Apps
Do you want your web application to look and act exactly like an existing Delphi application? WebHub includes a fancy component nicknamed "F2H" meaning "form to html converter". This component can take any Delphi container, such as a form or a groupbox, and convert it to HTML. This content can be used as the basis for any pages, such that the surfer looks at something which looks like a Windows application.
Whether this is desirable or not, depends on the target market and the type of application.
You may know that IntraWeb specializes in this type of web application, and uses AJAX in creative ways to make web applications operate like Delphi applications. There was an excellent presentation about this at CodeRage 2008, and if you missed it, I recommend you find the recorded session. Look for "Rich User Interfaces with IntraWeb" by Olaf Monien at http://conferences.codegear.com/coderage08/sessions.
WebHub supports AJAX and includes three general-purpose commands to make AJAX features extremely easy to use. A Delphi developer in Florida has used the WebHub AJAX commands to create a web version of his proprietary application. So if you want your web application to look and act like a Windows application, you certainly can.
If you want **all** your web applications to look and act like your Delphi application, IntraWeb will be a better product for you than WebHub.
WebHub developers often build an application with the idea of "skinning" it for multiple customers
Apps with Skins; Re-use
Would you agree that developers are most profitable when they can build something and then re-use it two or more times? WebHub developers often build an application with the idea of "skinning" it for multiple customers.
This can be done in many ways. The simplest is to use an AppSetting to define the values that need to change for each customer, and use a different configuration file for each customer.
Whatever technique you use, the key is to use macros and droplets for each piece of the design that will be swapped out. If you have an extra-talented CSS person on your team, you might not have to vary much more than the path to the CSS file.
If you want to skin your web app for two or more purposes, WebHub will probably be a better product for you than IntraWeb.
Techniques inside Delphi
There are a few innovations inside Delphi which make WebHub applications unique and fun.
MultiTypeApp; TtpProject
MultiTypeApp is the name of a unit which, when included in your DPR instead of Forms, makes your application compile easily as a normal Windows app, a Windows service, or as a console application. Because most WebHub developers eventually deploy their app as a Windows service, that is the default behavior. However by adding the PREVENTGUI compiler directive, you eliminate the as-service feature (and overhead).
TtpProject is the name of a component which we use to organize and sequence all the CreateForm statements relating to forms and datamodules, plus any initialization. When combining standard WebHub datamodules and forms with custom units, an ordinary DPR can become quite messy, and often only the original developer understands the required sequence.
TtpProject has a series of events which offer a place to put the nuts and bolts of project startup that would normally be in the DPR. It includes some features which are especially helpful to WebHub coders and can be ignored in other types of projects.
The use of TtpProject is always combined with the use of MultiTypeApp. Both are part of TPack and available with full source.
Let's look at one real-world example, keeping in mind two goals:
- Create objects in the correct order to avoid referencing something which is still nil;
- Enable easy compilation of the app with zero GUI in case that is needed later.
Fig. 2: Delphi Object Inspector with all the events on TtpProject (in Delphi 7)
Each event is called in the order shown. Thus all the datamodules are created FIRST (over 3 steps, as needed for WebHub); then any Init methods are called on those datamodules in order to run code which cannot run inside OnCreate due to interdependencies among modules; then the GUI is created; then the GUI is initialized.
Listing 8 shows the code inside those events for an app in production named CSShop, from the DMForCSShopPR.pas unit:
procedure TDMforCSShopPM.ProjMgrDataModulesCreate1(
Sender: TtpProject; var ErrorText: String;
var Continue: Boolean);
begin
CreateCoreWebHubDataModule; // includes TwhApplication
end;
procedure TDMforCSShopPM.ProjMgrDataModulesCreate2(
Sender: TtpProject; const SuggestedAppID: String;
var ErrorText: String; var Continue: Boolean);
begin
if SuggestedAppID = '' then
begin
ErrorText := 'Usage: csshop.exe /ID=shopname';
Continue := False;
Exit;
end;
if AppIDToConfigFilespec(SuggestedAppID) = '' then
begin
ErrorText := Format(
'WebHub Configuration Error in WHCentralInfo.xml%s' +
'No configuration file for AppID "%s".',
[sLineBreak, SuggestedAppID]);
Continue := False;
Exit;
end;
with pWebApp do
begin
AppID := SuggestedAppID;
Refresh; // load all config and WHTEKO information
end;
// provide notice to use while the rest is loaded
CoverApp(SuggestedAppID, 2, 'reloading application',
False, ACoverPageFilespec);
end;
procedure TDMforCSShopPM.ProjMgrDataModulesCreate3(
Sender: TtpProject; var ErrorText: String;
var Continue: Boolean);
begin
try // uses MultiTypeApp, not Forms
Application.CreateForm(TdmCommon, dmCommon);
Application.CreateForm(Tdmdb, db);
Application.CreateForm(TdmFastTax, dmFastTax);
Application.CreateForm(TdmAccount, dmAccount);
Application.CreateForm(TdmCart, dmCart);
Application.CreateForm(TdmVersionControl,
dmVersionControl);
Application.CreateForm(TdmPlaceLookup, dmPlaceLookup);
Application.CreateForm(TdmAS400, dmAS400);
CreateStandardWHModules; // based on app config
Application.CreateForm(TdmwhNavigation, dmwhNavigation);
Application.CreateForm(TDataModuleProductPhotos,
DataModuleProductPhotos);
except
on E: Exception do
begin
ErrorText := E.Message;
Continue := False;
end;
end;
end;
procedure TDMforCSShopPM.ProjMgrDataModulesInit(
Sender: TtpProject; var ErrorText: String;
var Continue: Boolean);
begin
try
db.Init;
dmFastTax.Init;
dmAccount.Init;
dmCart.Init;
dmVersionControl.Init;
dmAS400.Init(dmCommon.cn1, dmCommon.tr1);
InitCoreWebHubDataModule; // TwhApplication
InitStandardWHModules; // based on app-config
dmwhNavigation.Init;
DataModuleProductPhotos.Init;
except
on E: Exception do
begin
ErrorText := E.Message;
Continue := False;
end;
end;
end;
procedure TDMforCSShopPM.ProjMgrGUICreate(
Sender: TtpProject; const ShouldEnableGUI: Boolean;
var ErrorText: String; var Continue: Boolean);
begin
if ShouldEnableGUI then
try
Application.CreateForm(TfmWebHubMainForm,
fmWebHubMainForm);
CreateStandardWHModulesGUI; // based on app-config
Application.CreateForm(TfmwhSponsor, fmwhSponsor);
Application.CreateForm(TfmMemory, fmMemory);
Application.CreateForm(TfmAS400, fmAS400);
except
on E: Exception do
begin
ErrorText := E.Message;
Continue := False;
end;
end;
end;
procedure TDMforCSShopPM.ProjMgrGUIInit(Sender: TtpProject;
const ShouldEnableGUI: Boolean; var ErrorText: String;
var Continue: Boolean);
begin
if ShouldEnableGUI then
try
InitCoreWebHubDataModuleGUI;
InitStandardWHModulesGUI;
fmwhSponsor.Init;
Application.MainForm.Caption := pWebApp.AppID;
UncoverApp(ACoverPageFilespec);
WebMessage(''); // clear splash screen
except
on E: Exception do
begin
ErrorText := E.Message;
Continue := False;
end;
end;
end;
end.
Listing 8: Delphi code linked to the events shown in figure 2
To understand why all this is necessary, you need to think about how objects are created and initialized. Getting the sequence correct is essential. For a WebHub application, you must instantiate a TwhApplication (OnDataModulesCreate1), set its AppID property and refresh it (OnDataModulesCreate2), and then create other non-GUI modules which work once the TwhApplication is ready (OnDataModulesCreate3). After all of those have been instantiated, we do another pass to call an Init procedure on any datamodule which needs to do something special. For example, it's usually better to connect to a database in the Init method, in case one needs to use any properties on other datamodules.
The GUI forms are created and initialized completely separately. While the GUI is great during development and testing, it is often undesirable during production. By isolating the CreateForm statements for forms in OnCreateGUI, the whole project can quickly be compiled as a non-GUI edition when needed (by adding the PREVENTGUI directive).
It is possible to build WebHub apps without MultiTypeApp or TtpProject. However we recommend using them because the resulting code is more self-documenting.
Too difficult? Talk to the Wizard!
We built a few wizards to help you get your files started. They are accessible inside the Delphi IDE.
- New AppID – creates the XML and WHTEKO files needed for a new application – do this first! Use the menu: Project > WebHub > New AppID
- New Project – create the DPR and the unit containing TtpProject, with the events all coded for you. Use the menu: File > New > Other > Projects > WebHub Application and reference http://webhub.com/dynhelp:alias::newprojwizhowto for detailed steps for creating your first hello-world app.
- New Form – use this to add a module into an existing project. File > New > Form > WebHub Form
Modules aka Panelware
When Delphi first came out with form inheritance, TPack started leveraging inheritance to allow for user interfaces that would snap together in a way that was suitable for prototyping and testing. As WebHub applications on production servers usually prefer a minimalist GUI, this made sense. At first, we called these snap-together forms "panelware". WebHub panels were often re-used in multiple projects. More recently, we have been talking about standard and custom "modules", where the GUI is optional.
Let's illustrate this by reworking the banner idea we worked with earlier in listing 3. Of course, you would want that triggered from a web page through a TwhWebAction component. In addition, for testing, you might want the feature triggered by a button click.
Ideally, you would create two new units, a datamodule and a form. You would do this using the New Form Wizard. You would put the non-visual functionality into the datamodule (i.e. the TwhWebAction), and you would put the visual button into the form. Now the form would be a special form, descending from TutParentForm in TPack. This type of form automatically adds itself as a "panel" into the WebHub GUI. If that form is created first, it will be the first panel. If it is created third, it will be the third panel.
For advanced WebHubbers who want extra credit, it is possible to invent a keyword to associate with the new feature, say "banner". (This is worth doing if you intend to on-sell your module to other WebHub programmers.) You could then add a bit of code to your TtpProject events such that the core code in the datamodule and the GUI would be brought in based on configuration entries in your application-level config file.
The custom configuration is shown in figure 3. Notice that the banner feature is "Enabled with GUI" by default, yet it is "Enabled" on a server which has been labeled as "production." The Delphi code which makes the feature come and go based on the configuration is shown in listing 9.
Fig. 3: ZMAdmin, used to vary the use of the banner feature for development vs production.
procedure TDMSampleForWHProject.ProjMgrDataModulesCreate3(
Sender: TtpProject; var ErrorText: String;
var Continue: Boolean);
begin
CreateStandardWHModules;
if (pWebApp.Startup.CustomModuleStatus('banner') <>
mstatusDisabled) then
Application.CreateForm(TDM001, DM001);
{ Special Comment for DataModules - do not delete!
This comment is used by the WebHub Wizard to position
non-gui CreateForm statements for you, just above here.
You may add your own CreateForm statements as well,
either above or below this comment, as you wish. }
end;
procedure TDMSampleForWHProject.ProjMgrDataModulesInit(
Sender: TtpProject; var ErrorText: String;
var Continue: Boolean);
begin
InitCoreWebHubDataModule;
InitStandardWHModules;
if (pWebApp.Startup.CustomModuleStatus('banner') <>
mstatusDisabled) then
DM001.Init;
end;
procedure TDMSampleForWHProject.ProjMgrGUICreate(
Sender: TtpProject; const ShouldEnableGUI: Boolean;
var ErrorText: String; var Continue: Boolean);
begin
{$IFNDEF PREVENTGUI}
if ShouldEnableGUI then
begin
Application.CreateForm(TfmWebHubMainForm,
fmWebHubMainForm);
CreateStandardWHModulesGUI;
if pWebApp.Startup.CustomModuleStatus('banner') =
mstatusEnabledWithGUI then
Application.CreateForm(TfmAppPanel, fmAppPanel);
{ Special Comment for Forms - do not delete!
This comment is used by the WebHub Wizard}
end;
{$ENDIF}
end;
Listing 9: Creating modules based on status in application-level config file
When you are in a rush, you probably would not take the time to separate the GUI, give the feature a name, and load it conditionally based on configuration entries. However, if you wanted to develop a module to sell to other WebHub developers, or if you wanted to compile one large application for multiple purposes and needed to be able to turn major features on and off for various customers, you might take advantage of this approach.
Any WebHub application can surface some or all of its features via the standard SOAP interface
SOAP
Any WebHub application can surface some or all of its features via the standard SOAP interface, and we definitely recommend this. Precisely, any TwhWebAction derivative can be SOAP enabled by toggling the SOAPCallOk property from False to True.
This is demonstrated in the "spam aversion" demo, http://demos.href.com/htun. If you click into that demo, you can see how SOAP documentation is generated automatically, both human-readable and everything needed for software interfacing. In that demo, use the [Source] link to see all the Delphi code, especially the whStopSpam_fmWh.pas file which shows how to add a custom method with in and out parameters.
Customer Comments
I thought you might like to hear from "ordinary" Delphi programmers have to say about WebHub. The following two comments are from people who have built significant ventures using WebHub and Delphi. The first operates in Germany and the second in the USA.
“We have been working with WebHub since March 2000. At that time, we intensively evaluated web development options: Java, PHP, ASP, diverse frameworks in each of these languages. Even at that time, none of these evaluated tools impressed us with their performance. Also, the cost effectiveness and usability was often unbelievably lacking. Whoever has even once labored with Java and Struts and their XML will understand exactly what I am talking about. After months of searching and evaluating, I found href.com.
It was like a miracle. We could finally develop our real estate portal in Delphi, logically and consistently. It was wonderful.
The performance, the stability, the ease of use, the simplicity -- all this was, and still is today, the basis for us to say that the WebHub framework is the number 1 choice for anyone who wants to develop a stable, high-traffic, modular, high-performance web application.
We know Java, we know PHP, we know Ruby and Ruby on Rails. Yet, if we were to build our real estate portal again, starting today, we would do it with 100%-awareness with the friendly WebHub.
If it were possible to give 5 stars to WebHub, we would give it 6 stars. At this point, many, many thanks to Ann, for the always-friendly, high quality technical support, the quick clarification of ideas and quite simply for the best web tool which I use daily.”
-- Andreas Orth, www.my-next-home.de, customer from 2000 to 2009
“We have had several iterations of migrating to ASP.Net and all have failed in matching or even approaching the performance and the productivity of Delphi + WebHub. All of these attempts have been by professional asp.net developers.
Our competition (using ASP.Net, ASP, PHP, Java) have not been able to approach the complexities, performance, etc., we have attained on our site -- regardless of the number of developers they commit.”
-- John Correa, www.res.net, customer from 1997 to 2009
Licensing and Source Code Availability
We have a fine-grained way of providing source code. We recommend that you start with a free evaluation license (www.href.com/trywhub) and make sure that you are in love with WebHub. The latest prices are always available at http://www.href.com/hrefshop.
WebHub is available for Delphi 6 and above; Delphi 2009 is recommended. TNativeXml, ZaphosdMap and most of TPack also compile in Kylix 3 and Delphi for Dot Net through D2007. TNativeXml additionally compiles under FreePascal.
Fig. 4:. Once more where we started off at the cables suspending the Brooklyn Bridge, April 2004.
Conclusion
In these articles, I've walked you through the facets of WebHub which contribute to its unique level of power and flexibility. I invite you to use this knowledge -- in Delphi, with WebHub -- or otherwise.
Who should build apps with WebHub? Ideally, WebHub is for programmers who love expressing themselves in Object Pascal, who are interested in skinning their web application for multiple audiences, who need to translate their site content into two or more lingvos, who see advantages in partnering with a web artist, and who want to build something long-lasting.
I have been very quiet about WebHub since 2002; we were consumed with extensive refactoring. We are now officially open again for new customers, and I look forward to hearing from readers with questions or comments. Reach me through our site, http://www.href.com/contact.