A React component that allows OpenComponents to operate within a react application.
npm install react-oc``bash`
npm install react-oc
The easiest setup would involve installing the oc-client npm package (npm install oc-client) and using it to server-side render the oc-client oc-component.
`js
const Client = require('oc-client');
const client = new Client(...);
// This will provide the script tag that loads the oc-client-browser code.
const ocClientMarkup = await new Promise((resolve, reject) => {
client.renderComponent('oc-client', {}, function(err, html) {
resolve(html);
});
});
`
`js
// if using express:
const serverRenderedReactApp = ReactDOMServer.renderToString(...);
res.send(
);
`Usage
1. Wrap your application with
.
`jsx
export async function main() {
// pseudo code: This would typically run only server side and provide a
// hash table: { header: 'my header', footer: 'my footer' }
const components = await getComponents([{name: 'footer'}, {name: 'header'}]); return (
lang='en-GB'
prefetchedComponents={components}
// this allows oc to be defined in the browser, and falsy on the server.
clientOc={typeof window === 'object' && window.oc}>
);
}
`2. Use
to render a client-side only oc-component.
`jsx
export const MySubComponent1 = (props) => (
Welcome to my application.
)
`
When called on the server-side, the react-component will render an empty div. Then when hydrated/rendered on the client side, the react-component will expect to be defined in the parent react-component.3. Use
to render markup fetched on the server side.
`jsx
export const MySubComponent2 = (props) => (
Welcome to my application.
)
`
When called on the server-side, the react-component will expect to be defined in the parent react-component which will be an object. The prefetchKey refers to the key in that object that holds the markup. On the client side, this react-component will preserve the markup when hydrating. Rendering prefetched oc-components exclusively on the client-side is not yet supported.
| prop | mandatory | description |
|---|---|---|
| name | yes | see oc.build options. |
| parameters | no | see oc.build options. |
| lang | no | see oc.build options. |
| version | no | see oc.build options. |
| id | no | this id is applied to the container element. |
| className | no | this className is applied to the container element. |
| captureAs | no | see Capture Functionality. |This react-component will use
oc.build to render an tag within a div element. After being rendered, oc.renderNestedComponent is used to fetch and render the oc-component from the registry specified in .To mitigate the styling issues of wrapping an oc-component in a div element, there are two passthrough props that will be applied to the container div element:
id and className.This react-component expects the following props to be defined in the parent
react-component:| prop | description |
|---|---|
| baseUrl | see oc.build options. |
| clientOc | the global oc library usually found at
window.oc. |
| lang | this property is optional, but will be used as the default if no lang was specified on the node. see oc.build options. |NOTE: When server-side rendering, you may safely provide undefined for these properties.
IMPORTANT: This component was designed to support both universal and client-only react applications. It is expected that there will be no if hydrating on the client-side. If you provide prefetchedComponents on the client-side, any script tags provided will execute twice.| prop | mandatory | description |
|---|---|---|
| prefetchKey | yes | the key that represents the prefetched html markup. |
| fallback | no | by default, in the case of failure to find the relevant html markup, the react-component will render an empty div. You may provide a string that will be interpreted as html and injected into the div instead. |
| captureAs | no | see Capture Functionality. |
This react-component is designed to enable server-side rendering. Given a prefetchedComponents prop was provided to the parent
react-component, this react-component will render the markup. In the case where oc-client provides a failover tag (see: disableFailoverRendering), this react-component will call oc.renderNestedComponent on the client side to ensure that the oc-component loads correctly.This react-component expects the following props to be defined in the parent
react-component:| prop | description |
|---|---|
| prefetchedComponents | a hash table object
{key: value, ...} where key will be matched with prefetchKey, and the value is a string containing the markup that was fetched using oc-client. |NOTE: When hydrating over server-side rendered markup, you should provide undefined for prefetchedComponents. The react-component will not modify the markup provided by the server when hydrating.
Capture As
By setting a captureAs prop on the and components, you enable the ability to remove and restore the oc application from the DOM without losing state or registered event handlers. This can be useful when creating an single page application where components that contain oc components may be removed and re-added as the user interacts with the application.The value provided to
captureAs is important; the value will be used as an identifier so that we can restore the appropriate captured oc-component. This also allows us to restore the oc-component to different places, effectively moving the oc-component around without losing state. Depending on how the self contained oc-component is, this may cause to unexpected side effects.Warning: the oc-component is not cloned. This means that if multiple components with the same
captureAs value exist on the same page at the same time, only one of the