react4xp-runtime-client

    2.0.0 • Public • Published

    react4xp-runtime-client

    Used by a an Enonic XP root project, builds an asset used by the browser at buildtime.

    Supplies source code and a webpack setup to compile it.

    Usage

    Not really intended for separate installation or use. Part of the react4xp NPM bundle. Better start with the React4xp introduction.

    API: webpack build

    The webpack config takes two CLI arguments, mandatory from the root project. These are one the form of --env X=..., where X is any of the capital-letter keys below.

    • REACT4XP_CONFIG_FILE: root-project-relative path to a react4xp-project constant-values JSON file.
      • This file follows the format of, and is usually produced in the project by, react4xp-buildconstants.
      • The used values from it can be overriden by CLI env arguments: BUILD_R4X, LIBRARY_NAME, BUILD_ENV , CHUNK_CONTENTHASH, CLIENT_CHUNKS_FILENAME.
    • ROOT: absolute path to the root project

    API: client runtime

    In a standard react4xp setup, lib-react4xp serves the built client asset from the service react4xp-client. The lib also offers render controller-functions, that add a call to this react4xp-client URL, to the page contribution.

    That client asset adds an object to the global namespace in the browser: React4xp (or whatever the value of LIBRARY_NAME is). This object will contain the entries, under a key corresponding to their jsxPath.

    In addition to those, there is React4xp.CLIENT, which exposes three methods. These methods are also automatically called in the browser when using the render controller functions, but should you ever need them they are:

    render

    This corresponds to (and calls under the hood) ReactDOM's render function:

    React4xp.CLIENT.render(Component, targetId, props, isPage, hasRegions);
    • Component (string or object, mandatory): jsxPath of a react4xp entry, or a reference to that object in the React4xp namespace: React4xp[jsxPath].
    • targetId (string, mandatory): unique DOM id of the container where the entry will be rendered.
    • props (serializable object, optional): top-level data used by the entry
    • isPage (truthy/falsy, optional): truthy flags that the entry is the view of a page controller.
    • hasRegions (truthy/falsy, optional): truthy flags that the entry contains XP regions and that CLIENT may need to postprocess them.

    NOTE: render expects all necessary assets to already be loaded and run (this also happens automatically when using the controller function render): the entry asset, all its dependencies and react/react-dom themselves.

    hydrate

    This corresponds to (and calls under the hood) ReactDOM's hydrate function.

    React4xp.CLIENT.hydrate(Component, targetId, props, isPage, hasRegions);

    It's simply the hydrate version of React4xp.CLIENT.render - the signature and arguments are the same.

    Obviously, in addition to expecting assets to be loaded and run, it also expects an existing server-side-rendered DOM inside the target container element. Again, this is handled by the controller function render.

    renderWithDependencies

    This is purely a utility function for cases where the controller function render has not already taken care of things, but you need to render a react4xp entry from the client alone. Based on which entry or entries are requested, a service from lib-react4xp is called to find all required assets for the entries and their dependencies, then those are loaded, and finally React4xp.CLIENT.render is called for each of them.

    React4xp.CLIENT.renderWithDependencies(entriesWithTargetIdsAndProps, callback, serviceUrlRoot);
    • entriesWithTargetIdsAndProps (object, mandatory): keys in this object are are entry names (string: jsxPath) and the values are objects with a mandatory targetId attribute and an optional props attribute - which is a regular serializable object of any shape. Entries are loaded on the page in the order of the entry name keys.
    • callback (function, optional): called after the entire call chain is complete.
    • serviceUrlRoot (string, kinda-sorta-optional): root of the URL to the lib-react4xp's services - e.g. your app.
      • For example, if they have the URLs /_/service/my.app/react4xp/ and /_/service/my.app/react4xp-dependencies/, then serviceRootUrl should be /_/service/my.app - without a trailing slash.
      • You can skip this argument ONLY IF you define the constant SERVICE_URL_ROOT in global namespace before this call.

    Keywords

    none

    Install

    npm i react4xp-runtime-client

    DownloadsWeekly Downloads

    136

    Version

    2.0.0

    License

    Apache-2.0

    Unpacked Size

    38.6 kB

    Total Files

    6

    Last publish

    Collaborators

    • espen42