RenderJS Home RenderJS

    RenderJs - Web Gadgets in Pure HTML5

    • Last Update:2016-11-30
    • Version:006
    • Language:en
    RenderJS

    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:

    • Never access the DOM globally. A gadget should not have any knowledge of its current parent gadget. Instead, only on local DOM element (gadget.getElement())
    • Do not use HTML ID attribute, or it will prevent multiple gadget instanciations. Instead, use class attribute.
    • Do not access page URL. Instead, uses parameters provided to method call (like render)
    • A gadget can only call methods of its direct children. A child can not call a method of its parent. Instead, it should acquire a method.
    • Do not break the promise chain. If the RSVP.Queue's "push" method is used instead of the "then" method, your application will have an automatic code cancellation for free (on page change for example).
    • Do not catch all errors. Propagate not handled errors instead, so that application errors could be reported to the user/developper.

    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