Documentation Center

How to use events

Using events from the API is a great way to get more control over the XML, and to assist users in an even better way.

It takes some knowledge of JavaScript, and a slight understanding of the API to work with it, but very nice things can be done with it.

WithinSDL LiveContent Create events are called when certain things occur. This can be listened to by creating an eventlistener. The events available in SDL LiveContent Create a list of DOM API events. Eventlisteners need to be called on an object. Event have properties that can be used to manipulate the parts of the event.

To start listening it is best to first start with a line of script that allows you to know when to start listening:

Editor.addEventListener("load",myLoadHandler);


This creates a listener on the Editor, and is called when the editor is done loading.

The 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 and XopusDocumentobject, which is not quite the same as and XML document, but it comes close. When looking at the XopusBeforeChildInserted event, several properties can be 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, set, modify or remove attributes, or more. Setting the cancelEvent property will stop the whole event from taking place.

The handler that is connected to this listener in the above example, checkBreaks 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,     
      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. Depending on what you want to do you might want to take a look at doing it sooner or later.

Other uses

It is hard to give examples of how to use this. SDL LiveContent Create will do a lot of things all on its own, 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 for your XML or for your users.