HTML template component

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

Table of contents

What is this
Introduction
Possibilities
Available versions, downloading
How to install
Template page syntax
Usage

Properties
Methods
Events
How to create template page
How to prepare report
OnOpenURL event
OnScriptRun event
MS ActiveX Scripting

Professional version's advantages
How to buy and download the source code
Contact information
Useful Internet 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, SGML, text) page from template.
However it works at 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, Netscape Composer, MS FrontPage, MS Word, Notepad and any other.

Introduction

Template page script may contain absolutely all what you want and what the scripting language accept.
It may, for example, iterate through dataset, move to any dataset position, make SQL query and so on.
How it works. Report creation process contains two steps:

creation of template script from template page

execution of the script to receive the end report

Template page source

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

|

HTML template component
Step 1: creating a template script

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

Step 2: executing the template script and receiving report

Script engine

+

Application's objects and data

|

Report

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

Template page contains:

Simple text. It will in end report as is. It has hexadecimal representation in script. All characters including line breaking and space are represented in script as two hexadecimal digits.

Template code. There are some different types of template code: code fragments, expression, page instruction.

See below about template page syntax.

Possibilities, features

I. Customized template code tags.
By default it is "<template" and "/>".
You can setup own tag, for example "<%" and "%>" as is used by Microsoft's ASP and Sun's JPS.
See below in detail.

II. Customized text output functions formats.
By default it is write_hex("%s") and write_str(%s).
You can setup, for example, report.out_x("%s") and report.out(%s) or any other in dependence of scripting language and application's objects hierarchy.
See below in detail.

III. Template text can be loaded from any URL. By default only "file://" URL type is defined.
You can provide method to load from other URL types like:

http://

ftp://

database://

any other

It is very flexible to load report templates from database BLOB fields.
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.

IV. The "@ include file=" instruction allow to prepare report from any number of pieces.
For example, report header, company logo, report footer etc.
See below in detail.

V. Component is compatible with any type of script engines and scripting languages.
See below how to use with MS ActiveX scripting and the ActiveX Shell technology.

VI. Component allows to create a reports of any complexity: simple dataset, master / detail, filtered, with counting any functions on columns.

Available versions, downloading

Available compiled versions for:

C++ Builder 3

C++ Builder 4

C++ Builder 5

Delphi 3

Delphi 4

Delphi 5

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.
Install html_template_reg.pas from Menu > Component > Install Component.
By default HTML_Template will 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. Also see examples below.

Template page syntax

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 = Query1 while not dataset.EOF />	set dataset = 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") />	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 text that will in end report as is. It has hexadecimal representation in script. All characters including line breaking and space are represented in script as two hexadecimal digits.	write_hex("3C7461626C653E0D0A")

Syntax notes

Default tags are used in examples above. You can setup own tags instead of "<template" and "/>" tags. For example "<%" and "%>" as is used by Microsoft's ASP and Sun's JPS. It is possible to use ANY other. For example, "<template>" and "</template>" pair will not so bad. Or <?template and ?> will be all right too.

You can setup own text output functions formats instead of write_hex("%s") and write_str(%s) that will in corresponding to scripting language syntax and application's objects hierarchy.

Usage

Properties

Name	Type	Default value	Description
URL	String	file://template.html	URL to the template page source of report. It is used by Prepare function.
Code_begin	String	<template	Template code open tag.
Code_end	String	/>	Template code close tag.
Expr_prefix	String	=	Expression prefix.
Write_Hex	String	write_hex("%s")	Format for hexadecimal string output function.
Write_Str	String	write_str(%s)	Format for expression result output function.
Line_length	Integer	50	Maximum length of one piece of long string which will be placed as hexadecimal string. It is needed if used script engine can not support too long lines. Real script line length will be equal: length(Write_hex) + Line_length * 2. because one char is saved in two hexadecimal digits.
Language	String		It is readonly property which @page language= instruction can set only. It is available when OnScriptRun event handler is called. It is flexible if there is templates with different script languages.
RunScript	Boolean	True	If value is False then OnScriptRun event handler is not called. It is flexible for getting script without its auto execution.
Ready	Boolean	False	Readonly property. It is True when report ready.
ReportOutput	TComponent		Readonly propery. It is an output object for the script for use with the ActiveX Shell technology. It provides two ActiveX methods 'write_hex' and 'write_str'. See example below.
Text	String		Readonly property. It is a report text as single string when report ready. It is a report text if you are using ReportOutput object as output object for the script.

