Home

Butter API (v0.1)

Core Module

Butter

trigger( name, options )

Triggers an event with type name. The event will be sent to each listener waiting for events of type name, with options as the only parameter.

listen( name, handler )

Listen for an event with type name. When an event occurs with type name, handler will be called. To receive data from the event, handler should take one parameter in its signature.

unlisten( name, handler )

Stop listening for events with type name. If handler is specified, all listeners for type name will be forgotten. Otherwise, only the listener matching handler will be effected.

addTrackEvent( track, trackEvent )

Add trackEvent to track. track may be a Track object (see below), or a string, representing the name of a stored Track. trackEvent may be a TrackEvent or an object representing the parameters to create a TrackEvent (object parameters are passed directly to the TrackEvent constructor). Returns a TrackEvent if successful, and dispatches a "trackeventadded" event. Throws an error if track is invalid, or no Media is defined.

getTrackEvents()

Returns an object whose properties are the names of stored Tracks. Each property references an array of TrackEvents belonging to the corresponding Track.

getTrackEvent( track, name )

Searches through track for a TrackEvent named name, and returns it if successful. track may be a Track or a string representing the name of one.

removeTrackEvent( track, trackEvent )

Searches through track for a TrackEvent equivalent to or named by trackEvent, and forgets it if successful. Upon removal, the corresponding TrackEvent is returned, and a "trackeventremoved" event is dispatched.

addTrack( track )

Stores track in the current Media. If track is and object with properties to create a Track, it will be passed directly to the Track constructor first, and the consequent Track will be stored. Otherwise track is assumed to be a valid Track. The Track object will be returned, and a "trackadded" event will be dispatched. Throws an error if no Media is defined.

getTracks()

Returns an array of Tracks from the current Media. Throws an error if no Media is defined.

getTrack( name )

Searches for a Track named name and returns it if successful. Throws an error if no Media is defined.

removeTrack( track )

Searches for track and removes it if successful. track may be a string representing a named Track, or the Track object to be removed itself. Upon removal, the corresponding Track is returned, and a "trackremoved" event is dispatched. Throws an error if no Media is defined.

addTarget( target )

Stores target. target may be a Target or an object with properties to create a Target, in which case the object will be passed directly to the Target constructor to create a Target object to be stored instead. The Target object is returned, and a "targetadded" event is dispatched.

removeTarget( target )

Searches for target, and removes it if successful. target may be a Target object, or a string representing the name of one. Upon removal, the corresponding Target object is returned, and a "targetremoved" event is dispatched.

getTargets()

Returns an array of the currently stored Target objects.

getTarget( name )

Searches for a Target named name and returns it if successful.

importProject( projectData )

exportProject()

setProjectDetails()

getProjectDetails()

play()

Plays the current Media object.

pause()

Pauses the current Media object.

currentTime()

Gets the current time of the current Media object.

getAllMedia()

Returns an array containing all stored Media objects.

getCurrentMedia()

Returns the currently selected Media object.

getMedia( name )

Searches for a stored Media object named name, and returns it if successful.

setMedia( media )

Sets the current Media to media, which may be a Media object, or a string representing the name of one. The referenced Media object must be added first (see addMedia below). Dispatches a "mediachanged" event if successful.

addMedia( media )

Stores media, returns it, and dispatches a "mediaadded" event. media is assumed to be a Media object, or an object representing the properties to create one.

removeMedia( media )

Searches for media, and removes it if successful. media may be a Media object, or a string representing the name of one. Upon removal, the Media object is returned, and a "mediaremoved" event is dispatched.

getScriptLocation() [Class Method]

Attempts to return the location of the current butter.js script.

registerModule( name, module ) [Class/Instance Method]

Registers a Butter module, and extends the API to include methods from the module.

extendAPI( properties ) [Class Method]

Extends the API. The Butter class and new instances of Butter objects will receive API additions.

Track

getName()

Returns the name of the Track.

getId()

Returns the internally-generated id of the Track.

