defining your own source structure

Contents

defining your own source structure

Lesson overview

So far, every time we’ve referenced a .jsx react component from react4xp in a controller, we’ve used a component object in the entry argument of React4xp.render. This is just a shortcut, and it depends on an "XP-conventional" naming regime to work: the .jsx source file must be in the same folder as the controller, and have the same name.

It doesn’t have to be that way. In this example, we’ll take a look at which react components are available to React4xp.render - called entries in react4xp - and how to reference them, whatever they’re called and wherever they’re located.


Entries and locations

For react components to be available to React4xp the way we’ve seen so far, their JSX source files must be located in certain folders where react4xp is looking for them and auto-compiles them.

When they are located where they should (and export a props⇒component function), those react components are called entries (full reference).


1: Below site/

Below the folder src/main/resources/site/, all source files with the extension .jsx are detected at compile-time and available as entries to react4xp. If you take the path relative to resources/ and the file name without the extension, you get a string that can be used to point react4xp to that react component:

  • "site/parts/hello-react/hello-react"src/main/resources/site/parts/hello-react/hello-react.jsx

  • "site/parts/color/color"src/main/resources/site/parts/color/color.jsx

  • "site/parts/color/differentEntry"src/main/resources/site/parts/color/differentEntry.jsx

…​etc.

These strings are called jsxPaths in react4xp, and they can be used directly in controllers as the entry argument. For example in the color Part controller from before:

site/parts/color/color.es6
React4xp.render(
    component,
    props,
    request,
    options
);

…​is equivalent to:

React4xp.render(
    "site/parts/color/color",
    props,
    request,
    options
);

And so on. Calling the .jsx source file something else, or having it in a different folder, is fine as long as you refer it correctly like this.

jsxPaths are name strings, not relative paths! You can’t refer to color.jsx from color.es6 as "color" or "./color" etc.
If you look at the rendered HTML output in page source, you can see React4xp using the jsxPaths to refer to the compiled assets from the client - even if you used the component object in the entry argument.
All the entries in your project are listed with their jsxPath after compilation, in build/resources/main/assets/react4xp/entries.json.


2: Below react4xp/

If you just want to keep your react components out of the regular XP file structure in site/ and be independent of the structure of Parts, Pages etc, the folder src/main/resources/react4xp/ is meant for that. Here’s how (assuming you’re using the starter or generally following the recommended react4xp setup pattern):

Open react4xp.properties in the project root, and look for the property entryDirs. This is a (comma-separated) list of folder names relative to the react4xp/ folder. React4xp comes with a built-in suggestion here: entryDirs = entries. This means that all .jsx (and .js and .es6) source files below src/main/resources/react4xp/entries will become entries: react components available to react4xp.

They will get a jsxPath relative to the closest entryDirs folder.

So for example if entryDirs = entries, then the closest entryDirs folder is src/main/resources/react4xp/entries, and any XP controller can render src/main/resources/react4xp/entries/subFolder/myEntry.jsx like this:

React4xp.render(
    "subFolder/myEntry",
    props,
    request,
    options
);
Under the site/ folder, entry source files must have the extension .jsx. This is because regular XP source files can have .js and .es6 extensions, and must be separated since the compilation and handling is very different. However, under the entryDirs folder(s), entries can have .js and .es6 extensions too!
React4xp doesn’t currently separate between different entryDirs, they behave as one. So if entryDirs = entries,moreEntries then react4xp/entries/foo/bar.jsx and react4xp/moreEntries/foo/bar.jsx will get the same jsxPath: "foo/bar". Beware of namespace collisions; you won’t be able to refer to both.


3: Anywhere else

The entryDirs are paths relative to src/main/resources/react4xp/, so just use relative entryDirs if you need entries outside of that.

For example, say you’ve added an NPM package externalComponents with react components in a comps subfolder, and you want to use them as entries. Simply add it to entryDirs:

react4xp.properties
entryDirs=entries,../../../../../node_modules/externalComponents/comps

(Or replace entries if you’re not using it, of course)


Further reading

If you want a deeper dive into details before moving on, here’s more about entries and the jsxPaths that point react4xp to them.


Okay, next example lessons!



Contents