Unicorn Enterprises SA

Unicorn XML Scripting Engine, Version 1.00.00
Plugin for HTML-Kit
Release Notes

This document describes the functionality of Unicorn XML Plugin for HTML-Kit, version 1.00.00.

The plugin will be referred as HKPXML in this document.

Getting Help

Would you have any troubles using this software, please feel free to write to [email protected].

Basic Concepts

HKPXML is an ECMAScript (also known as JavaScript) language interpreter, implemented as a plug-in DLL for HTML-Kit editor. HKPXML provides a collection of XML-enabling components, but does not implement any predefined processing scheme. Every particular XML processing application can be coded in ECMAScript. This ECMAScript application must be registered in HKPXML configuration file. When the application is registered, it is treated by HTML-Kit editor as a separate plug-in. The user of HTML-Kit can invoke ECMAScript programs registered with HKPXML the same way as she invokes conventional HTML-Kit plug-ins. Conceptually, each registered ECMAScript application can be treated as a separate plug-in, powered by the same HKPXML engine DLL.

What is ECMAScript

Informally speaking, ECMAScript is a standartized and vendor-independent incarnation of the popular Web scripting language JavaScript. The standardization is provided by the European Association of Computer Manufacturers (ECMA), the standard name is ECMA-262.

JavaScript is conforming to the ECMA-262 standard and could be considered a superset of ECMAScript. If you know already JavaScript, you can start using ECMAScript and Unicorn XML Scripting Engine instantly.

Installation and Configuration

The HKPXML engine DLL is contained in the file hkpxml.dll. This file must be placed into a directory where all HTML-Kit plug-ins are stored (something like c:\Program Files\Chami\HTML-Kit\Plugins).

The HKPXML configuration file is needed to store information about registered ECMAScript plug-ins. This file has XML format and normally has the name hkpxml.cfg. The name and the location for the configuration file is not fixed; the convenient place to store it can be the Config subdirectory of Plugins.

The exact path for the HKPXML configuration file must be stored as the value of Windows system variable named HKPXML_CONFIG. For example, if the name and location for the configuration file were chosen as described above, the value for HKPXML_CONFIG would be:

c:\Program Files\Chami\HTML-Kit\Plugins\Config\hkpxml.cfg

To add the definition for the HKPXML_CONFIG variable, use the folder Environment of the icon System of the Windows Control Panel.

When HTML-Kit performs registration of installed plug-ins, it calls the hkp_Register entry of HKPXML. HKPXML queries the system variable HKPXML_CONFIG to obtain the location of the configuration file. It then loads the file and registers all ECMAScript programs defined in this file as individual HTML-Kit plug-ins.

The HKPXML distribution comes with the sample configuration file hkpxml.cfg which can be used when HKPXML is installed the first time. This file can be later used as a template for defining custom ECMAScript plug-ins.

Configuration File

The configuration file is an XML document with a very simple structure. The root element, <hkpxml> contains a set of <plugin> children. Each <plugin> is an element with an empty content; attributes of this element correspond to the various property names supported by HTML-Kit plug-in API (HKPAPI). The following table describes mapping between attributes of <plugin> and HKPAPI property names:

When HKPXML DLL executes the hkp_Register section, it reads the configuration file, registering a separate plug-in for each <plugin> element encountered. Element attributes are mapped to HKPAPI properties, the attribute values are posted to HTML-Kit engine via calls to hkp_DataAdd.

The attribute program has the special meaning. It has no mapping to HKPAPI properties. This attribute must contain the full path to the ECMAScript program which implements the plug-in. The HKPXML DLL will use this information to locate the appropriate implementation script when the plug-in is invoked via call to the hkp_Main DLL entry.

You can choose any location for your ECMAScript programs which implement plug-ins. Furthermore, main ECMAScript programs can invoke other ECMAScript programs or other resources (for example, XSLT stylesheets). You can choose any convenient way to store related resources which form your plug-in applications.

To create a new HKPXML plug-in, create an ECMAScript program (and, if necessary, all other resources required by this program), then add a new <plugin> element to the HKPXML configuration file.

ATTENTION: HTML-Kit provides caching of plug-ins. When you modify the HKPXML configuration file and restart HTML-Kit, your modifications will not be activated instantly. In order to activate them, clear the plug-ins cache using the Tools / Install / Clear Plugins Cashe ... menu command, then restart the HTML-Kit. However, if you just update the ECMAScript program code (or any resources used by this code), without updating the configuration file, you do not need to clear the cache.

ECMAScript Binding for HTML-Kit Plugin API

In addition to the standard features, the ECMAScript engine in HKPXML provides the full support for HTML-Kit API (HKPAPI). Therefore, with HKPXML plug-ins can be developed completely in ECMAScript.

