oc-client
=========


Node.js client for OpenComponents


Node.js version: 6 required

Build status: Linux:  | Windows:

Disclaimer: This project is still under heavy development and the API is likely to change at any time. In case you would find any issues, check the troubleshooting page.

API

* new Client()
* Client#init()
* Client#getComponentsInfo()
* Client#renderComponent()
* Client#renderComponents()

$3

It will create an instance of the client. Options:

|Parameter|type|mandatory|description|
|---------|----|---------|-----------|
|cache|object|no|Cache options. If null or empty will use default settings (never flush the cache)|
|cache.flushInterval|number (seconds)|no|The interval for flushing the cache|
|components|object|yes|The components to consume with versions|
|components[name]|string|yes|The component version|
|forwardAcceptLanguageToClient|boolean|no|Default false. When true, when doing client-side requests (normal or failover) appends a custom parameter to the browser's component hrefs so that the framework will ignore the browser's Accept-Language in favour of the query-string value|
|registries|object|yes|The registries' endpoints|
|registries.serverRendering|string|no|The baseUrl for server-side rendering requests|
|registries.clientRendering|string|no|The baseUrl for client-side rendering requests|
|templates|array|no|The templates available to the client, will extend the default: [require('oc-template-handlebars'), require('oc-template-jade')]|

Example:

``js
var Client = require('oc-client');

var client = new Client({
registries: { serverRendering: 'https://myregistry.com/'},
components: {
hello: '1.2.3',
world: '~2.2.5',
bla: ''
}
});
`

$3

It will warmup the components that have been declared during the instantiation. Options:

|Parameter|type|mandatory|description|
|---------|----|---------|-----------|
|headers|object|no|An object containing all the headers that must be forwarded to the components' requests|
|timeout|number (seconds)|no|Default 5. Maximum amount of time to wait during requests|
|renderComponents|function|no|A function to renderComponents on warmup. Defaults to client own implementation|

Example:

`js
var Client = require('oc-client');

var client = new Client({
registries: { serverRendering: 'https://myregistry.com/'},
components: {
hello: '1.2.3'
}
});

client.init({
headers: { 'accept-language': 'en-US'}
}, function(error, responses){
console.log(error);
// => something like null or Error making request to registry

console.log(responses);
// => something like { hello: 'hello'}
});
`

$3

It will get the components' resolved versions for given requested versions. Useful for polling mechanism and caches management.

Example:
`js
...
client.getComponentsInfo([{
name: 'header',
version: '1.X.X'
}], function(error, infos){
console.log(infos);
/* => [{
componentName: 'header',
requestedVersion: '1.X.X',
apiResponse: {
name: 'header',
requestVersion: '1.X.X',
type: 'oc-component',
version: '1.2.4'
}
}] */
});
`

$3

It will resolve a component href, will make a request to the registry, and will render the component. The callback will contain an error (if present), rendered html, and details (which includes headers).

Options:

|Parameter|type|mandatory|description|
|---------|----|---------|-----------|
|container|boolean|no|Default false, when false, renders a component without its container|
|disableFailoverRendering|boolean|no|Disables the automatic failover rendering in case the registry times-out (in case configuration.registries.clientRendering contains a valid value.) Default false|
|forwardAcceptLanguageToClient|boolean|no|When not specified in config, defaults to false. When true, when doing client-side requests (normal or failover) appends a custom parameter to the browser's component hrefs so that the framework will ignore the browser's Accept-Language in favour of the query-string value|
|headers|object|no|An object containing all the headers that must be forwarded to the component|
|parameters|object|no|An object containing the parameters for component's request|
|registries|object|no|The registries' endpoints (overrides the parameters defined during instantiation)|
|registries.serverRendering|string|no|The baseUrl for server-side rendering requests (overrides the parameter defined during instantiation)|
|registries.clientRendering|string|no|The baseUrl for client-side rendering requests (overrides the parameter defined during instantiation)|
|render|string|no|Default server. When server, it will return html. When client will produce the html to put in the page for post-poning the rendering to the browser|
|timeout|number (seconds)|no|Default 5. When request times-out, the callback will be fired with a timeout error and a client-side rendering response (unless disableFailoverRendering is set to true)|

Example:
`js
...
client.renderComponent('header', {
container: false,
headers: {
'accept-language': 'en-GB'
},
parameters: {
loggedIn: true
},
timeout: 2
}, function(err, html, details){
console.log(html, details.headers);
// => "

"
});
`

$3

It will make a request to the registry, and will render the components. The callback will contain an array of errors (array of null in case there aren't any), an array of rendered html snippets, and an array of details. It will follow the same order of the request. This method will make 1 request to the registry + n requests for each component to get the views of components that aren't cached yet. After caching the views, this will make just 1 request to the registry.

Components parameter:

|Parameter|type|mandatory|description|
|---------|----|---------|-----------|
|components|array of objects|yes|The array of components to retrieve and render|
|components[index].name|string|yes|The component's name|
|components[index].version|string|no|The component's version. When not speficied, it will use globally specified one (doing client initialisation); when not specified and not globally specified, it will default to "" (latest)|
|components[index].parameters|object|no|The component's parameters|
|components[index].container|boolean|no|The component's container option. When not specified, it will be the one specified in the options (for all components); if none is specified in options, it will default to true. When false, renders a component without its container|
|components[index].render|string|no|The component's render mode. When not specified, it will be the one specified in the options (for all components); if none is specified in options, it will default to server. When server, the rendering will be performed on the server-side and the result will be component's html. If client, the html will contain a promise to do the rendering on the browser.|

Options:

|Parameter|type|mandatory|description|
|---------|----|---------|-----------|
|container|boolean|no|Default true, when false, renders a component without its container|
|disableFailoverRendering|boolean|no|Disables the automatic failover rendering in case the registry times-out (in case configuration.registries.clientRendering contains a valid value.) Default false|
|forwardAcceptLanguageToClient|boolean|no|When not specified in config, defaults to false. When true, when doing client-side requests (normal or failover) appends a custom parameter to the browser's component hrefs so that the framework will ignore the browser's Accept-Language in favour of the query-string value|
|headers|object|no|An object containing all the headers that must be forwarded to the component|
|ie8|boolean|no|Default false, if true puts in place the necessary polyfills to make all the stuff work with ie8|
|parameters|object|no|Global parameters for all components to retrieve. When component has its own parameters, globals will be overwritten|
|registries|object|no|The registries' endpoints (overrides the parameters defined during instantiation)|
|registries.serverRendering|string|no|The baseUrl for server-side rendering requests (overrides the parameter defined during instantiation)|
|registries.clientRendering|string|no|The baseUrl for client-side rendering requests (overrides the parameter defined during instantiation)|
|render|string|no|Default server. When server, it will return html. When client will produce the html to put in the page for post-poning the rendering to the browser|
|timeout|number (seconds)|no|Default 5. When request times-out, the callback will be fired with a timeout error and a client-side rendering response (unless disableFailoverRendering is set to true)|

Example:
`js
...
client.renderComponents([{
name: 'header',
parameters: { loggedIn: true }
}, {
name: 'footer',
version: '4.5.X'
}, {
name: 'advert',
parameters: { position: 'left' },
render: 'client'
}], {
container: false,
headers: {
'accept-language': 'en-US'
},
timeout: 3.0
}, function(errors, htmls, details){
for ( let i; i < htmls.length; i++) {
console.log(htmls[i], details[i].headers);
}
// => ["

",
// "

Footer

",
// "<\/oc-component>"]
});
``