RenderJS

What is RenderJS?

RenderJS is a JavaScript library developed by Nexedi which helps modularizing your HTML5 code and your JavaScript applications. It uses the HTML5 standard as an easy way to specify self-contained components which consist of HTML5 code, CSS code and Javascript code. It helps reusing components in different applications just as easily as linking an HTML5 page to another. It also helps combining multiple reusable component within the same single page application.

The main focus of renderJS is graphic user interface (GUI) components such as editors, viewers, fields or widgets. renderJS can also be used to define reusable components with no GUI such as translators or format converters.

A Simple Example

Let us suppose we want to add a text editor to an HTML5 page, here is how we proceed:

<!DOCTYPE html>
<html>
  <head>
    <title>Simple example</title>
    <script src="RSVP.js"></script>
    <script src="render.js"></script>
  </head>
  <body>
    <p>Text editor displays below:</p>
    <div data-gadget-url="http://www.renderjs.org/editor/rtl/index.html"></div>
  </body>
</html>

renderJS takes care of managing all dependencies and rendering.

Getting started

This walkthrough is designed to get you started using a basic renderJS instance.

Download renderJS library, renderJS core as well as the dependencies required to start using core components.

Script / PermaLink

Description

render.js

The renderJS library

RSVP.js

A extended version of RSVP to add cancellation and Queue support

Add the renderJS script to your HTML head:

   <script src="RSVP.js"></script>
   <script src="render.js"></script>

renderJS fundamentals

renderJS can be used either by adding HTML5 tags to your page or by invoking Javascript methods.

The renderJS script provides HTML5 attributes which can be added to any HTML5 page.

Method

Sample Call

Description

data-gadget-url

<div data-gadget-url="hello-world.html"></div>

Embeds the HTML5 code of a gadget in a page, loads CSS and Javascript depencies.

data-gadget-scope

<div data-gadget-url="hello-layout.html" data-gadget-scope="hello"></div>

Associates a gadget to a namespace which can later be used to retrieve a gadget programmatically

data-gadget-sandbox

<div data-gadget-url="hello-layout.html" data-gadget-sandbox="iframe"></div>

Defines the sandboxing type of a gadget (iframe, public, etc.).

The renderJS Javascript API replicates and extends HTML5 attributes.

Method

Parameters

Returns

Description

rJS(window)

window

GadgetKlass

Get the currently loading gadget class (based on the HTML URL).

GadgetKlass.ready

callback function

GadgetKlass (to allow method chaining)

Declares an init function called at the gadget instance creation.

GadgetKlass.setState

json object

GadgetKlass (to allow method chaining)

Declares the default gadget state.

GadgetKlass.declareMethod

  • method name
  • method callback

GadgetKlass (to allow method chaining)

Declares a public asynchronous method of a gadget.

GadgetKlass.declareService

service callback

GadgetKlass (to allow method chaining)

Declares an asynchronous callback executed when a gadget is included into the DOM.

GadgetKlass.onEvent

  • event type
  • callback
  • use_capture
  • prevent_default

GadgetKlass (to allow method chaining)

Declares an DOM event listener as a service on the gadget element. The callback is called each time the event is triggered.

GadgetKlass.declareJob

  • method name
  • callback

GadgetKlass (to allow method chaining)

Declares a public asynchronous method of a gadget. The callback is executed as a service, and the method does not return the result of the callback.

GadgetKlass.allowPublicAcquiredMethod

  • acquisition name
  • acquisition callback

GadgetKlass (to allow method chaining)

Declares an asynchronous acquisition callback.

GadgetKlass.declareAcquiredMethod

  • method name
  • acquisition name

GadgetKlass (to allow method chaining)

Declares an asynchronous method to acquire method from parent.

GadgetKlass.onStateChange

    callback (with a modification_dict as parameter)

GadgetKlass (to allow method chaining)

Declares a callback executed when the gadget state is modified by the changeState method

gadget.changeState

    json object

promise

Modify the gadget state keys defined in the json object. Trigger the onStateChange callback if the new values are different.

gadget.declareGadget

  • gadget url
  • gadget options

promise

Returns a newly created subgadget

gadget.getDeclaredGadget

gadget scope

promise

Returns a previously created subgadget

gadget.dropGadget

gadget scope

promise

Drop a reference to a previously created subgadget

A gadget also has some internal properties:

Property name

Description

element

The DOM element used by the gadget.

state

JSON object.

Design of the renderJS application

A full renderJS application is a composition of multiple gadgets rendered in the same page. More than this, a gadget URL can be rendered simultaneously inside the page.

In order to achieve a working state, the gadget code should strictly follow some rules:

renderJS inter gadget communication is always asynchronous. Promise pattern is used to simplify the code and error handling. Take a coffee, and read the specifications.

Step by step tutorials

Follow this tutorial.

Supported browsers

RenderJs work in any standards compliant browser. It has been successfully tested with Firefox and Chrome. Current considered "stable" version is 0.12.1 which can be downloaded from link below: renderjs.js

A list of all version is available in renderJS repository: https://lab.nexedi.com/nexedi/renderjs

Applications using RenderJs

RenderJs has been successfully used for by ERP5, OfficeJs and SANEF.

Articles

RESILIENCE W3C Lightning Talk or download as PDF.

Contribute

> git clone https://lab.nexedi.com/nexedi/renderjs.git
> npm install
> grunt server

Submit merge Request to gitlab or github.

Question ?

RenderJS is still under heavy development and some information may not be found here. Fill free to ask your question regarding renderJS on OfficeJS Forum

Copyright and license

renderJS is an open-source library and is licensed under the LGPL license. More information on LGPL can be found here