Methods

Name	Description
Create	constructor Create(AOwner : TComponent); This is constructor.
Prepare	function Prepare : AnsiString; It executes script preparation process with template page given as URL property. It returns the script as result.
Prepare_URL	function Prepare_URL (URL : AnsiString) : AnsiString; It executes script preparation process with template page given as URL parameter. It returns the script as result.
Prepare_Text	function Prepare_Text (text : AnsiString) : AnsiString; It executes script preparation process with template page given as single String given as text parameter. It returns the script as result.
DefaultOpenURL	procedure DefaultOpenURL(URL : AnsiString; var PageText : AnsiString); This is default URL open procedure. It returns document from URL as single String in PageText variable. OnOpenURL event handler may replace it. Note: only "file://" URLs are defined by default.
DoOpenURLError	procedure DoOpenURLError(URL : AnsiString; ErrorMessage : AnsiString); It calls OnOpenURLError event handler. Call this from OnOpenURL implementation if error occurs.

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 single String in PageText variable. It is possible to use DefaultOpenURL method in the implementation. See example below.
OnOpenURLError	procedure (Sender : TObject; URL : AnsiString; ErrorMessage : AnsiString) of object; It occurs when DefaultOpenURL can not load template page or when you call DoOpenURLError method. You can provide here a dialog box or show the error by any other way.
OnScriptRun	procedure (Sender : TObject; script : AnsiString) of object; Use it to execute script by used script engine. Parameter script is a script body. Same as returned by all Prepare... functions. See example below.

How to create template page
step 1.
Design HTML page using your favorite editor like Netscape Composer, MS Fron Page, MS Word etc. If it will report from dataset then add and edit table columns. Add company logo, report name and others.
For example, this is HTML code you have.

<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 page using your HTML editor or manually in HTML code.
For example, in Netscape Composer use Menu > Insert > HTML Tag.
VBScript code is added in this example.

<html>
<head>
   <title>Report example 1</title>
</head>
<body>
<h3>Company: <template= 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 = 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.
Now you have template page. Place it as file to disk or as BLOB field into database.

How to prepare report
step 1.
Place HTML_Template component to the form at Designer.
Edit component's URL property. Only "file://" URLs are defined by default. It is possible to define other URL types by using OnOpenURL event. See OnOpenURL event example.
step 2.
Define OnScriptRun event handler. That is needed to execute prepared script. See OnScriptRun event example.
step 3.
Call component's Prepare method. Prepare method does this:

loads template page text from URL

prepares script

calls OnScriptRun event handler

returns prepared script as result

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

procedure Form1.html_template1OpenURL(Sender : TObject; URL : AnsiString;
                                      var PageText : AnsiString);
var sql_text : AnsiString;
         sql_query : TQuery;
begin
// It is possible to use "abbrev" function defined in html_template module
// to check that one string begins like another
if abbrev(URL, 'database://' ) then begin
    with TQuery.Create(nil) do begin
     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
    (Sender as THTML_Template).DefaultOpenURL(URL, PageText);
end;
end;

OnScriptRun event example
How to run script ? It is your choice. It is possible your application already uses some script engine. If it is then just write template page compatible with your script engine and execute the script at this event handler.
The example below uses the ActiveX Shell technology and MS ActiveX Scripting to enable scripting on Deplhi application. It is available for downloading. In detail about the ActiveX Shell technology for Delphi and C++ Builder see its manual. In detail about MS ActiveX Scripting see below. You need to have installed it to run the example.
This is example implementation for OnScriptRun:

uses
ComObj, activex_shell;
// ====== at the form declaration =====
Query1 : TQuery;
Query2 : TQuery;
SaveDialog1 : TSaveDialog;
// ====== at the form declaration =====
procedure Form1.HTML_Template1ScriptRun(Sender : TObject; script : AnsiString);
var scripting : Variant;
begin
// creating an instance of MS Script Control
scripting := CreateOLEObject('ScriptControl');
scripting.AllowUI := False;
scripting.Timeout := -1;
scripting.Language := 'VBScript';

