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

Allegro.cc custom JavaScript

From Allegro Wiki
Revision as of 19:13, July 31, 2007 by CGamesPlay (talk | contribs) (link update)
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.

Utility Functions

doc.add_onLoad

Registers a function to be called after the HTML is completely loaded. Some browsers will wait until the entire page (images, etc) is loaded before calling these functions.

Example

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

 alert("Hi!");

};

doc.add_onLoad(myfunction);

doc.add_onLoad(function() {

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

}); </highlightSyntax>

Classes

RPC

The RPC class provides a wrapper around XMLHttpRequest (known as AJAX). It can be used to submit GET and POST requests. Due to security limitations, you can only request pages from the allegro.cc domain.

All RPC implementations should be done with care. No script should ever make more calls than what would normally be made without it.

<highlightSyntax language="javascript"> class RPC {

 const HTML=1, JSON=2, XML=3;
 // do not create an instance of RPC directly
 private RPC();
 // use RPC.create() to create an RPC object
 static RPC create();
 // override these event functions to process the request
 event onLoad(mixed response);
 event onError(int errorCode);
 // submit a standard GET request
 void go(string url);
 // submit a POST request with fields
 void addField(string key, mixed val);
 void post(string url, string contentType = "application/x-www-form-urlencoded");
 // change this to RPC.JSON or RPC.XML if the server is not returning HTML
 int responseType = RPC.HTML;

} </highlightSyntax>

Adding Fields

The addField method accepts both objects and literals. If you pass an array or object as the value, it will automatically be JSON encoded. If the value only is a single string or number, it will not be encoded. If you want to JSON encode a simple literal, call JSON.encode().

Example #1: Displaying the source of the main page

<highlightSyntax language="javascript"> var rpc = RPC.create(); rpc.onLoad = function(html) {

 alert(html);

}; rpc.go('/'); // note the relative URL </highlightSyntax>

Example #2: Making a worthless POST

<highlightSyntax language="javascript"> var rpc = RPC.create(); rpc.addField('name', 'John Doe'); rpc.post('/'); </highlightSyntax>

JSON

The JSON class encodes objects and decodes JSON strings. <highlightSyntax language="javascript"> class JSON {

 static mixed decode(string json);
 static string encode(object o);

} </highlightSyntax>

Example #1: Encoding

<highlightSyntax language="javascript"> var data = {foo: bar}; var json = JSON.encode(data); </highlightSyntax>

The variable json now is the string {"foo":"bar"}.

Example #2: Decoding

<highlightSyntax language="javascript"> var json = '{"foo":"bar"}'; var data = JSON.decode(json); </highlightSyntax>

The variable data.foo holds the string "bar".

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();
 // use RPC.create() to create an RPC object
 static RPC create();
 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"> var rpc = RPC.create(); rpc.addField("permData", {namespace: { key: val }}); // permanent data rpc.addField("reqData", {namespace: { key: val }}); // request data rpc.post("/dhtml/set-user-data.rpc"); </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"> var rpc = RPC.create(); rpc.responseType = RPC.JSON; rpc.addField("reqData", ["namespace.key1", "namespace.key2"]); // request data rpc.onLoad = function(json) {

 alert(json.namespace.key1);

}; rpc.post("/dhtml/get-user-data.rpc"); </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!