|
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.
Would you have any troubles using this software, please feel free to write to [email protected].
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.
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.
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.
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:
XML attribute | HKPAPI property | Comment |
---|---|---|
name | hkp_NAME | |
version | hkp_VERSION | |
section | hkp_SECTION | |
description | hkp_DESCRIPTION | |
hint | hkp_HINT | |
icon-large | hkp_ICON_LARGE | Not yet supported (ignored) |
icon-small | hkp_ICON_SMALL | Not yet supported (ignored) |
copyright-short | hkp_COPYRIGHT_SHORT | |
copyright-long | hkp_COPYRIGHT_LONG | |
icon-caption | hkp_ICON_CAPTION | Not yet supported (ignored) |
enabled | hkp_ENABLED | |
author | hkp_AUTHOR | |
phone | hkp_PHONE | |
company | hkp_COMPANY | |
mailing-address | hkp_MAILING_ADDRESS | |
hkp_EMAIL | ||
url-home | hkp_URL_HOME | |
url-download | hkp_URL_DOWNLOAD | |
mode-console | hkp_MODE_CONSOLE | |
mode-show-status | hkp_MODE_SHOW_STATUS | |
mode-in-text-full | hkp_MODE_IN_TEXT_FULL | |
mode-in-text-selected | hkp_MODE_IN_TEXT_SELECTED | |
mode-in-word-at-cursor | hkp_MODE_IN_WORD_AT_CURSOR | |
mode-save-first | hkp_MODE_SAVE_FIRST | |
program | No mapping | Used by HKPXML itself |
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.
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
output
Data
func
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
addInt
get
getInt
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);
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.
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.
|