Generally:

YourClassName.yourMethodName(args...).operation(args);

CoolApi.getABox("red").useToReplace(document.getElementById("playground"));

for example.

When you call a method, it doesn't make the server request. Instead, it returns an object describing the call. This means you can manipulate it (such as requesting a custom format), pass it as an argument to other functions (thus saving http requests) and finally call it at the end.

The operations are: get(callback, args to callback...);

See below.

useToReplace(element) // pass an element reference. Example: useToReplace(document.querySelector(".name")); useToReplace(element ID : string) // you pass a string, it calls document.getElementById for you

useToReplace sets the given element's innerHTML to the return value. The return value is automatically requested to be formatted as HTML.

appendTo(element) appendTo(element ID : String)

Adds the return value, as HTML, to the given element's inner html.

useToReplaceElement(element)

Replaces the given element entirely with the return value. (basically element.outerHTML = returnValue;)

useToFillForm(form)

Takes an object. Loop through the members, setting the form.elementskey.value = value.

Does not work if the return value is not a javascript object (so use it if your function returns a struct or stringstring)

getSync()

Does a synchronous get and returns the server response. Not recommended.

get() :

The generic get() function is the most generic operation to get a response. It's arguments implement partial application for you, so you can pass just about any callback to it.

Despite the name, the underlying operation may be HTTP GET or HTTP POST. This is determined from the function's server side attributes. (FIXME: implement smarter thing. Currently it actually does it by name - if the function name starts with get, do get. Else, do POST.)

Usage:

CoolApi.getABox('red').get(alert); // calls alert(returnedValue); so pops up the returned value

CoolApi.getABox('red').get(fadeOut, this); // calls fadeOut(this, returnedValue);

Since JS functions generally ignore extra params, this lets you call just about anything:

CoolApi.getABox('red').get(alert, "Success"); // pops a box saying "Success", ignoring the actual return value

Passing arguments to the functions let you reuse a lot of things that might not have been designed with this in mind. If you use arsd.js, there's other little functions that let you turn properties into callbacks too.

Passing "this" to a callback via get is useful too since inside the callback, this probably won't refer to what you wanted. As an argument though, it all remains sane.

Error Handling:

D exceptions are translated into Javascript exceptions by the serverCall function. They are thrown, but since it's async, catching them is painful.

It will probably show up in your browser's error console, or you can set the returned object's onerror function to something to handle it callback style. FIXME: not sure if this actually works right!