node package manager

oc-client

oc-client

Node.js client for OpenComponents

NPM

Node.js version: 4 required

Build status: Linux: Build Status | Windows: Build status

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(options)

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

Example:

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

Client#init(options, callback)

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

Example:

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: '<b>hello</b>'} 
});

Client#getComponentsInfo(components, callback)

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

Example:

...
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'
    }
  }] */
});

Client#renderComponent(componentName [, options], callback)

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) and rendered html.

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
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:

...
client.renderComponent('header', {
  container: false,
  headers: {
    'accept-language': 'en-GB'
  },
  parameters: {
    loggedIn: true
  },
  timeout: 2
}, function(err, html){
  console.log(html);
  // => "<div>This is the header. <a>Log-out</a></div>" 
});

Client#renderComponents(components [, options], callback)

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) and an array of rendered html snippets. 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:

...
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){
  console.log(html);
  // => ["<div>Header</div>", 
  //     "<p>Footer</p>", 
  //     "<oc-component href=\"\/\/registry.com\/advert\/?position=left\"><\/oc-component>"] 
});