Javascript API

From KickApps Documentation

This page documents the JavaScript API hooks and events that are available in KickApps 4.0+ and how to use them. This article is specifically about the supported event methods and how to put them to use in your own application so that you may further customize how your KickApps community looks and feels.

To see a live example of this event API in action, please refer to our Facebook Connect plugin.

Previously, developers often would overwrite our functions with their own, allowing them to control the flow and behavior of the application. This meant that any time we updated our code, these communities would not be using the updated functions.

To address this issue, we have strategically added events throughout the KickApps platform that you may listen for. These events act as hooks that allow your JavaScript to plugin to our own code at specific times, temporarily passing execution to your code. You may use this API to prevent our default actions from occurring while providing your own logic and behavior.

Note: Our event system is an instance of our ObserverClass and is located in the Ka.events namespace.

Please refer to the list of events currently supported for further information about them, and specific usage for each.

Ka.events methods

The following describes the public methods of the ObserverClass. Examples are provided for each method on a separate page.

Ka.events.listen()

Summary

Listens for the specified event and fires the specified callback upon dispatch of the event.

Syntax

<int> Ka.events.listen(<string> eventName, <function> callback, [object] options)

Parameters

eventName

Event to listen for

callback

Callback to fire upon dispatch of specified event

Additional Options

(Optional) You may optionally provide additional options for more precise control over your event handler. The following options are supported, but not required.

Additional Options

scope

Provides the option of setting the scope of the '''this''' keyword in your event handler.

browser

Allows you to specify which browser this event handler will run on. You may specify "MSIE", "Safari", "Mozilla" or "Opera".

version

In conjunction with browser, this allows you to target a specific version of a specific browser.

Examples

View example code

Ka.events.remove()

Summary

Removes an event from the event queue. You can remove an event by ID, by event name, or by passing the callback function of the event you want to remove. Removing by ID removes only the event handler that matches that ID. Removing by event name or callback removes all events handlers that match that event name or callback.

Syntax

<void> Ka.events.remove(<string> eventName)

<void> Ka.events.remove(<function> callback)

<void> Ka.events.remove(<int> eventId)

Parameters

eventName

Name of the event handler to be removed

callback

Callback function of the event handler to be removed

eventId

ID of the event handler to be removed

Examples

View example code

Ka.events.dispatchEvent()

Summary

Dispatches an event by name, passing optional additional arguments if neccessary.

Syntax

<bool> Ka.events.dispatchEvent(<string> eventName, [object] additionalArguments)

Parameters

eventName

Event to be dispatched

additionalArguments

(Optional) JavaScript Object containing any relevant properties to be passed to the event handler

Examples

View example code

Debugging

To enable debugging of the event system, all you must do is put the following code in your JavaScript:

   Ka.Settings.enableLogging = true;

Note:

• Debugging the KickApps event system requires the Mozilla Firefox browser and the Firebug plugin.
• Enabling logging will enable logging across the platform, not just for the event system so you may notice a number of logged events

Template:Categorize as Javascript APIs