will be inserted at the end of the body, inside the root element. If
* body is missing, a pure-target-container body is generated and returned.
* @param content {string} HTML content that, if included, is inserted into the container with the matching Id.
* @returns {string} adjusted or generated HTML body with rendered react component.
*/
renderTargetContainer(body, content) {
this.ensureAndLockId();
// If no (or empty) body is supplied: generate a minimal container body with only a target container element.
if (((body || '') + "").replace(/(^\s+)|(\s+$)/g, "") === "") {
return buildContainer(this.react4xpId, content);
}
// If there is a body but it's missing a target container element:
// Make a container and insert it right before the closing tag.
if (!bodyHasContainer(body, this.react4xpId)) {
return HTMLinserter.insertAtEndOfRoot(body, buildContainer(this.react4xpId, content));
}
if (content) {
return HTMLinserter.insertInsideContainer(body, content, this.react4xpId);
}
return body;
}
/** Renders a pure static HTML markup of ONLY the react4xp entry, without a surrounding HTML markup or container.
* Can override props that have previously been added to this component.
*/
renderEntryToHtml = (overrideProps) => SSRreact4xp.renderToString(this.jsxPath, JSON.stringify(overrideProps || this.props));
/** Server-side rendering: Renders a static HTML markup and inserts it into an ID-matching target container in an HTML body. If a
* matching-ID container (or a body) is missing, it will be generated.
* @param body {string} Existing HTML body, for example rendered from thymeleaf.
* @returns {string} adjusted or generated HTML body with rendered react component.
*/
renderSSRIntoContainer(body) {
const componentString = this.renderEntryToHtml();
return this.renderTargetContainer(body, componentString);
}
renderBody = params => {
const {body, clientRender} = params || {};
return clientRender ? this.renderTargetContainer(body) : this.renderSSRIntoContainer(body);
};
//-------------------------------- RENDERING page contributions for importing entry / dependency chunks --------------
/** Generates or modifies existing enonic XP pageContributions. Adds client-side dependency chunks (core React4xp frontend,
* shared libs and components etc, as well as the entry component scripts.
* Also returns/adds small scripts that trigger the component scripts. Prevents duplicate references to dependencies.
*
* @param params {object} Additional parameters controlling the react rendering. All of them are optional:
* - pageContributions PageContributions object that will be added before the new pageContributions.
* - clientRender If clientRender is truthy, this function will assume that the react4xp entry is not being rendered
* server-side (by .renderBody), and only calls a 'render' command in the client. If omitted or falsy, server-side
* rendering is assumed, and a 'hydrate' command is called on the entry instead.
*/
renderPageContributions = params => {
const {pageContributions, clientRender} = params || {};
const command = clientRender ? 'render' : 'hydrate';
this.ensureAndLockBeforeRendering();
return getAndMergePageContributions(this.jsxPath, pageContributions, {
bodyEnd: [
// Browser-runnable script reference for the react4xp entry. Adds the entry to the browser (available as e.g. React4xp.CLIENT.
), ready to be rendered or hydrated in the browser:
``,
// Calls 'render' or 'hydrate' on the entry (e.g. React4Xp.CLIENT.render( ... )), along with the target container ID, and props:
``
]
});
};
///////////////////////////////////////////////// STATIC ALL-IN-ONE RENDERER
/** Main renderer. Default behavior: renders server-side and adds hydration logic for the client-side.
* However, renders a static, unhydrated server-side HTML string if request is missing or in edit mode.
* Or can render a container element with client-side rendering logic.
* On problems/errors, logs and falls back to a placeholder output which marks the problem on the page.
*
* @param entry {string|object} Mandatory reference to the React4xp entry JSX file. Corresponds to "view" parameter in the thymeleaf renderer etc.
* Can be a string or an object:
* If it's a string, it's interpreted as a jsxPath.
* If it's an object, it's interpreted as a component object from portal.getComponent(), and will be used to both find the JSX file and generate a unique ID (see also the params below).
* @param props {object} Optional object. Sends props to the JSX file. Corresponds to "model" parameter in the thymeleaf renderer etc.
* @param request {object} XP request object (from controller get-method etc). Mandatory for proper react rendering, but strictly speacking optional:
* If omitted, the rendering will fall back to a template-like JSX rendering: outputs a static HTML string using the props,
* and it will not be activated/hydrated in the client.
* @param params {object} Additional parameters controlling the react rendering. All of them are optional:
* - clientRender {boolean} Controls server-side vs client-side rendering (as long as a request argument is given, see above).
* Server-side rendering (SSR) is the default behavior if this parameter is missing or falsy: a static HTML string is rendered as output, and react hydrate() pageContributions are added.
* If set to true, however, client-side rendering is forced: only a target container with an element ID is rendered in the output, but react render() pageContributions are added.
* - id {string} sets the target container element ID.
* (by force - if an ID was generated from a component-type entry object (see above), this manual ID will override the generated one).
* If the ID matches an DOM element ID in an input body (see body below), the rendered react component will be inserted in that element. If not, a container with this ID will be added.
* If there's no body parameter at all, an HTML string with a matching-ID element is generated.
* If the id parameter is omitted, a generic unique ID is generated as if uniqueId below is set to true.
* - uniqueId {boolean|string} If set, takes an extra step to ensure a unique ID:
* If id is already set (by previous param or using a component-object entry), a random integer will be postfixed to it.
* If uniqueId is a string, this is the prefix before the random postfix. If the id param is used in addition to a uniqueId string, uniqueId takes presedence and overrides id.
* - body {string} HTML string, for example a static string, or previously rendered from other react4xp output, thymeleaf or other templating engines.
* If it already has a matching-ID target container, body passes through unchanged (use this option and the setId method to control where in the body the react component should be inserted).
* If it doesn't have a matching container, a matching will be inserted at the end of the body, inside the root element.
* If body is missing, a pure-target-container body is generated and returned.
* - pageContributions {object} Pre-existing pageContributions.
* If added, page contributions generated during this rendering will be added to (merged with) the input parameter ones.
*
* @returns a response object that can be directly returned from an XP controller, with body and pageContributions attributes
*/
static render = (entry, props = {}, request = null, params = {}) => {
let react4xp;
try {
if (typeof entry === 'string') {
params.jsxPath = entry;
} else if (entry && typeof entry === 'object') {
params.component = entry;
}
if (props && typeof props === 'object') {
params.props = props;
}
const { clientRender } = params;
react4xp = React4xp._buildFromParams(params);
const {body, pageContributions} = params || {};
if (!request || request.mode === "edit" || request.mode === "inline") {
return {
body: react4xp.renderSSRIntoContainer(body),
pageContributions
};
} else {
return {
body: clientRender ?
react4xp.renderTargetContainer(body) :
react4xp.renderSSRIntoContainer(body),
pageContributions: react4xp.renderPageContributions({pageContributions, clientRender})
};
}
} catch (e) {
log.error(e);
log.error("entry (" + typeof entry + "): " + JSON.stringify(params));
log.error("props (" + typeof props + "): " + JSON.stringify(props));
log.error("request (" + typeof request + "): " + JSON.stringify(request));
log.error("params (" + typeof params + "): " + JSON.stringify(params));
const r = react4xp || {};
return {
body: buildErrorContainer(r.jsxPath, r.react4xpId)
}
}
};
}
module.exports = React4xp;