HTML Template component

allows to create HTML, XML, and text reports
in Delphi and C++ Builder application

Table of contents

What is this
Introduction
Template page syntax

Available versions, downloading
How to install

Usage

Properties
Methods
Events

How to create your report - step by step
OnOpenURL event handler example
MS ActiveX Scripting
Professional version's advantages
How to buy and download the source code
Contact information
Useful links

What is this

This is a component for Delphi and C++ Builder.

Need to create HTML, XML or text reports ?! Use this !
It works like well known ASP, JSP and PHP technologies and allows to produce HTML (XML, text) page from the template.
However it works at the application side without Web server engine and can access application's objects and data.
To design report view it is possible to use your favorite editor. For example, MS FrontPage, MS Word, Netscape Composer, Notepad and others.

Introduction

Suppose you need to create some kind of report in your application. HTML formatted, XML, or plain text formatted report. Actually it can be any "open text format", like RTF, PDF, which structure you know. And you would like to have one file with all information about the report. Including styles, graphical design, and logic.

You can use this component to do it. Although the name of the component is "HTML Template", the generated report can be in any text format. We use this name because HTML is generally user for reporting in applications.

The idea of template page itself is similar to ASP, JSP, PHP pages. It is a text with pieces of script between special tags. For preparing report the component outputs the text as is and interpret script code and expressions. For instance, you have the following report template:
<html>
<body>
<template = "Hello " + "world!" >
</body>
</html>
You see simple expression "Hello " + "world!" here. We will have the following execution result:

<html>
<body>
Hello world!
</body>
</html>

Template page script may contain absolutely all algorithms and routings which you need to produce result report. See below the template page syntax. Scripts may, for example, iterate through dataset, move to any dataset position, make SQL query and so on. You can use VBScript, JScript, or any other supported by MS ActiveX Scripting.

The component allows to create reports of any complexity: simple dataset, master / detail, filtered, with counting any functions on columns, with additional UI form for report parameters. You can find examples in the distribution kit.

How it works. The report execution process contains two steps.

Creation a script from template page. Script is a program on the used scripting language.

Execution of this script program.

For instance we have the following template page:

...
<table>
<template
set dataset = this.Query1
do while not dataset.EOF
/>
<tr><td> <template = dataset.FieldValues("name") /> </td></tr>
<template
dataset.Next()
loop
/>
</table>
...

After first step we will have a script program like this:

...
out.write_hex("3C7461626C653E0D0A")
set dataset = this.Query1
do while not dataset.EOF
out.write_hex("0D0A3C74723E3C74643E0D0A")
out.write_str( dataset.FieldValues("name"))
out.write_hex("0D0A3C2F74643E3C2F74723E0D0A0D0A")
dataset.Next()
loop
out.write_hex("0D0A3C2F7461626C653E0D0A")
...

You can see that the script program is a template page turned "inside out". Text pieces from template page have hexadecimal representation in script. We did it as the best way to represent in the script program all textual data like like breaks, spaces, quotas, etc.

After execution of this script program we will receive the end report:

...
<table>
<tr><td> First name </td></tr>
<tr><td> Second name </td></tr>
<tr><td> Third name </td></tr>
...
</table>
...

Thus from technical point of view the report template is a program on the scripting language. This component prepares such program from the report template and executes it by using the ActiveX Shell technology. Script program uses objects and data from your application. You can use this and self variables inside report to access all components on the form (or DataModule) and published properties of the form.

Report template + Script engine:
ActiveX Shell technology + Objects and data
of the application = Result report

We consider the report creation process below step by step.

Template page syntax

There are the following kinds of template code: script code fragments, expressions, page instructions, simple text pieces.

Description	Syntax	Example	In script
Contain a code fragment valid in the scripting language. Including any declaration and expressions.	<template code fragment />	<template set dataset = this.Query1 while not dataset.EOF />	set dataset = this.Query1 while not dataset.EOF
Contain an expression code fragment valid in the scripting language. Only one expression is allowed.	<template = expression />	<template = dataset.FieldValues("name") />	out.write_str(dataset.FieldValues("name"))
Contain one page instruction. It works like compiler directives. Supported instructions: include - include and parse page by absolute URL page language - used scripting language	<template @ instruction />	<template @ include page = "file://page_header.html" /> <template @ page language = "VBScript" />	(script from included page) (nothing)
Any other text and tags.	text <tag > text text ...	This is a text that will be in end report as is. It has hexadecimal representation in the script program. All characters are represented in the script as two hexadecimal digits.	out.write_hex("3C7461626C653E0D0A")

Syntax notes

