Creating a Custom Editor

Overview

Custom editors are easy to create and use with the new Butter API. They consist of an instance of butter that has a Butter Communications Client ( CommClient ) connected to a Communications Server ( CommServer ) running in the Event Editor module.

This client is the object that will drive the functionality of your editor. Information about Track Events, Manifests, The Media's current time, and Dom Targets is all channelled through the CommClient using message listeners. Any modifications to a Track Event can then be channelled back through the CommClient to the CommServer.

Requirements

• An HTML file for the editor UI
• butter.js
• butter.comm.js

You can code your logic in a script tag in the head of your editor or separately in a JavaScript file (recommended).

Setup

To begin, instantiate butter and the comm module using their constructors.

var butter = new Butter();

butter.comm();

Then instantiate a CommClient, giving it a name as a string (you won't need this later so it's not that important):

var client = new butter.CommClient( "nameOfClient" );

Your next job is to begin listening for messages from the server. This is done using the listen method.

client.listen( "edittrackevent", function( messageFromServer ) { /* Begin editing the TrackEvent */ });

There are several types of messages to listen for, each serving a specific purpose:

• "edittrackevent" - This message is sent to the editor when a track edit is to begin. It passes an Object containing the track event (trackEvent) and the id's of DOM targets that track events can be targeted to.
• "updatetrackevent" - This message is sent to the editor when a track event that is being edited is updated outside of the editor( i.e. on the timeline ). The track events popcornOptions object is passed as the message data.
• "domtargetsupdated" - This message is sent to the editor when a new DOM target is Added in Butter, so that the editor can update itself accordingly

The only event that has to be implemented is "edittrackevent", the other two are optional and only serve to enhance functionality if the developer desires to implement them.

Editing and Sending Responses

When an editor recieves the "edittrackevent" message, that is its cue to begin the editing process. The callback method should handle the message data and call any methods that are needed to create the UI and begin the editing.

The developed is provided with several events that are listened for by the editor. These provide the necessary functionality that most editors will need. You can send messages to the CommServer using the send method:

client.send( data, "type" );

The types of messages that the Event Editors CommServer is listening for are:

• "okayclicked" - The CommServer will accept an object containing the new popcornOptions object, that should be based on changes the user make using the editor. The server will cut the CommClient off and close the iframe/window that the editor is open in.
• "cancelclicked" - The CommServer will end the CommClients connection and close the iframe/window that the editor is open in. The data parameter can be anything, and will be ignored.
• "applyclicked" = The CommServer will accept an object containing the new popcornOptions object, that should be based on changes the user makes using the editor. The client will not be cut off and editing can resume.
• "deleteclicked" - The CommServer will delete the track event from the butter core. It will close the CommClients connection and close the editor iframe/window.

These send messages can be put anywhere the editor developer desires, allowing for full customization of the editing UI and process.