Railgun Wiki
Register
Advertisement
This page describes one or more aspects related to the development of the Railgun script. Developers may find this content helpful, but it may not be very interesting to the average end-user of the script.
Category: Railgun development Template: {{devnotice}}
General information Installation instructions Configuration options Changelog
Railgun Wiki Installation Configuration Changelog
List of all code pages Create a module tutorial Railgun's API Author of the script
Code Developing a module API User:Mathmagician

Summary[]

All API methods are in the Railgun namespace. For example, Railgun.info()

api()                             // prints an API overview
clear()                           // WARNING! deletes all data in storage
getItem(key)                      // returns a value from storage
info()                            // prints framework, config and storage data
init([anything])                  // initialize Railgun [w/o modules package]
insert(id, content[, header])     // inserts a module into the siderail
register(id, name, init[, destr]) // registers a module with the framework
removeItem(key)                   // deletes a single value from storage
setItem(key, value)               // saves data to storage
swapElements(jQuery, jQuery)      // swaps 2 element's locations in the DOM

Railgun.api()[]

This function can be run from the console to print the above summary of API methods. It has no real functionality otherwise.

// sample usage
Railgun.api();

Railgun.clear()[]

Railgun.clear() is sends a request to the server to delete all content from localStorage, and should generally not be used.

// sample usage
Railgun.clear();

Railgun.getItem()[]

Railgun.getItem(key) takes a single string parameter, a key, and returns the value associated with that key in localStorage.

  1. key -- a key associated with some value in storage
// sample usage
var friends = Railgun.getItem("friends");

Railgun.info()[]

Railgun.info() is similar to Railgun.api() in that it prints helpful information to the console for debugging purposes, but has no actual functionality otherwise.

// sample usage
Railgun.info();

Railgun.init()[]

Railgun.init([anything]) fires Railgun's main initialization sequence. It can safely be called again manually from the console while developing a module. If a parameter is specified, then the modules package will not be loaded.

// Using Railgun with Railgun.Config.isDelay = true

// copy paste module code into the console

// sample usage
Railgun.init(1); // initialize manually after defining a module for testing

Railgun.insert()[]

Railgun.insert(id, content[, header]) is an essential method that every module must use to physically insert itself into the siderail. This method takes some HTML content, wraps it in a section with an optional h1 header, and then inserts it into the siderail.

  1. id -- the id attribute of the <section> tag to be generated
  2. content -- the HTML content to be wrapped
  3. header -- (optional) some text to be wrapped in an <h1></h1> header
var content = '<a href="http://www.google.com">Google</a>';

// sample usage
Railgun.insert('railgun-google-module', content, 'Google');

Railgun.register()[]

Railgun.register(id, name, init[, destr]) is another method that every module is required to use. This method registers the module's initialization method with the Railgun framework, which will then call the method when the framework is initialized (after all other modules have been defined).

  1. id -- the id attribute of the module's <section> tag
  2. name -- a human-readable display name of the module
  3. init -- an initialization method that constructs the module
  4. destr -- (optional) a destroyer method which will be called when the module is uninstalled, if this is not provided then a default destroyer will be used.
// scope -- don't add stuff into the global namespace
(function () {
    // define the module...

    var friends = 0;

    function increment () {
        friends++;
        $('#friends-counter').html(friends);
    }

    function init () {
        var content = '<div id="friends-counter" style="width: 100%;'
            + ' font-size: 3em;">0</div>';

        // insert module into the siderail
        Railgun.insert('id-example', content, 'Example Module');

        // update friend counter every second
        setInterval(increment, 1000);
    }

    // sample usage -- register the module
    Railgun.register('id-example','Example Module', init);
}());


// after registering the module, you can test it from the console:
Railgun.init(1);

Railgun.removeItem()[]

Railgun.removeItem(key) takes a string key as parameter and sends a command to the server to delete that item from localStorage.

  1. key -- a key associated with some value in storage
// sample usage
Railgun.removeItem("friends");

Railgun.setItem()[]

Railgun.setItem(key, value) takes a string key and some value, and then saves the value to local storage under the name specified by the key. This is the main method for saving data between page loads.

  1. key -- a key to be associated with a value
  2. value -- a value to be saved to localStorage
// sample usage
var object = { data: 1 };
Railgun.removeItem("object" , object);

Railgun.swapElements()[]

Railgun.swapElements(jQuery, jQuery) swaps the locations of two elements in the DOM.

var firstInToolbar = $('.toolbar .tools > *').first();

var lastInToolbar = $('.toolbar .tools > *').last();

// sample usage
Railgun.swapElements(firstInToolbar, lastInToolbar);

Documentation[]

The documentation for this project is also available for download on the Code page. In the next tutorial page, there's a sample module demonstrating how to leverage the API to accomplish certain key tasks when it comes to writing a module.

<< Previous Current page Next >>
Developing a module API Module layout
Category:Tutorial Home: Developing a module Template: {{devtutorial}}
Advertisement