Skip to main content

Client-side rendering

Integration​

To make this happen, a components registry has to be publicly available. This is how to integrate the component:

<html>
  <head></head>
  <body>
    <oc-component
      href="//my-components-registry.mydomain.com/hello-world/1.X.X"
    ></oc-component>
    <script src="//my-components-registry.mydomain.com/oc-client/client.js"></script>
  </body>
</html>
  • It is recommended to use protocol-less urls for rendering so that we can use https where possible for security reasons
  • The /oc-client/client.js is a convenient shortcut for serving the browser oc-client of the same version as the registry.
  • The client can be before or after the components. When after, a rendering needs to happen via explicit call as described in this page: advanced client-side operations.

What exactly happens during a component's client-side rendering?​

  1. The first thing is for the client to be initialised. This includes verifying the dependencies are satisfied (for instance, jQuery)
  2. At the end of the initialisation, the client is going to fire an event oc:ready
  3. Then the client is going to scan for <oc-component> tags in the page and for each one of them:
  4. It is going to make an HTTP GET to the href parameter of the component, sending a Accept: application/vnd.oc.unrendered+json header (which is the standard header for getting an unrendered component).
  5. In case of error (timeout or 5xx response) the client is going to retry 30 times (retry attempts and timeout are configurable)
  6. In case of success, the client is going to find what kind of template the component uses and verify dependencies are satisfied. In case of Handlebars, for instance, it is going to ensure the handlebars runtime is available and ready, if it is not it's going to download it and then go to the next step
  7. The client will take the compiled view url, for instance //cdn.com/components/my-component/1.2.3/template.js and put it in the <head> tag, then waiting for it to be ready. If the template is already there (for example because there are multiple components of the same type and version in the page) it is going to skip step 7. When the template is ready it is exposed in the window.oc.components['hash-of-the-component'] namespace as a function: view(viewModel)=html.
  8. This is going to take the viewModel (part of the HTTP response) and use it to render the view, in order to obtain the html. When finished, it is going to place the HTML result inside the <oc-component> container tag. Some templates may perform additional actions. In case of a React template, for instance, the HTML may be bound to the Virtual DOM.
  9. An oc:rendered event is published containing the pointer to the component, and all the information (version, name, html, etc.)
  10. Back to 3) In order to render, in case, nested client-side components

What can I do in the client-side?​

Look at this page: advanced client-side operations