Home

Awesome

oc-client

Node.js client for OpenComponents

NPM

Node.js version: 6 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:

Parametertypemandatorydescription
cacheobjectnoCache options. If null or empty will use default settings (never flush the cache)
cache.flushIntervalnumber (seconds)noThe interval for flushing the cache
componentsobjectyesThe components to consume with versions
components[name]stringyesThe component version
forwardAcceptLanguageToClientbooleannoDefault 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
registriesobjectyesThe registries' endpoints
registries.serverRenderingstringnoThe baseUrl for server-side rendering requests
registries.clientRenderingstringnoThe baseUrl for client-side rendering requests
templatesarraynoThe templates available to the client, will extend the default: [require('oc-template-handlebars'), require('oc-template-jade')]

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:

Parametertypemandatorydescription
headersobjectnoAn object containing all the headers that must be forwarded to the components' requests
timeoutnumber (seconds)noDefault 5. Maximum amount of time to wait during requests
renderComponentsfunctionnoA function to renderComponents on warmup. Defaults to client own implementation

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), rendered html, and details (which includes headers).

Options:

Parametertypemandatorydescription
containerbooleannoDefault false, when false, renders a component without its <oc-component> container
disableFailoverRenderingbooleannoDisables the automatic failover rendering in case the registry times-out (in case configuration.registries.clientRendering contains a valid value.) Default false
forwardAcceptLanguageToClientbooleannoWhen 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
headersobjectnoAn object containing all the headers that must be forwarded to the component
parametersobjectnoAn object containing the parameters for component's request
registriesobjectnoThe registries' endpoints (overrides the parameters defined during instantiation)
registries.serverRenderingstringnoThe baseUrl for server-side rendering requests (overrides the parameter defined during instantiation)
registries.clientRenderingstringnoThe baseUrl for client-side rendering requests (overrides the parameter defined during instantiation)
renderstringnoDefault 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
timeoutnumber (seconds)noDefault 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, details){
  console.log(html, details.headers);
  // => "<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), 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:

Parametertypemandatorydescription
componentsarray of objectsyesThe array of components to retrieve and render
components[index].namestringyesThe component's name
components[index].versionstringnoThe 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].parametersobjectnoThe component's parameters
components[index].containerbooleannoThe 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 <oc-component> container
components[index].renderstringnoThe 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:

Parametertypemandatorydescription
containerbooleannoDefault true, when false, renders a component without its <oc-component> container
disableFailoverRenderingbooleannoDisables the automatic failover rendering in case the registry times-out (in case configuration.registries.clientRendering contains a valid value.) Default false
forwardAcceptLanguageToClientbooleannoWhen 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
headersobjectnoAn object containing all the headers that must be forwarded to the component
ie8booleannoDefault false, if true puts in place the necessary polyfills to make all the stuff work with ie8
parametersobjectnoGlobal parameters for all components to retrieve. When component has its own parameters, globals will be overwritten
registriesobjectnoThe registries' endpoints (overrides the parameters defined during instantiation)
registries.serverRenderingstringnoThe baseUrl for server-side rendering requests (overrides the parameter defined during instantiation)
registries.clientRenderingstringnoThe baseUrl for client-side rendering requests (overrides the parameter defined during instantiation)
renderstringnoDefault 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
timeoutnumber (seconds)noDefault 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, details){
  for ( let i; i < htmls.length; i++) {
    console.log(htmls[i], details[i].headers);
  }
  // => ["<div>Header</div>",
  //     "<p>Footer</p>",
  //     "<oc-component href=\"\/\/registry.com\/advert\/?position=left\"><\/oc-component>"]
});