sdesai/gist:1386836

## gistfile1.md

      
    Raw
  

              gistfile1.md
            
          
    USE CASES


Render widgets on NodeJS, where DOM is absent.
Optimize rendering of Widgets at scale (1000s of TreeViewNodes).

GOAL


Avoid all Node references from Widget through the end of renderUI().
bindUI()/syncUI() will still have Node references (to bind events and incrementally update DOM).

DESIGN

Opt-in Widget Extension, to maintain backwards compatibility.

A boundingBox/contentBox Node instance won't be present for initializer/attr setters/attr getters/HTML_PARSER,
so needs to be opt-in.


Component Developer can opt-in, if they have a 100% string rendered component (e.g. TreeViewNode)
In this case, get("boundingBox") etc. needs to be documented accordingly for the end user.


Environment can opt-in (e.g. NodeJS - conditional loading)


Example:
Y.WidgetStringRenderer = function() {...};

Y.WidgetStringRenderer.prototype = {
   // override what needs to be overridden in Y.Widget to support string template based rendering.
}

Y.Foo = Y.Base.create("foo", Y.Widget, [Y.WidgetStringRenderer]);

Handlebars Default

It'll use Handlebar style templates as opposed to substitute, for forward compatibility.
However we should maybe look into a "handlebars-core" to satisfy the kweight nitpickers. We've been asked to break out less than 3KB chunks before which is where handlebars-base-min.js currently is.
"handlebars-core" could provide basic {{ }} and {{{ }}} support, and also maybe provide substitute compatibility (how to identify single { tokens, from content in a handlebars template?).
Two Phase Render

We'll need to break up the render() phase, into the renderUI() portion and the bind/syncUI() portion
render()
    renderUI() : No Node references
    bindUI()   : Node references
    syncUI()   : Node references

Not sure what the method split should be yet. Options are below, first one is my leading candidate
Options

TreeView use case:
// While iterating 1000s treeview nodes ...
treeviewNode.renderHTML(buffer);     // only renderUI() - is it OK that render event is not fired? 
                                     //                   I think so. Nothing is in the DOM yet.

// Once injected into the DOM ...
treeviewNode.render();         // renderUI() [if not invoked before], bindUI(), syncUI()

NodeJS use case:
// On Server
calendar.renderHTML();

// On Client
calendar.render();

Or,
treeviewNode.render();
treeviewNode.bind();        // How about if they want to do it all at once in render(); bind() and Y.bind() confusion

Or,
treeviewNode.renderHTML();
treeviewNode.bind();

Or,
treeviewNode.renderUI() // When do we fire/set render state?
treeviewNode.bindUI()
treeviewNode.syncUI()

Will require re-establishing boundingBox/contentBox Node references, post-renderUI().

Widget will generate node instance from rendered template content for boundingBox, contentBox
Usage

TreeViewNode - Always 100% String rendered

Y.TreeViewNode = Y.Base.create("treeViewNode", Y.Widget, [Y.Parent, Y.Child, Y.WidgetStringRenderer]);

// In Parent.render() ...
var buffer = [];
for (i = 0; i < children.length; i++) {
    child.renderHTML(buffer);   
}

var allChildrenHTML = buffer.join("");

Only on NodeJS (conditionally loaded extension mix)

// calendar-nodejs, or maybe just widget-base-nodejs
Y.Calendar = Y.Base.create("calendar", Y.Widget, [Y.WidgetStringRenderer]);

var buffer = []
calendar.renderHTML(buffer);

var calendarHTML = buffer.join("");

We can add sugar in the future (render straight into a template for example). Not enough time for Sprint 1.
calendar.renderHTML(template, token);