NAME
XML::XMetaL::Base - Base class for customization package handlers
SYNOPSIS
package XML::XMetaL::Custom::Bingo;
use strict;
use warnings;
use base qw(XML::XMetaL::Base);
...In the On_Macro_file_load macro in an .mcr file:
...
use XML::XMetaL::Bingo;
...
$handler = XML::XMetaL::Bingo->new(-application => $Application);
...
$dispatcher->add_handler(
-system_identifier => "bingo.dtd",
-handler => $handler
);
# The dispather forwards the method call to the handler:
$dispatcher->On_Macro_File_Load();DESCRIPTION
The XML::XMetaL::Base class is a base class for XMetaL customization package handlers.
Subclasses of XML::XMetaL::Base must implement handlers for XMetaL events. There are two types of events triggered by XMetaL:
Macro Events
On Insert Events
Both event types are described in more detail below.
Macro Events
This is the most common type of events. They are triggered by actions such as opening and closing documents, dragging and dropping objects, etc. They are described in the Event Macros section of the XMetaL Programmer's Guide.
Macro events have names like On_Document_Open_Complete, and On_Double_Click. When a macro event is triggered, a macro of the same name in the .mcr file is run. Which .mcr file that is used is determined by the system identifier in the DOCTYPE declaration of the currently active document. For example, if the system identifier points to the file bingo.dtd, then event macros in the file bingo.mcr will be triggered.
When not using XML::XMetaL, the code in a macro can grow quite complex. This macro code has several drawbacks. For example, a macro cannot be reused by other customization packages, unless you put it in the global macro file xmetal.mcr. On the other hand, if you do that, then your application cannot be easily distributed, because your updated xmetal.mcr may overwrite someone elses updated xmetal.mcr.
With XML::XMetaL, macros are used in a different manner. Each macro, except the On_Macro_File_Load macro, where the XML::XMetaL framework is instantiated, contains only a single line of code, of the form:
$dispatcher->Some_Macro();where Some_Macro is the name of the macro triggered by XMetaL. The dispatcher forwards the method call to an event handler.
For example, the handler called by macros in bingo.mcr could be XML::XMetaL::Custom::Bingo. XML::XMetaL::Custom::Bingo would be a subclass of XML::XMetaL::Base.
XML::XMetaL::Custom::Bingo is a front end, a Facade (if you are into design patterns) for all the code that makes up the Bingo customization package.
Behind the facade, you can hide as much functionality as you like, you can develop as many classes as you like, you can develop using OO techniques and you can reuse as much as you like, without XMetaL knowing about it.
You no longer have any need to modify xmetal.mcr, you don't have to worry about global variables spilling over from other customization packages and fritzing things up.
In all, if you are doing heavy customization, or implementing customization packages for many different DTDs, using XML::XMetaL will speed up your work and help you keep your code nicely structured.
You can also take external control of XMetaL, for example with a test script, that runs automated unit or function tests.
On Insert Events
On insert events are triggered whenever a user inserts a new element in a document. By default, XMetaL inserts a tag pair, specified in a .ctm file. It is also possible to have an on insert event trigger a macro. This macro is also specified in the .ctm file. There is one .ctm file per customization package, so for the Bingo package used as an example above, there would be a bingo.ctm file.
When using XML::XMetaL, each on insert event macro should trigger a call to the event handler, as usual via the dispatcher. The XML::XMetaL convention is to prefix all methods processing on insert macros with the prefix ctm_ followed by the name of the element to be inserted. A method call for inserting the element list would thus look like this:
$dispatcher->ctm_list();If you stick to this convention, future versions of XML::XMetaL will be able to use introspection techniques to automatically update .ctm files when methods are added or removed from a handler.
Constructor and initialization
$handler = XML::XMetaL::Bingo->new(-application => $Application);Note that XML::XMetaL::Bingo is a fictive subclass of XML::XMetaL::Base. XML::XMetaL::Base, being a base class, is never instantiated directly.
Handlers are always instantiated in an On_Macro_File_Load macro, because this ensures that a handler will be instantiated the first time a document of a particular document type is opened.
See XML::XMetaL for more information.
Class Methods
None.
Public Methods
None, but see the AUTOLOAD section below.
AUTOLOAD Method
The AUTOLOAD method provides default event handlers for all events not explicitly specified. These default handlers are a major reason for subclassing event handlers from XML::XMetaL::Base in the first place.
The default event handler will open an XMetaL alert box and display a message telling that no handler has been implemented for this event. This provides a more graceful way to handle missing event handlers than just raising an exception and crashing out of the application.
ENVIRONMENT
The Corel XMetaL XML editor must be installed.
BUGS
A lot, I am sure.
Please send bug reports to <henrik.martensson@bostream.nu>.
SEE ALSO
See XML::XMetaL.
AUTHOR
Henrik Martensson, <henrik.martensson@bostream.nu>
COPYRIGHT AND LICENSE
Copyright 2003 by Henrik Martensson
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.