Below is a list of all methods provided by RenderJS, followed by a more detailed explanation in later sections.
Gadget's definition API
All methods return the gadget definition. And so, they are chainable.
Callback this context is the gadget instance
| Do what? |
Do this! |
Explanation |
| Ready Handler |
rJS(window).ready(callback)
|
The ready callback is triggered automatically when all gadget dependencies have loaded.
Callback this context is the gadget instance
|
| Declare Method for parent gadget |
rJS(window).declareMethod("methodName", callback, options)
|
Declaring methods is the most common way of adding functionality to a gadget.
Only declare methods which require the this context or which should be accessible by other gadgets.
Callback this context is the gadget instance
options can be used to setup a mutex on the callback to prevent concurrent execution: {mutex: "bar" / "changeState"}
|
| Declare Service |
rJS(window).declareService(callback)
|
Callback automatically trigger as soon as the gadget is loaded into the DOM.
Callback is cancelled as soon as the gadget is removed from the DOM.
Callback this context is the gadget instance
There can be multiple declareService handlers, which all trigger concurrently.
|
| Loop |
rJS(window).onLoop(callback, delay)
|
.onLoop callback has the same behaviour than a service, but browser tab must also be visible to trigger it.
When the callback is over, it is executed again after the delay is over.
|
| Declare Job |
rJS(window).declareJob("methodName", callback)
|
When the methodName is called on a gadget, it spawns a service executing the callback.
Like a service, its execution starts when the gadget is in the DOM.
Callback this context is the gadget instance
However, calling a job cancels the previous call of the job if it hasn't finished.
|
| Bind Event |
rJS(window).onEvent(type, callback, use_capture, prevent_default)
|
Create an event listener for the given event on the gadget .element
Callback this context is the gadget instance
Callback take the DOM event as first argument
|
| Set Initial State |
rJS(window).setState(options)
|
The gadget's state should be set once when initialising the gadget.
The state should contain key/value pairs, but the state is just an ordinary JavaScript object with no hard restrictions.
|
| Change State Callback |
rJS(window).onStateChange(callback)
|
callback is executed after changeState call on a gadget, whenever the gadget state changes.
Comparison of gadget state is done with json.stringify
Callback this context is the gadget instance
Callback take a modification_dict as first argument, which contains all the modified state parameters
Callback is protected by the changestate mutex
|
| Publish Method form child gadget |
rJS(window).allowPublicAcquisition("acquisition_name", callback)
|
Publish a method to allow children to acquire it.
Callback this context is the gadget instance
Callback take the acquired method argument_list as first argument
Callback take the child gadget scope as second argument
|
| Acquire Method |
rJS(window).declareAcquiredMethod("methodName", "acquisition_name")
|
Acquire a method from a parent gadget
|
By default, there are 2 acquired methods which can be automatically called by renderJS internally:
- reportServiceError: used to catch child gadget error in their services
- reportGadgetDeclarationError: used to catch gadget loading error when declared in the DOM
Gadget API
| Do what? |
Do this! |
Explanation |
| Declare Gadget (HTML) |
<div data-gadget-url="gadget_example.html"
data-gadget-scope="example"
data-gadget-sandbox="public">
</div>
|
Only data-gadget-url is required. Set data-gadget-scope to access the gadget by that scope name in JavaScript.
Set data-gadget-sandbox to be public, to wrap the gadget in a <div> directly in the DOM, or iframe, to wrap the gadget in an <iframe>.
|
| Declare Gadget (JS) |
gadget.declareGadget(gadget_url, options);
|
return an RSVP.Queue resolved with the child gadget reference.
The options exactly correspond to those when declaring the gadget in HTML, with the addition of element, to specify an element to wrap the gadget in, rather than the default auto-generated <div>.
|
| Get an existing gadget |
gadget.getDeclaredGadget(scope);
|
return an RSVP.Queue resolved with the child gadget reference.
throw a ScopeError if the scope is unknown
|
| Drop an existing gadget |
gadget.dropGadget(scope);
|
return an RSVP.Queue resolved with undefined.
throw a ScopeError if the scope is unknown
|
| Change State |
gadget.changeState(state);
|
return an RSVP.Queue resolved with undefined, when the onStateChange callback is resolved
Change the state by passing in a new key-value pair, which only overwrites the keys provided in the changeState call, and only if the current and new values are different. All other keys remain unchanged.
|
| Declared Method call |
gadget.declaredMethodName(arguments)
|
return an RSVP.Queue resolved with the result of the .declareMethod callback
|
| Declared Job call |
gadget.declaredJobName(arguments)
|
return undefined
|
| Acquired Method call |
gadget.acquiredMethodName(arguments)
|
return an RSVP.Queue resolved with the result of the ancestor .allowPublicAcquisition callback
Recursively go up in the parent tree until one "ancestor" allowPublicAcquisition the "parentPublicAcquisition"
If no ancestor handle it, throw AcquisitionError
|