React4XP - API reference
Contents
React4XP - API reference
The react4xp library (Enonic Market) exposes a couple of methods that can be run from XP controllers.
Install
Instructions on how to install the library locally or insert it into your project are at the library docs at github.
Import library
const React4xp = require('/lib/enonic/react4xp');
React4xp.render
All-in-one (static) shorthand function for a lot of use cases. Covers both client- and serverside rendering.
Inserts a react component into an (optional) pre-existing HTML string and adds any necessary page contributions to make all work: links to assets, both shared and specific to the entry, and a client-side JS call (.render
or .hydrate
in the client wrapper) that activates the react component in the browser.
Signature
The signature is analogous to thymeleaf’s familiar render(view, model)
. But there are two extra parameters, and a full XP response object is returned:
{body, pageContributions} = React4xp.render(entry, props, request, options);
Parameters
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
string or component object, mandatory |
|||||||||||||||||||||
|
object, optional |
Data model passed into the react component. JS object must be serializable (no functions can be passed). Corresponds to the model argument in |
||||||||||||||||||||
|
XP request object, optional (but mandatory for react activation) |
Include to detect the rendering mode inside/outside Content Studio: inside Content Studio there should be only a static serverside-rendering, no browser react activation (or client-side rendering), only returning get an HTML visualization with the initial |
||||||||||||||||||||
|
object, optional |
Additional options to control the rendering. All of them are optional within this object:
|
Returns
Returns an XP response object with these main attributes:
Attribute | Type | Description |
---|---|---|
|
string, rendered HTML |
HTML output. The root of this HTML is always a surrounding container HTML that will have a matching-ID target element in it somewhere (an element matching the ID of the clientside call to Inside that matching-ID element, there will be a serverside rendering of the entry (with the initial props from |
|
object |
Regular XP page contributions. Includes everything the browser needs to activate (or client-side render) the react component: script tags with urls to auto-compiled assets for the entry and its dependencies, a client-side react4xp wrapper asset and an activating client-wrapper call. Urls point to react4xp’s own optimized asset services. Also included before this, are any input |
React4xp object
Slightly more cumbersome than React4xp.render
, but also more flexible and controllable: create a data-holding react4xp object with the React4xp contructor, manipulate it or extract data from it, and then later render it to an HTML body string and/or page contributions, separately. This is actually what React4xp.render
does behind the scenes.
The "custom flow syntax" lesson focuses on using react4xp data objects.
Constructor
const myComponent = new React4xp(entry);
Creates an initial react4xp data object from an entry.
Parameter | Type | Description |
---|---|---|
|
string or component object, mandatory |
Reference to an entry: the react component to be rendered. Direct JsxPath string, or a |
Constructs a react4xp data object, which exposes the attributes and methods below:
Main object attributes
Extract from the object the data that has been generated or set in it.
Name | Type | Description |
---|---|---|
|
string |
Target |
|
string |
jsxPath to the entry. |
|
object |
|
const targetElementId = myComponent.react4xpId;
Setter methods
Use these to set the object’s properties. All of them are optional; if not used, the object will render with empty values or placeholders where needed, along the same logic as for React4xp.render above.
All the setter methods return the data object itself, so that you can use a builder pattern where…
myComponent.firstSetter("a").secondSetter("b").thirdSetter("c");
…is equivalent to:
myComponent.firstSetter("a");
myComponent.secondSetter("b");
myComponent.thirdSetter("c");
The order between the setters doesn’t matter, with the exception if setId
and uniqueId
which affect each other.
.setProps
myComponent.setProps(props);
Sets props for the entry.
Parameter | Type | Description |
---|---|---|
|
object, mandatory |
|
.setId
myComponent.setId(id);
Sets an ID (directly and literally, so uniqueness is up to you) of both the target HTML element for rendering the entry into, and the ID of the data object itself (react4xpId
). If renderBody()
is run later without finding a matching element ID in body
, this sets the ID of a generated element in the HTML output.
If the data object already has an ID, .setId(id)
will overwrite it. If id
is omitted, .setId()
just deletes any previous ID (which has the later effect of giving this a new, unique ID at the time of rendering).
Parameter | Type | Description |
---|---|---|
|
string, optional |
ID of both the target HTML element and the data object itself. |
.uniqueId
myComponent.uniqueId();
Enforces a unique ID, either by itself or after running .setId()
. If the object already has an ID (react4xpId
), a random-ID string will be added to it. If not, the ID will just be a new random ID.
No parameters.
.setJsxPath
myComponent.setJsxPath(jsxPath);
If you for some reason need to override the JsxPath that was set (or inferred from the component object) in the constructor.
Parameter | Type | Description |
---|---|---|
|
string, mandatory |
New jsxPath to a different entry. |
Rendering methods
These methods perform specific rendering tasks independently, using the data object as a basis, the way it’s set up with the setters and with the entry from the constructor (or the setJsxPath
setter).
Most of these rendering methods will lock down the jsxPath and ID if the react4xp data object, the first time one of them is run. After this, the setters will prevent these from being changed so that another conflicting rendering can’t be performed from the same data object. |
.renderBody
const responseBody = myComponent.renderBody(options);
Similar to React4xp.render above, but renders only a static HTML output.
Renders based on the state of the data object at the time of rendering, and with fewer option
parameters than React4xp.render
.
The static HTML will always contain a target element for rendering the entry into. That target element contains a serverside rendering of the entry if serverside is switched on (clientRender
is falsy).
Does not render page contributions. Run |
Parameters:
Parameter | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
object, optional |
Options to control the rendering, all of them optional:
|
Returns:
Returns an HTML string ready to return as the body
attribute in an XP response object from the controller.
The root of the returned HTML is always a surrounding container HTML that will have a matching-ID target element in it somewhere (an element matching the data object’s ID (react4xpId
), either from the ID setter methods, or a generated ID if they haven’t been run). This surrounding structure is options.body
, unchanged if that already contained a matching-ID element, or with a new target element generated and inserted at the end if it didn’t have one. If there is no options.body
, the surrounding container is just a generated target element.
Inside that matching-ID element, there will be a serverside rendering of the entry (with the initial props from .setProps
) if options.clientRender
is falsy.
.renderPageContributions
const outputPageContributions = myComponent.renderPageContributions(options);
Similar to React4xp.render above, but only renders the page contributions needed to run and activate the react component in the browser. Whether the trigger call is .render
or .hydrate
depends on if options.clientRender
is truthy or falsy, respectively.
Renders based on the state of the data object at the time of rendering, and with fewer option
parameters than React4xp.render
.
Does not render any HTML. Run Also, there is no detection of inside-vs-outside Content Studio, and consequently the client is not automatically prevented from running client-side code in Content Studio. That is not recommended, see the examples for how to handle this. |
Parameters:
Parameter | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
object, optional |
Options to control the rendering, all of them optional:
|
Returns:
A regular XP page contributions object, ready to be used as the pageContributions
attribute in an XP response object from the controller.
Includes everything the browser needs to activate (or client-side render) the react component: script tags with urls to auto-compiled assets for the entry and its dependencies, a client-side react4xp wrapper asset and an activating trigger call to the client wrapper. Urls point to react4xp’s own optimized asset services. Also included before this, are any input options.pageContributions
.
With a serverside rendering (options.clientRender
is falsy), the client will expect an existing target element with a pre-rendered entry in the response body
, and call react4xp.CLIENT.hydrate
. If options.clientRender
is truthy, an empty target element is expected in the response body
, and the rendering is left to the client with react4xp.CLIENT.render
.
.renderEntryToHtml
const entryHTML = myComponent.renderEntryToHtml(overrideProps);
Helper rendering tool, for utility purposes.
Pure serverside rendering of the entry to a static HTML string, without any surrounding HTML, target container or anything, just the entry.
Parameter | Type | Description |
---|---|---|
|
object, optional |
If omitted, the data object’s own props (from JS object must be serializable (no functions can be passed). |
Returns a static HTML representation of the entry.
.renderTargetContainer
const targetContainerHTML = myComponent.renderTargetContainer(body, content);
Helper rendering tool, for utility purposes.
Generates a matching-ID target container based on the ID (react4xpId
) of the react4xp object, intended for an entry to be rendered into later.
Parameter | Type | Description |
---|---|---|
|
string, optional: valid HTML |
Similar to If If |
|
string, optional |
If included, this is inserted into the target element in the output. (Note that if you later perform a react rendering into the target element, any |
Returns an HTML representation that will contain a matching-ID target element, which (depending on body
and content
) may be surrounded by other HTML and/or have a content of its own.