// adding an objects to script control's name space
// 1. output object
scripting.AddObject('Output', obj_to_variant(HTML_Template1.ReportOutput));
// 2. other objects you want be accessible from template page code
scripting.AddObject('Query1', obj_to_variant(Query1));
scripting.AddObject('Query2', obj_to_variant(Query2));
// executing the script and receiving report
scripting.ExecuteStatement(script);
end;

Function obj_to_variant is provided by activex_shell module. As you see the ActiveX Shell technology is used here for quick creating of ActiveX objects from Delphi objects. Because MS ActiveX Scripting used as script engine works only with ActiveX objects.
The HTML Template component in example has properties values:
Write_Str := 'Output.write_hex("%s")'
Write_Hex := 'Output.write_str(%s)'
This is reason why we need ActiveX object with name 'Output' and two methods: 'Write_Str' and 'Write_Hex'.
Other objects at the script control's name space are corresponding to the template page code. You can provide any names / objects.
We recommend to use HTML Template component with the ActiveX Shell technology as in this example.

If you need to use HTML Template component separately then you have provide to the script engine two type of ActiveX objects: output object with 'Write_Str' and 'Write_Hext' methods and data objects.
Use Delphi ActiveX framework to prepare such ActiveX objects.

create an ActiveX Library

add Automaton Object

add properties and methods to the object

compile and register the library

This is example implementation for OnScriptRun. It uses MS ActiveX Scripting but does not use the ActiveX Shell technology:

// creating an instance of MS Script Control
scripting := CreateOLEObject('ScriptControl');
scripting.AllowUI := False;
scripting.Timeout := -1;
scripting.Language := 'VBScript';
// adding your objects to script control's name space
// you have to provide an output object and data objects
scripting.AddObject('Output', CreateOLEObject('My ActiveX output object'));
scripting.AddObject('Data1', CreateOLEObject('My ActiveX data object 1'));
scripting.AddObject('Data2', CreateOLEObject('My ActiveX data object 1'));
// executing the script and receiving report
scripting.ExecuteStatement(script);

Note that in this case you can not use Text property of the component because report is stored in your output object.

MS ActiveX Scripting

You need MS ActiveX Scripting installed to run example above.
It consists from:

MS Script Engine

MS Script Control

MS Script Engine - already is on your computer if MSIE 4.0 or above is installed. It is possible to install separately with the distribution kit loaded from Microsoft site
http://www.microsoft.com/msdownload/vbscript/scripting.asp
Size: ~ 650 Kb
License: Freeware
GUID: {EE09B103-97E0-11CF-978F-00A02463E06F}

MS Script Control - is necessary for use the MS Script Engine by your application. It is possible to install with the distribution kit loaded from Microsoft site
http://msdn.microsoft.com/scripting/scriptcontrol/default.htm
Size: ~ 250 Kb
License: Freeware, see site
GUID: {0E59F1D5-1FBE-11D0-8FF2-00A0D10038BC}

Professional version's advantages

Now 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.

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

Personal license,
single user or one computer 40 $ Buy it

Company license,
any number of users and computers within one company 90 $ Buy it

We will provide too the ActiveX Shell technology used in examples as compiled files. Its sources are available separately.

Contact information

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

Useful Internet links

ActiveX Shell technology page

HTML Template component page

Delphi and C++ Builder components page

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

I.	Customized template code tags. By default it is "<template" and "/>". You can setup own tag, for example "<%" and "%>" as is used by Microsoft's ASP and Sun's JPS. See below in detail.
II.	Customized text output functions formats. By default it is write_hex("%s") and write_str(%s). You can setup, for example, report.out_x("%s") and report.out(%s) or any other in dependence of scripting language and application's objects hierarchy. See below in detail.
III.	Template text can be loaded from any URL. By default only "file://" URL type is defined. You can provide method to load from other URL types like: http:// ftp:// database:// any other It is very flexible to load report templates from database BLOB fields. 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.
IV.	The "@ include file=" instruction allow to prepare report from any number of pieces. For example, report header, company logo, report footer etc. See below in detail.
V.	Component is compatible with any type of script engines and scripting languages. See below how to use with MS ActiveX scripting and the ActiveX Shell technology.
VI.	Component allows to create a reports of any complexity: simple dataset, master / detail, filtered, with counting any functions on columns.

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. Install html_template_reg.pas from Menu > Component > Install Component. By default HTML_Template will 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, single user or one computer	40 $	Buy it
Company license, any number of users and computers within one company	90 $	Buy it