How to use events
Detailed explanation on how to use events from the API for more control over the XML.
- DOM API events
- The DOM API contains events that fire before and after something is happening with the XML. Allows developers to use events to change what happens at a very detailed level.
- Global API events
-
Editor events include
load,unload,xmlContextChangeand several others.
This script snippet creates a listener on the editor, and is called when the editor is done loading:
Editor.addEventListener("load",myLoadHandler);
The corresponding function myLoadHandler might look like this:
function myLoadHandler(evt)
{
var doc = Editor.getActiveDocument();
doc.addEventListener("XopusBeforeChildInserted", checkBreaks);
}
XopusDocument object, which is not quite the same as an XML document, but it comes close. When looking at the XopusBeforeChildInserted event, there are several properties of interest:
childNodecancelEventtarget
The childNode in this case is the new node that is being inserted. It will inserted under the target, in this case the parentNode. Using different methods for these objects (in this case an XopusElement) you can find out the names of these elements and set, modify or remove attributes, or more. Setting the cancelEvent property will stop the whole event from taking place.
The function checkBreaks is the handler that is connected to the listener in the example and it checks that no two <br/> tags occur next to each other.
function checkBreaks(evt)
{
var child = evt.childNode;
//if we insert a linebreak
if(child.getLocalName() == "enter")
{
var next = evt.nextSibling;
var previous = next
? next.getPreviousSibling()
: evt.target.getLastChild();
//don't insert it,in the following cases...
if (
(previous == null) //if at the beginning of paragraph
||
(previous != null && previous.getLocalName() == "enter") //if following an enter
||
(next != null && next.getLocalName() == "enter") //if followed by an enter
)
{
evt.cancelEvent = true;
}
}
}
Before or After
There are several events that fire before and after the event. What you are trying to achieve determines how you should sequence your events.
Other uses
It is hard to give examples of how to use events. Content Editor will do many logical things that are explained by the schema, but from time to time you want to do illogical things, perhaps copy a node, set a default attribute, or text, or something else. By listening to creations of nodes, splits, moves, mergers, or value modifications, you can add whatever functionality or feature you need to change your XML for your users.