Documentation Center

How to use events

Detailed explanation on how to use events from the API for more control over the XML.

It takes some knowledge of JavaScript and the API in order to work with events, but very nice things can be done with them. Within Content Editor , you can keep track of events by creating an event listener. Event listeners need to be called on an object. Events have properties that can be used to manipulate the parts of the event. Here are lists of the events available in the API:
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, xmlContextChange and 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);  
}
As you can see this event is attached to the XML document that is loaded. This document is actually an 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:
  • childNode
  • cancelEvent
  • target

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.