RenderJS Home RenderJS

    renderJS is a javascript library used to create reusable HTML5 components (called gadgets) for single-page web applications.
    It is also used to quickly integrate existing 3rd party libraries into existing applications. 

    It is developed and maintained by Nexedi to reduce the code duplication between the ERP5 interface and as a basis for applications in app stores such as OfficeJS.

    Concepts

    Gadget definition

    The definition of a renderJS gadget consists of a single HTML file and its JS/CSS dependencies defined in the DOM header.

    This definition is referenced by the URL of the HTML document.

    HTML can also contain a link to the gadget interface URL, which acts a documentation.

    Minimal example:

    <html>
      <head>
        <script src="rsvp.js"></script>
        <script src="renderjs.js"></script>
      </head>
      <body>
    A minimal renderJS gadget
      </body>
    </html>

    Gadget definition loading

    When renderJS loads a new definition URL, it:

    1. fetches the HTML and parse it
    2. keep a copy of the BODY, to clone it on every instance
    3. loads all JS, CSS defined in the HEAD
    4. generates the "class" methods defined by .declareMethod and .declareJob

    Click here to see more

    Installing

    RenderJS is easy to set up and get working.

    Download the files directly:

    Getting started

    The first thing is to understand the asynchronous event handling in Javascript.

    As writing code with callbacks everywhere often leads to difficult maintainance, it has been decided to only rely on the promises/A+design pattern to write javascript code in Nexedi.

    The goal of promise is only to make the code readable and maintainable.

    If you read the promises/A+ specifications for the first time, probably you're missing the point of promises, so, read again.

    We started to use RSVP as cross browsers compatible promise's implementation.
    We patched it to implement a cancel method on the promise object, which allows to manually interrupt a promise execution. This cancel method is not part of the promises/A+ specifications, and so, will not be integrated into RSVP.

    Such method is from time to time under discussion on the promises/A+ repo on other promise implementations or even internally for Chrome native promise. Nobody gives it the same semantics/specifications for now.

    Our implementation is simple and easy to understand.

    Code based on renderJS should be promise based:

    We added a new kind of promise in RSVP.Queue to allow cancelling a list of promise chains. You should only use Queue, and never use the .then method but the .push method instead.

    Writing a WebApp is not only understanding renderJS. It's also handling URL navigation, having reusable gadgets between project, providing feedback in the UI, handling errors, writing tests, etc...
    To achieve this, follow the OfficeJS learning track.

    API - Quickguide

    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

    Click here to see more

    Contributing

    The RenderJS source code is available on GitLab, with a mirror on GitHub.

    HowTo

    Guideline

    FAQ

    License

    RenderJS is Free Software, licensed under the terms of the GNU GPL v3 (or later). For rationale, please see Nexedi licensing.

    Examples

    Most of the front end solutions created by Nexedi are based on RenderJS and jIO. For ideas and inspiration check out the following examples:

    • OfficeJS - Office Productivity App Store (Chat client, task managers, various editors).