getTrackEvent( name )

Searches for TrackEvent named name and returns it if successful.

getTrackEvents()

Returns an array containing all TrackEvents stored in this Track.

removeTrackEvent( trackEvent )

Searches for trackEvent and removes it if successful. trackEvent may be a TrackEvent object, or a string representing the name of one.

addTrackEvent( trackEvent )

Stores trackEvent. trackEvent may be a TrackEvent object, or an object with properties for generating a TrackEvent object, in which case the object will be sent directly to the TrackEvent constructor.

TrackEvent

start

Start time of the TrackEvent.

end

End time of the TrackEvent.

type

Type of the TrackEvent

popcornOptions

Popcorn-specific options associated with the TrackEvent.

popcornEvent

The Popcorn track-event object associated with the TrackEvent.

track

The Track object to which the TrackEvent is currently attached.

getName()

Returns the name of the TrackEvent.

getId()

Returns the internally-generated id of the TrackEvent.

Target

object

The object the Target represents. Most likely a DOM object.

getName()

Returns the name of the Target object.

getId()

Returns the internally-generated id of the Target object.

Media

setMedia( mediaElement )

Stores mediaElement to be represented by the Media object.

getMedia()

Returns the media represented by the Media object.

getName()

Returns the name of the Media object.

getTracks()

Returns an array of Tracks stored in the Media object.

addTrack( track )

Stores track. If track is and object with properties to create a Track, it will be passed directly to the Track constructor first, and the consequent Track will be stored. Otherwise, track is assumed to be a Track object. The Track object will be returned and a "trackadded" event will be dispatched.

getTrack( name )

Searches for a Track named name and returns it if successful.

removeTrack( track )

Searches for track and removes it if successful. track may be a string representing a named Track, or the Track object to be removed itself. Upon removal, the corresponding Track is returned, and a "trackremoved" event is dispatched.

Comm Module

CommClient

listen( type, callback )

Listen for an message with type type. When a corresponding message is sent, callback will be called. To receive data from the event, callback should take one parameter in its signature.

forget( type, callback )

Stop listening for events with type type. If callback is specified, all listeners for type type will be forgotten. Otherwise, only the listener matching callback will be effected.

send( message, type )

Send an event with type type. The message will be sent to each listener waiting for message of type type. If type is not specified, an attempt to use the general callback will occur.

CommServer

bindFrame( name, frame, readyCallback, messageCallback )

Binds a Frame (likely an IFRAME), to channel name. When the Frame has loaded, readyCallback is called. When any message is received on this channel, messageCallback is called.

bindClientWindow( name, client, callback )

Binds a Window to channel name. When any message is received on this channel, callback is called.

listen( name, type, callback )

Listen for an message with type type on channel name. When a corresponding message is sent, callback will be called. To receive data from the event, callback should take one parameter in its signature.

forget( name, type, callback )

Stop listening for events with type type on channel name. If callback is specified, all listeners for type type will be forgotten. Otherwise, only the listener matching callback will be effected.

send( name, message, type )

Send an event with type type to channel name. The message will be sent to each listener waiting for message of type type. If type is not specified, an attempt to use the general callback will occur.

Previewer Module

Previewer

previewer( { layout:, target:, media:, callback: } )

Setup for the previewer module, passing in an options object containing mandatory parameters. Layout is a string pointing to the location of the layout that will be used within the previewer. Target specifies the DOM element in which the previewer should inhabit. Media is a string pointing to the location of the media object that will be used in Butter. Callback is a user specified function that will be executed after DOM scraping has completed.

getPopcorn( )

returns a string that contains the popcorn code that has been created so far. The returned string has some styling applied to it.

buildPopcorn( videoTarget )

Builds the version of popcorn that will be used within the previewer. VideoTarget is the id of the DOM element in which the video will be built. Popcorn is then built and ready to be populated with data. The previewer MUST be ready in order to build popcorn, so it is recommended that this be called in the callback of the previewer constructor/setup.