You can setup your own tags instead of "<template" and "/>" tags used in examples above. For instance, "<%" and "%>", as in Microsoft's ASP and Sun's JPS. Or "<template>" and "</template>" in XML style will be OK too. You can setup any other tags. See below in detail.
You can setup your own text output functions formats instead of out.write_hex("%s") and out.write_str(%s) that will in conform with used scripting language syntax. The used syntax is for VBScript. See below in detail.
The "@ include file=" instruction allows to prepare report from any number of pieces. For example, report header, footer, company logo, etc. See below in detail.
Report template will be loaded from any URL giver as URL property. We have defined method to work with "file://" URL type. You can support others by using OnOpenURL event. For example, for URL like:

ftp://
http://
database://
...

It is very flexible to load report templates from database. Database URL example:

database://select report_text from report_templates where report_type = "Report 1"
You need only to execute that query and get BLOB field text. See below in detail. Also see OnOpenURL example.

Available versions, downloading

Available compiled versions for:

C++ Builder 3

C++ Builder 4

C++ Builder 5

Delphi 3.02 (patched)

Delphi 4

Delphi 5

Delphi 6

Source code is compatible with Delphi 3 or above, C++ Builder 3 or above.
Latest version of the component is always available from the components download page.

How to install

1. Unzip archive htmltmpl.zip with subdirectories.

2. Directory CB3\ is for CBuilder 3 users.
Directory CB4\ is for CBuilder 4 users.
Directory CB5\ is for CBuilder 5 users.
Directory D3\ is for Delphi 3 users.
Directory D4\ is for Delphi 4 users.
Directory D5\ is for Delphi 5 users.
Directory D6\ is for Delphi 6 users.
Install html_template_reg.pas from Menu > Component > Install Component.
By default HTML_Template will be installed to "Apelseen" components page.

3. Just drop HTML_Template component to the form at Designer when need it.

Examples are located in the corresponding directories too.

Usage

Properties

Name	Type	Default value	Description
URL	String	file://template.html	URL of the report template source file. You can extend list of supported URL types by writing OnOpenURL event handler. See example.
OpenTag	String	<template	Template code open tag.
CloseTag	String	/>	Template code close tag.
Write_Hex	String	out.write_hex("%s")	Format for hexadecimal string output function. By default compatible with VBScript syntax.
Write_Str	String	out.write_str(%s)	Format for expression result output function. By default compatible with VBScript syntax.
Language	String	VBScript	You can set this property also by @page language= instruction in the report template page. The second way is flexible when there are report templates with different scripting languages.
Ready	Boolean	False	Readonly property. It is True when report is ready.
ReportText	String		Readonly property. It is the ready report text as single string when report is ready.

Methods

Name	Description
Create	constructor Create(AOwner : TComponent); This is a constructor.
Execute	function Execute : Boolean; It executes the report with template page given as URL property. It returns True in case of successful report execution. Use ReportText property to access result report.
ExecuteFromURL	function ExecuteFromURL (URL : AnsiString) : Boolean; It executes the report with template page given as URL parameter. It returns True in case of successful report execution. Use ReportText property to access result report.
ExecuteFromText	function ExecuteFromText (text : AnsiString) : Boolean; It executes the report with template page given as text parameter. It returns True in case of successful report execution. Use ReportText property to access result report.
DefaultOpenURL	procedure DefaultOpenURL(URL : AnsiString; var PageText : AnsiString); This is default URL open procedure. It returns document from URL as String in PageText variable. OnOpenURL event handler may replace this default routine. This default routine supports only "file://" URLs.
DoOpenURLError	procedure DoOpenURLError(URL : AnsiString; ErrorMessage : AnsiString); You should call this function in OnOpenURL event handler f there was any error. This function only generates OnOpenURLError even.

Events

Name	Description
OnOpenURL	procedure (Sender : TObject; URL : AnsiString; var PageText : AnsiString) of object; Use it to define your own URL types. It must return document's text from URL as PageText variable. You may call DefaultOpenURL method in the implementation. See an example below.
OnOpenURLError	procedure (Sender : TObject; URL : AnsiString; ErrorMessage : AnsiString) of object; It occurs when DefaultOpenURL cannot load template page or when you call DoOpenURLError method. You may provide here a dialog box or report the error by other way.
OnExecuteError	procedure (Sender : TObject; ErrorMessage: String); It occurs when any error happens, excepting a report loading error (use OnOpenURLError to handle).

How to create your report - step by step

Step 1.
Design HTML (XML, plain text, ...) page by using your favorite editor like MS FrontPage, MS Word, Notepad, Netscape Composer, etc. If you are going to create report from some datasets then add table columns and so on. Add the company logo, report name and others features.
For example, you have the following HTML for the report:

