JavaScript API Event Handlers

Back to Developer Support 

EditMe's JavaScript API can call functions in specially named scripted pages during key site events. For example, if you want to track user logins, you might want a function called every time any user logs into your site. EditMe's event model can be used for this purpose.

Event handlers are JavaScript functions with specific names placed into a scripted page called EditMeScriptEvents (or any page name beginning with EditMeScriptEvents). To enable event handling on your site, make a new page called EditMeScriptEvents with the following page attributes:

• Edit in Plain Text
• Hide this page from the Index, Recent Changes, and Search
• MIME Type set to EditMe Scripted Page (text/vnd.editme.xm-js.page)
• Security set to Adminstrator View/Administrator Edit

Currently, not all events are implemented (see the table below to see what's implemented). Contact us if you are working on an application that requires any of the events we haven't gotten to yet, and we'll put a rush on it.

Note that these events do not fire when similar actions are performed by the JavaScript API. The purpose of these events is to run JavaScript code when something happens on the site through EditMe's web interface. 

The following events are either supported or planned. In the table, Function Name is the JavaScript function in the EditMeScriptEvents page that will get called when the event fires. Event Data is the value stored in an implicit "event_data" variable set when the function is called.

The following is a template that can be used to create a new EditMeScriptEvents page. Note that if EditMe finds the text "function editme_event_user_login()" in this page content, it will attempt to execute the event handler when a user logs in. It's important that the function not remain in the script commented out, and there must not be a space between the function name and the ().

<div>
<!-- other scripts may be optionally included here, as in:
   <script editme="process 'MySharedFunctions'"/>
-->
<script type="text/vnd.editme.js"><![CDATA[
/** EVENT HANDLERS **/
// this event fires whenever a user logs in
function editme_event_user_login() {
    var userName = event_data;
    // do something with userName here...
}
]]></script>
This page is not intended to be viewed.
</div>

A nice example of some code in an EditMeScriptEvents page and an idea of what it might be used for can be found in the wiki article, How To Add Custom Properties.

Troubleshooting Events

Event programming can be difficult due to the lack of feedback if something goes wrong. Here are some tips to help troubleshoot event scripts.

• Don't use the 'page' implicit variable in event scripts. It has no meaning in this context and will lead to errors.
• Test your event scripts by creating a scripted page for testing that processes the event script, sets the event_data variable, and then calls one of the event functions. This will show you whether there are errors in your script.
• If things aren't working, try stripping your event script down to something extremely simple and get that working, then build from there. For example, the following should always work, and will simply create a test data entry with the name of the page and a time stamp when a page is edited. You can modify this for use with other event handlers.
  function editme_event_page_update() {
    var de=data.get('test.'+event_data);
    if(de==null) {
      de=data.newEntry();
      de.key='test.'+event_data;
    }
    de.value=(new Date()).toString();
    de.save();
  }