The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Allegro.cc custom JavaScript

From Allegro Wiki
Jump to: navigation, search

Overview

If you have an account at Allegro.cc, then you can make custom JS changes to it. Just go here:

http://www.allegro.cc/cc/theme-css

With JS you can make all sorts of run-time changes to the page. It's more tricky than changing things visually with CSS. If you want to do anything too advanced, you may want to make your own theme. (Allegro.cc themes)

Some basic help

First off you'll want to install Firebug[1]. Firebug offers many advanced features such as javascript breakpoints and watches, easily change any portion of the page in real time, as well as a slew of highly useful features.

Also useful is Fiddler[2]. Fiddler is a tool that lets you log http sessions and view a huge slew of information on the sessions. It also lets you modify them and resend them. Fiddler is only compatible with Internet Explorer 7.0.

Prototype

Allegro.cc includes the prototype.js library.

registering onload events

Typically you'll want to call some function after the page has loaded. To do so, use Prototype's dom:onload event.

Example

<highlightSyntax language="javascript"> function myfunction() {

 alert("Hi!");

};

document.observe("dom:loaded", myfunction);

document.observe("dom:loaded", function() {

 alert("Another way to say Hi!");

}); </highlightSyntax>

Allegro.cc JS

toolTip

The toolTip class provides tooltips that are displayed as a user hovers over an object. <highlightSyntax language="javascript"> class toolTip {

 const FETCH_RPC=1, FETCH_CALLBACK=2;
 // do not create an instance of toolTip directly
 private toolTip();
 static void init();                   // turns it on
 static void shutdown(bool forever);   // shuts it off or disables it (if forever = true)
 
 // register a tooltip for a node
 static void add(HTMLNode node, function callback, int fetchMode);

} </highlightSyntax>

The only method that needs to be called is toolTip.add(). It does not display a tooltip on demand; it simply registers it. When the user hovers over the node, it will be displayed.

The callback parameter is a function pointer. For user created tooltips, you'll probably always use the fetchMode of toolTip.FETCH_CALLBACK. This means that the function returns the HTML directly.

Example

<highlightSyntax language="javascript"> function callBack(node) {

 return "Hello, " + node.nodeName;

}

toolTip.add(document.body, callBack, toolTip.FETCH_CALLBACK); </highlightSyntax>

User Data

You can store small amounts of arbitrary user data in the Allegro.cc database. This data is private and can only be accessed by the user himself via JavaScript. There are two types of user data:

  • Permanent: available on every page in the userData variable
  • Request: only available when requested via a special RPC call

Limitations & Acceptable Use

Other than a storage limit, there are no restrictions. It's assumed that you will use the system with due diligence.

  • Up to 64K of data can be stored, although it's recommended to use as little as possible.
  • All data should be saved with a namespace specific to your "module" to avoid naming collisions.
  • Using numbered arrays is not recommended and may give random results! If your key is numeric, you must prefix it with a leading 0 if you want it to be remembered. (Use "042", not "42".)
  • Data that will be accessed a lot should be saved as Permanent data to avoid having to make RPC calls.
  • Use short variable names to save space.
  • The space should be used for things that are informative, educational, practical, etc. It's not for silly games or gimmicks.

Storing Data

To store data, use the following procedure: <highlightSyntax language="javascript"> new Ajax.Request("/dhtml/set-user-data.rpc", {

 parameters: {
   permData: {namespace: { key: val }}), // permanent data
   reqData:  {namespace: { key: val }})  // request data
 }

}); </highlightSyntax>

The request must be POSTed to "/dhtml/set-user-data.rpc" with permData and/or reqData. The base type of the data fields must be an associative array. You are encouraged to use your namespace as the base key to avoid naming collisions.

The previous siblings are not overwritten. If foo.bar.apple already exists, setting foo.bar.orange will not erase it. To erase data, you must explicitly set it to null.

Only make a maximum ONE request to store data per page. There's no reason to do it multiple times. Also, refrain from sending an update request when there really is nothing to update.

Examples of Values for permData or reqData

Error: "Pizza". The base is not an associative array.

Bad: {"favoriteFood": "Pizza"}. There's no namespace.

Better: {"mjl": {favoriteFood: "Pizza"} }.

Retrieving Data

Permanent data is always available via the userData object, but of course it's not updated until the next page view.

Request data must be requested via an RPC: <highlightSyntax language="javascript"> new Ajax.Request("/dhtml/get-user-data.rpc", {

 parameters: {reqData: ["namespace.key1", "namespace.key2"]},  // request data
 onSuccess: function(transport)
 {
   alert(transport.responseJSON.namespace.key1);
 }

}); </highlightSyntax>

Warning: Don't accidentally call set-user-data and overwrite something.

The value of reqData when requesting data must be an array of keys. The stored json of {"mjl": {"favoriteFood": "Pizza"} } would be requested like ["mjl.favoriteFood"] or simply ["mjl"]. Only request the minimum amount of information that you need!