<html>
<head>
<title>Report example 1</title>
</head>
<body>
<h3>Company: </h3>
<table BORDER WIDTH="90%" >

<tr>
<td><b>Sale date</b></td>
<td><b>Items total</b></td>
<td><b>Amount paid</b></td>
</tr>

<tr>
<td></td>
<td></td>
<td></td>
</tr>
</table>
<br>
<b>AmountPaid total: </b>
</body>
</html>

Step 2.
Add template tags to the template page. VBScript code fragments and expressions are added in this example. You can use all published properties of the form (or DataModule) and all components on the form, plus some functions of those objects. See features of ActiveX Shell technology in detail where we consider all possibilities of access VCL objects from ActiveX model. The this or self keyword is reference to the form in the scripts. Use all scripting language features in the template page script. Like the flow control, iteration, and all others. VBScript is used in this example:

<html>
<head>
<title>Report example 1</title>
</head>
<body>
<h3>Company: <template= this.Query1.FieldValues("Company") /></h3>
<table BORDER WIDTH="90%" >

<tr>
<td><b>Sale date</b></td>
<td><b>Items total</b></td>
<td><b>Amount paid</b></td>
</tr>


<template
AmountPaid_sum = 0
Set dataset = this.Query2
dataset.First()
do while not dataset.EOF
/>
<tr>
<td><template = dataset.FieldValues("SaleDate") /></td>
<td><template = dataset.FieldValues("ItemsTotal") /></td>
<td><template = dataset.FieldValues("AmountPaid") /></td>
</tr>
<template
AmountPaid_sum = AmountPaid_sum + dataset.FieldValues("AmountPaid")
dataset.Next()
loop
/>
</table>
<br>
<b>AmountPaid total: <template= AmountPaid_sum /></b>

</body>
</html>

Step 3.
Save the report template to the file or as a BLOB (TEXT, VARCHAR, ...) field in the database. Set the corresponding URL property in the HTML Template component by Object Inspector.

Step 4.
Write some event handlers code and then call Execute method of the component. Use ReportText property to receive the ready report text. Congratulation!
See also example application and report templates from the distribution kit.

OnOpenURL event handler example

This is example implementation for URLs like "database://...".

procedure Form1.HTML_Template1OpenURL(Sender : TObject; URL : AnsiString; var PageText : AnsiString);
begin
// checking that URL starts with 'database://' if ( copy(URL, 1, length('database://')) = 'database://' ) then begin
    with TQuery.Create(nil) do begin      // the rest part of the URL is SQL
     SQL.Add( copy(URL, length('database://') + 1, length(URL)) );
     try
       Open();
       if FieldCount > 0 then PageText := Fields[0].AsString;
     except
       PageText := '';
     end;
     Close();
     Free;
    end;
end
else begin     // using default URL open routine
    (Sender as THTML_Template).DefaultOpenURL(URL, PageText); end;
end;

MS ActiveX Scripting

Please see ActiveX Shell technology page for detail about MS ActiveX Scripting in Delphi / C++ Builder application.

Professional version's advantages

All page instructions like @ include page and other @ instructions work only in professional version.

How to buy and download the source code

For commercial purposes and if you are interested in sources you have to buy the professional version.
Software will available at once after the registration from our secure web site.

We provide also ActiveX Shell technology source code with the professional version.

HTML Template component
(professional version, source code, compatible with D3 and above, CB3 and above)

Personal license,
for one developer 50 $ Buy it

Company license,
for any number of developers within one company 90 $ Buy it

Contact information

Send your questions and comments to support@apelseen.com
Apelseen software website is http://www.apelseen.com

Useful links

ActiveX Shell technology page

HTML Template component page

Delphi and C++ Builder components page

Version 2.2
Copyright (c) 1999, Apelseen software. All Rights Reserved.

1.	Unzip archive htmltmpl.zip with subdirectories.
2.	Directory CB3\ is for CBuilder 3 users. Directory CB4\ is for CBuilder 4 users. Directory CB5\ is for CBuilder 5 users. Directory D3\ is for Delphi 3 users. Directory D4\ is for Delphi 4 users. Directory D5\ is for Delphi 5 users. Directory D6\ is for Delphi 6 users. Install html_template_reg.pas from Menu > Component > Install Component. By default HTML_Template will be installed to "Apelseen" components page.
3.	Just drop HTML_Template component to the form at Designer when need it.

`HTML Template component` (professional version, source code, compatible with D3 and above, CB3 and above)
Personal license, for one developer	50 $	Buy it
Company license, for any number of developers within one company	90 $	Buy it