What is renderJS?

renderJS is a JavaScript library 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

Description

Source

renderJS

The renderJS library

render.js

RSVP

A custom version of RSVP to add cancellation support

RSVP.js

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 attibutes.

Method

Parameters

Returns

Description

rJS(window)

window

GadgetKlass

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

GadgetKlass.ready

callback function with one parameter representing the gadget instance

GadgetKlass (to allow method chaining)

Declares an init function called at the gadget instance creation.

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.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.

gadget.getElement

promise

Returns the DOM element used by the gadget

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

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:

  • Never access the DOM globally. A gadget should not have any knowledge of its current parent gadget
  • Do not use HTML ID attribute, or it will prevent multiple gadget instanciations

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.7.3 which can be downloaded from link below: http://git.erp5.org/gitweb/renderjs.git/blob_plain/HEAD:/dist/renderjs-latest.js?js=1

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://git.erp5.org/repos/renderjs.git

  > npm install

  > grunt server
Submit patches to renderJS forum.

Authors

  • Ivan Tyagov
  • Jean-Paul Smets
  • Sven Franck
  • Romain Courteaud

Copyright and license

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

Add new tab

Tab name: