immutable-app-component

Immutable App Component integrates with the
Immutable App ecosystem to
provide a framework for defining dynamic UI components.

Immutable App Commponent is an Immutable App module that provides the client
side runtime for components and the endpoints that clients use to communicate
with the server.

ImmutableCoreComponent
is used to instantiate component classes and provides much of the functionality
that Immutable App Component exposes.

Why use Immutable App Component

Given that there are already several large and actively developed UI frameworks
out there why use Immutable App Component?

What sets Immutable App Component apart is that it is specifically not meant
for Single Page Apps (SPAs) and specifically is designed to support
dynamic components that integrate into a traditional server rendered HTTP
application.

Server rendered pages load and render faster, have greater compatibility, work
with SEO out of the box, are less prone to error and degrade more gracefully
when errors do occur.

Immutable App Component is ideal for applications that need some dynamic
content but do not need a full SPA.

Immutable App Component uses
Handlebars templates and
plain JavaScript so the learning curve is shallow and you do not need to set
up any additional tooling to get started.

Component architecture overview

At its simplest a component contains a server side method that instantiates
some data and renders it with a template.

The initial page render includes the fully rendered component as well as
javascript that registers the component with a client side component service.

The compiled version of the component template is sent to the client so that
if the data changes the client can re-render the component.

On the server side components are exposed via an endpoint that allows the
client to refresh the component data. Components can be declared with a
periodic refresh interval so that they are automatically refreshed.

Components can be bound to input elements and data will be updated by new
input. Data can also be set manually via a set method. Data set on the client
will then be sent to the server component set method if supported.

The client side component service checks components on an interval and if the
component needs to be refreshed a request will be made to the server to check
if the data has changed. If the data has changed the template will be
re-rendered.

Components can also include javascript that executes on the client to integrate
the component lifecycle with other javascript on the page.

Component directory structure

my-app
|
+-- app
|
+-- app.js
|
+-- components
| |
| +-- my-component
| | |
| | +-- helpers
| | | |
| | | +-- foo.js
| | |
| | +-- partials
| | | |
| | | +-- foo.hbs
| | |
| | +-- my-component.css
| | +-- my-component.hbs
| | +-- my-component.client.js
| | +-- my-component.script.js
| | +-- my-component.server.js

By default each component is stored in a separate folder in the components
directory at the root of the Immutable App directory where other default
directories like app, assets, helpers and partials are stored.

Components do not share templates, partials or helpers with the main app.

In this example the my-component.server.js file contains the server side
component definition which must be a plain object that can be passed to
new ImmutableCoreComponent.

my-component.client.js contains the client side component definition which
must be a plain object that can be passed to new ImmutableAppComponent
in the client browser.

my-component.script.js contains raw javascript that will be executed after
the ImmutableAppComponent is instantiated in the browser. This script will
be wrapped inside an anonymous function, run in strict mode and have the
component available in scope as component.

my-component.hbs is the component template. This template will be use to
render the component on the server. It will also be compiled and delivered to
the client so that the component can be re-rendered by the client.

my-component.css is an optional stylesheet file that will be delivered to
the client.

helpers may contain one or more helpers. helpers can be defined either as
an object with names pointing to functions or by exporting a function, in
which case the name of the file will be used for the name of the helper.

partials may contain one or more partials. The name of the file will be used
as the name of the partial.

Like models,
controllers
and templates in Immutable App, components defined in separate modules can be
extended and overriden by other modules required later in your app.

Creating a new component

// my-component.server.js

module.exports = {
new: function (args) {

}
}

Using a component in your app

// controller

function getPage (args) {
var myComponent = await this.component.myComponent.new({ ... })

return {
components: {myComponent: myComponent}
}
}

// template

<...>{{components.myComponent}}

In controller methods components can be accessed via this.component. The
new method creates a new instance of the component. The data returned by
the new method is used to render the template.

The component object has a toString method that renders the template so the
component object can be placed in a template as a simple variable.

ImmutableAppComponent

Every component that is rendered on the server instantiates a new instance of
that component on the client. All components are registered with the global
ImmutableAppComponent instance which manages the components on the page
and coordinates all communications with the server.

Every component is given a unique id which will be the component name in param
case for the first instance of the component (my-component) and with a count
appended if there are additional instances (my-component-1, my-component-2).

$3

var myComponent = ImmutableAppComponent.getComponent('my-component')

The getComponent method on the global ImmutableAppComponent instance
will return the component instance identified by its id.

$3

| method name | description |
|-------------|----------------------------------------------------------------|
| bind | bind an input elemement id to a component data property |
| get | get a component data property |
| refresh | request data from server and re-render if changed |
| render | render data on client |
| set | set a component data property |

#### bind

myComponent.bind('element-id', 'property')

Immutable App Components support the binding of input elements to data
properties that will be set from that input if it is changed.

The data property can reference deeply nested data structures via standard
JS syntax (e.g. my.deeply.nested[1].property).

This is a two-way binding so updates to the component data will also update
the bound element.

#### get

myComponent.get('property')

Get a property from the component data state. Like bind, get also supports
accessing deeply nested data properties.

#### refresh

myComponent.refresh()

The refresh method makes a request to the server to retrieve the latest data.
If the data has changed the client will re-render the template.

If the client sends the current data id then data will only be returned if it
has changed.

If the data has changed the client render method will be called to re-render
the data.

myComponent.refresh({serverRender: true})

The serverRender option can be used to have the template rendered on the
server or this can set by default in the component configuration.

#### render

myComponent.render()

The render method will execute the compiled handlebars template with the current
component data and replace the existing component in the DOM.

Every time the component is rendered its internal state is marked as clean and
it will not be automatically re-rendered until its data is changed.

#### set

myComponent.set('property', value)

Set a property in the component state data. Like bind and get, set also
supports accessing deeply nested data properties.

Whenever set is called the clean property will be set to false and the
component will be automatically re-rendered at the next interval.

$3

myComponent.preRender = function (data) {
...
}

Each component method (bind, get, refresh, render, set) has a pre and
a post hook that can be set with a function that customizes the component
behavior.

These methods are: preBind, preGet, preRefresh, preRender, preSet,
postBind, postGet, postRefresh, postRender and postSet.

Hooks can be used both to modify default actions and to integrate components
together and with other application code.

Hooks can be defined in the client.js file or set on the client side by code
outside of the component. Since each hook has only a single function care must
be taken to avoid overwriting hooks.

#### preBind

myComponent.preBind = function (elementId, property, event) {
...
}

preBind is called with the the id of the element to be bound, the name of the
property to bind to, and the name of the event to bind to which may be change,
input or undefined (both). If preBind returns false the bind will not be
performed.

#### preGet

myComponent.preGet = function (property) {
...
}

preGet is called with the name of the property to get. If preGet returns a
value this value will be returned to the caller of get and postGet will be
called.

#### preRefresh

myComponent.preRefresh = function (args) {
...
}

preRefresh is called with the arguments to refresh if there were any. If
preRefresh returns false the refresh will not be performed.

#### preRender

myComponent.preRender = function (args) {
...
}

preRender is called with the arguments to render if there were any. If
preRender returns false the render will not be performed.

#### preSet

myComponent.preSet = function (property, value, event) {
...
}

preSet is called with the property to set, and the value to set. If preSet
returns false the set will not be performed.

If preSet is called from an event handler the event that triggered it will
be passed as the optional third argument.

#### postBind

myComponent.postBind = function (bind) {
...
}

postBind is called with a data object containing information about the bind.
postBind will not be called if the bind failed. The return value of postBind
is ignored.

#### postGet

myComponent.postGet = function (property, value) {
...
}

postGet is called with the name of the property, and the value retrieved. If
postGet returns a value that value will be returned to the caller of get.

#### postRefresh

myComponent.postRefresh = function (args, data) {
...
}

postRefresh is called with the arguments to refresh and the data returned
from the server. If postRefresh returns a value that value will be called to
the caller of refresh.

#### postRender

myComponent.postRender = function (args) {
...
}

postRender is called with the args to render if any. Any return value will
be ignored.

#### postSet

myComponent.postSet = function (property, value, event) {
...
}

postSet is called with the property and value set and optionally the event that triggered the set. Any return value will be ignored.

ImmutableCoreComponent

On the server side each component is backed by an
Immutable Core module with
methods for new, get, and set.

All components are accessed through a single endpoint and the client batches
calls from multiple components into a single request.

$3

var component = this.components.myComponent.new({...})

This syntax can be used from controllers and other Immutable Core methods using
the Immutable AI instance that
they are called with.

Alternatively you can do:

var component = new ImmutableCoreComponent({
name: 'myComponent',
...
})

When the new ImmutableCoreComponent instance is instantiated the component
name will be looked up in the global component register and the new method on
the component module will be called with the original args.

The data return by new is the initial state of the component instance that
will be used to render the component.

The component will only be rendered when the toString method is called.

Immutable Core bind methods (after, before, detach, with) can be used to
modify and extend default component methods.

$3

// my-component.server.js

module.exports = {
get: function (args) {},
new: function (args) {},
set: function (args) {},
}

The server side of a component can have three methods: get, new and set.

All of these methods are optional.

#### get

The get method is called whenever a client makes a refresh request to the
server. The resulting data will be returned to the client and used to
re-render the component.

#### new

The new method returns the initial data state for the component. new must be
called with a single object as arguments and should return a plain object.

#### set

The set method is called whenever data is changed by the client. The arguments
for the set method will include a data property that includes the full current
data state.