HTML template component

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
• Source code buy online
• Contact information
• Useful Internet links

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.
 

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 script and receiving the 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> ...

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, it will be standard 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 compiled versions for:

• CBuilder 3
• Delphi 3
• Delphi 4
• Delphi 5

Compiled versions for other Delphi and C++ Builder releases is not available now.
Use the source code with those releases.

Source code compatible with Delphi 3 or higher and C++ Builder 3 or higher.

Latest version of the component is always available from the components download page.
 

 

1.	Unzip archive htmltmpl.zip with subdirectories.
2.	Directory CB3\ is for CBuilder 3 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 source code is located in the corresponding directory ( CB3\, D3\, D4\, D5\ ) too.
Also see examples below.
 

Syntax notes

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

Properties

Methods

Events

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%" > <!-- this is table's header  --> <tr> <td><b>Sale date</b></td> <td><b>Items total</b></td> <td><b>Amount paid</b></td> </tr> <!-- this is table's first row  --> <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.

This is example of manually added VBScript code.
 

<html> <head>    <title>Report example 1</title> </head> <body> <h3>Company: <template= Query1.FieldValues("Company") /></h3> <table BORDER WIDTH="90%" > <!-- this is table's header  --> <tr> <td><b>Sale date</b></td> <td><b>Items total</b></td> <td><b>Amount paid</b></td> </tr>   <!-- this is table's first row  --> <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:

1. loads template page text from URL
2. prepares script
3. calls OnScriptRun event handler
4. 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 begin 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.

As you see in example above, some additional methods are used by template code: "First", "EOF", "Next", "FieldValues". Moreover we have to provide two methods named "write_str" and "write_hex" to output result from the script.

The example below uses the "ActiveX Shell" technology 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.

Note that you need MS ActiveX Scripting installed to run example.

This is example implementation for OnScriptRun.
 

// Query1 : TQuery; // Query2 : TQuery; // SaveDialog1 : TSaveDialog; uses   ShellApi, ComObj, HTML_report, activex_shell; procedure Form1.HTML_Template1ScriptRun(Sender : TObject; script : AnsiString);   var scripting, module: Variant;        report : THTML_Report; begin // creating an object which will provide a output functionality to the script    report := THTML_Report.Create(Self);   report.Name := 'Report';   try // assigning an output stream to that object   if not SaveDialog1.Execute() then Exit;   report.Stream := TFileStream.Create(SaveDialog1.FileName, fmCreate);     // ============================================= // Main execution block uses MS ActiveX Scripting // and the "ActiveX Shell" technology. // ============================================= // creating an instance of MS Script Control   scripting := CreateOLEObject('ScriptControl');   scripting. AllowUI  := False;    scripting. Language := 'VBScript';  // creating a script module by using the "ActiveX Shell" technology    module := scripting.Modules.Add('report_module', obj_to_variant(Self) );  // executing the script and receiving the report   module.ExecuteStatement(script);  // =============================================     // opening report   ShellExecute(Application.Handle,PChar('open'),PChar(SaveDialog1.FileName),                nil,nil,SW_SHOWNORMAL); // freeing of objects   finally     if report.Stream <> nil then report.Stream.Free;     report.Free;   end; end;

In the example one additional object is used to provide output functionality to script - "write_str" and "write_hex" methods. It is THTML_Report class which can be found in file all \ html_report.pas. The "ActiveX Shell" technology is used to create ActiveX object from Delphi object. That allows to use full object hierarchy in the script.

Of course it is possible to use HTML Template component separately. Just create ActiveX component by using Delphi ActiveX framework (File > New and then ActiveX > AutomationObject ). And then make OnScriptRun event handler as in example below.

In that case it is necessary just to provide a correct script execution. The ActiveX object must have methods that you decide to use in script, in example above it was  - "First", "EOF", "Next", "FieldValues". Plus two methods that  write to the stream. In example above it was  - "write_str" and "write_hex".

Implementation will like this:
 

... // creating an instance of MS Script Control   scripting := CreateOLEObject('ScriptControl');    scripting. AllowUI  := False;    scripting. Language := 'VBScript';  // creating your ActiveX object   report := CreateOLEObject('Your ActiveX object'); // assigning some parameters to that object // such as datasets, output stream // ... // adding your object to script control's name space   scripting.AddObject('report', report, True); // executing the script and receiving the report   scripting.ExecuteStatement(script);  ...

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}

Now all page instructions like @ include page and other @ instructions works only in professional version.

For commercial purposes you have to buy the professional version's sources with the license.

Go to our Components Purchase Page and buy it online. Maximum per two days after receiving the payment we send you sources with comments by e-mail and make it available for downloading from our secure web site.

Note that we will provide too the "ActiveX Shell" technology used in examples as compiled files. Its sources are available separately.

Contact person: Karim Yusupov

Send your questions and comments to  mailto:apelseen@mail.com?Subject=About HTML template component

Apelseen software website is http://www.apelseen.da.ru/
 

• ActiveX Shell technology page
• HTML Template component page
• Delphi and C++ Builder components page

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