Most Powerful Open Source ERP

RenderJS API - Quickguide

  • Last Update:2020-06-05
  • Version:001
  • Language:en

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