It is important to note, that unlike other development platforms supported by HTML-Kit, HKPXML ECMAScript does not require coding of two entry points: hkp_Register and hkp_Main. All information required by hkp_Register is supplied by HKPXML configuration file and is processed by HKPXML engine automatically; therefore, ECMAScript code must not implement hkp_Register section. The ECMAScript code implementing the plug-in is called in response to the hkp_Main request from HTML-Kit, that is, each time HTML-Kit is requested to execute the plug-in.

HKPXML ECMAScript engine also does not provide function equivalent to hkp_Main. When the plug-in is executed, the HTML-Kit simply evaluates the entire ECMAScript program. Input and output data objects are passed to the script as properties input and output of the special HTMLKit object.

The object named HTMLKit encapsulates the functionality related to HKPAPI. This object has the following properties:

input

the input data object

output

the output data object

Data

the data object constructor

func

the function used to invoke HTML-Kit built-in services

Properties input and output are eqivalent to the arguments pDataIn and pDataOut of the HKPAPI hkp_Main function. For example, to write the "Hello, World!" to the output window, the following ECMAScript code can be used:

HTMLKit.output.add("OUTPUT", "Hello, World!\n");

The name of the input file can be obtained as

var fileName = HTMLKit.input.get("FILE_NAME");

The property Data is a constructor for data objects; this property must be used in conjunction with the ECMAScript new operator. It is equivalent to the HKPAPI hkp_DataNew function. For example, the ECMAScript code

var input = new HTMLKit.Data();

is equivalent to HKPAPI code

HKP_STDATA *pDataIn;
pDataIn = hkp_DataNew();

In ECMAScript, there is no eqivalent to the HKPAPI hkp_DataFree function. Data objects are destroyed by the interpreter automatically, based on the internal reference counting mechanism.

The function func is equivalent to the HKPAPI hkp_Func function, and is used to invoke the built-in services provided by HTML-Kit. For example, the following code opens the specified file in a new editor window:

var input = new HTMLKit.Data();
var output = new HTMLKit.Data();
input.add("FUNC_NAME", "OpenFileEx");
input.add("FUNC_PARAM1", fileName);
HTMLKit.func(input, output);

Data objects, supplied by input and output properties of the HTMLKit object, or created via Data constructor, have the following function propeties:

add

Adds the string property to this data object

addInt

Adds the integer property to this data object

get

Gets the string property of this data object

getInt

Gets the integer property of this data object

The function add is equivalent to the HKPAPI function hkp_DataAdd. It is invoked using the following pattern:

data.add(propertyName, stringValue);

The function addInt is equivalent to the HKPAPI function hkp_DataAddInt. It is invoked using the following pattern:

data.addInt(propertyName, integerValue);

The function get is equivalent to the HKPAPI function hkp_DataGet. It is invoked using the following pattern:

stringValue = data.get(propertyName);

The function getInt is equivalent to the HKPAPI function hkp_DataGetInt. It is invoked using the following pattern:

integerValue = data.getInt(propertyName, defaultIntegerValue);

Error Handling

Errors can be encountered during execution of ECMAScript programs. The current release of HKPXML employs the simplified error handling scheme: when the unrecoverable error is encountered, the evaluation of a script is terminated and the detailed error information is displayed in the output window.

More sofisticated error handling cannot be developed at this point, since the standard error handling technology employed by HTML-Kit is not yet documented.

Errors encountered during the registration (for example, syntax errors in the configuration XML file) are currently not repored by HKPXML engine.

Sample Scripts

The HKPXML distribution comes with three sample scripts.

The first script, named hello.es, displays the "Hello, XML World!" phrase in the output window.

The second script, named es.es, grabs the content of the current input window, and executes it as the ECMAScript program.

The third script, named xslt.es, invokes the XSLT processor to transform content of the current input window. The URI for the XSLT stylesheet must be specified in the source document using the processing instruction

<?xml-stylesheet href="stylesheetURI"?>

The stylesheet URI reference is extracted automatically by the script. The stylesheet URI must represent the absolute path); the syntax is:

file://localhost/device/path/name.ext

For example, the file path d:\uxsl\bin\test\teilite.xsl will be represented by the following URI:

file://localhost/d/uxsl/bin/test/teilite.xsl

The result of transformation is displayed in a new window. Errors are reported, as usual, in the output window.

Two sample files, the sample source XML document uxpstd.xml and the sampe stylesheet teilite.xsl, are included in the set of demo files. Please, do not forget to place the correct URI in the xml-stylesheet processing instruction (the second line in uxpstd.xml) before running this sample.

This sample is functionally equivalent to the "cm uxt" plug-in created by Ciaran McCreesh ([email protected]). The difference is that "cm uxt" invokes Unicorn XSLT processor as an external engine; in our example the built-in engine of HKPXML is used instead.

All three sample scripts are registered in the sample configuration file hkpxml.cfg included into the distribution. Before trying these samples, please don't forget to assign correct locations to program attributes in the hkpxml.cfg file.