Macros

Macros

Macros are HTML files, although they must be formatted as valid XML, e.g. no unclosed tag shortcuts etc. The HTML provides the user interface and JavaScript methods are used to provide the macro functionality. Macro files must contain certain elements for them to be recognized by the application. At startup the application scans the macro folder to find valid macro files (see Configuration - Settings for details). The macros which are discovered will be listed in the Macros menu.

The macro can access a number of objects provided by the host application, including the HL7 message currently being edited, the predefined databases (Configuration - Databases) and file I/O methods for reading and writing files to/from the predefined bucket locations (Configuration - Message Buckets) - these are the only folders that the macro is allowed to perform file I/O on, for security and safety reasons.

Macros are loaded and executed in a web browser panel, provided by Windows, which follows the security settings of your system. It is possible for your security settings to disallow certain activities which may affect macros running in QuickViewHL7 - I have not encountered problems yet and have not had any reports of such from users.

The web browser panel will be referred to in this documentation as the macro host. The window which contains the macro host also has an embedded 'console' panel, which is used to display error text and other outputs from the macro scripts. This is referred to as the console below.

Refer to the example macro files for complete examples of the following specifications, detailed code examples are not shown here.

Macro XML Blocks

Macro Header

An XML header block must be included, defining metadata about the macro (see example macro files). The header declares a 'qvm' namespace, used to identify XML elements which relate to the QuickViewHL7 macro manager. Elements of the header are:

macroname	Used as the caption in the Macros menu.
purpose	Appears as tooltip text when you mouse over a macro name in the menu.
errortrapping	Error trapping determines how the macro host will try to handle runtime errors in the macro. errortrapping options: (browser,console,ignore) default is console. When a trappable error occurs in the script, it can be displayed in the console, displayed as an HTML exception in the browser view, or ignored (probably not a good idea).

Include Directives

A single XML fragment may be used to specify file include directives. The includes XML fragment will
not be present when the document is loaded into the macro hoost at run-time, this section will be replaced with the contents of the include file specified.

File pathnames are relative to the location of the macro file, so subdirectories below the macro
location may be used. The macro file location must be accessable (at least readable) to the user who
started the application, and these include files should therefore also be accessable.

There are a variety of security issues which can cause the web browser panel to fail to load includes
when using the standard HTML include statements, while attempting to load local file-system hosted
files instead of files served up by a web server. Rather than tackle all the causes and user
interventions associated with these issues, I am implementing this file insertion technique, which
simply depends on the user access rights etc. of the person running the application.

Include types:

css	the named file will be embedded in a <style> section - the file itself should not contain the style tags.
js	the named file will be embedded in a JavaScript <script> section - the file should not contain the script tags.
other	The file will be embedded in the HTML without any wrapper tags, in this case the file should contain whatever element tags are required to make it valid part of the HTML.

Note: at this time, only one includes section will be identified and replaced in the document.

Some of the example files include minified jQuery 1.8 (which is also installed with the macro files). This is not required in your macros, but I have used it for convenience, mainly to use jQuery selectors instead of getElementById(). As jQuery is documented in many places on the web, not much explanation of it is given in the macros.

Script Blocks

After a macro is loaded and made ready to run, the JavaScript function MacroStart() will be called. This is where your macro should perform initialisation and begin doing things which do not need to wait for user interaction. As an alternative, some of the example macros which include jQuery are using the jQuery $(document).ready() method
instead if using MacroStart()

Macro Host Environment Methods

The macro host environment provides several methods to the scripting run-time:

CurrentEditorFocus()	Method returning an HL7 index object, with these properties: Segmentidx FieldIdx RepeatIdx ComponentIdx
PreferredEditorFocus(segment-index, field-index)	Tells the editor which segment and field should be selected AFTER the macro has exited. If field-index is less than zero then the segment will be selected and not expanded. Useful after the macro has updated part of the file in the editor, when you want it to be in focus afterwards.
CloseMacroWindow()	Terminates the macro and closes its host window.
NewHL7(string)	Returns a HL7Message object, after parsing the provided string.
ConOut(string [, arguments])	Writes a string out to the console, when you want to trace what is happening in your script. The string may use C# formatting notation, if arguments are included, e.g. window.external.ConOut("Segment index={0}, type='{1}'", segIndex, segType)
RefreshEditorOnClose()	Method which should be called if your script has changed the HL7 message in the editor. Tells the application that the current file has been changed, makes the editor tree view refresh after the macro has closed.

Macro Host Environment Objects

The macro host run-time environment provides a number of objects which allow the macro script to access and interact with the QuickViewHL7 application. These objects are accessed as members of window.external. A summary of the available objects follows.

CurrentHL7	An HL7Message object representing the file currently being edited. Members of this object are: SegmentCount() returns int TypeCount(segment-type) returns the number of segments with specified type FindSegment(type, instance) returns segment-index GetSegment(segment-index) returns string SetSegment(segment-index, string) InsertSegment(segment-index, string) DeleteSegment(segment-index) GetField(segment-index, field-index) returns string GetFieldJSON(segment-index, field-index) returns JSON string SetField(segment-index, field-index, string) GetUniqueKey(type) use type 'guid' to get a guid, anything else returns a timestamp LoadHL7(string) LoadSegments(HL7Segments-object) ToString() returns the full HL7 message
IO	An object providing file I/O methods: LoadFile(bucket-name, file-name) returns string LoadHL7(bucket-name, file-name) returns HL7Message object SaveToBucket(bucket-name, file-name, HL7-string, bool-allow-overwrite) SelectBucketContents(bucket-name) returns array of file names GenerateBucketList(element-id, bucket-name) generates a dropdown list element element-id - the id assigned to the HTML select element which is created bucket-name - the default bucket to be selected
ScriptDatabase	An object providing database methods: ExecuteNonQuery(database-name, sql) returns outcome string SelectToJSON(database-name, sql) returns a JSON object definition with these properties: Error - if something went wrong RowCount - number of rows retrieved Rows - array of rows, each of which is a dictionary of column-names and values.