JavaScript Modules Reference Documentation

This section contains reference information about the different types of libraries and objects available to JavaScript module developers.

The JavaScript @jahia/js-server-core library

This library contains all the functions and React components that are critical to implementing JavaScript modules. The reference HTML documentation may be found here: https://jahia.github.io/js-server-core/

Here, we will provide a quick overview of some of the functions and components available in the library.

The useServerContext hook

The useServerContext hook provides access to the most relevant Jahia objects for the currently executing request, such as the currentNode being rendered, the current renderContext (which contains the HTTP request and response), and other contact information. Let’s look at a quick example of how this hook can be used by using a view for a type npmExample:testUrlParameters that retrieves a URL parameter from the HTTP request using the Java HTTP Servlet API exposed by the renderContext.getRequest() call :

import React from 'react';
import { useServerContext } from '@jahia/js-server-core';

export const TestUrlParameters = () => {
    const {renderContext} = useServerContext();
    const urlParam = renderContext.getRequest().getParameter('test');
    return (
        <>
            <h3>Url parameter test</h3>
            <div>{urlParam}</div>
        </>
    );
}

TestUrlParameters.jahiaComponent = {
    nodeType: 'npmExample:testUrlParameters',
    name: 'default',
    displayName: 'test url parameters',
    componentType: 'view'
}

The useServerContext returns an object that contains different fields, which are defined by the following structure:

/**
 * A context object that gives access to the underlying Jahia Java objects that are part of the current rendering context
 */
export interface ServerContext {
    /**
     * Jahia's rendering context, it provides access to all kinds of context information, such as the current request, response, user, mode, mainResource and more
     */
    renderContext : RenderContext;
    /**
     * The current resource being rendered, which is a combination of the current node and its template/view information
     */
    currentResource : Resource;
    /**
     * The current JCR node being rendered
     */
    currentNode : JCRNodeWrapper;
    /**
     * The main JCR node being rendered, which is the root node of the current page
     */
    mainNode : JCRNodeWrapper;
    /**
     * The OSGi bundle key of the current module being rendered
     */
    bundleKey : string;
}

You can find all the relevant HTML documentation about these structures and all the sub-objects in the reference HTML documentation for the @jahia/js-server-core library and, more specifically, for the ServerContext object here:

https://jahia.github.io/js-server-core/interfaces/types_manual_servercontext.ServerContext.html

Java helper objects in @jahia/js-server-core

The @jahia/js-server-core library also exposes some Java classes that provide helper functions that help JavaScript developers access services such as (OSGi) module configuration properties, the Jahia JavaScript registry, Jahia’s rendering service, and Jahia’s GraphQL API.

These classes are accessible through the top-level server object. Here is an example of using that object to access OSGi module configuration properties:

import React from 'react';
import {server} from '@jahia/js-server-core';

export const TestConfig = () => {
    const configValues = server.config.getConfigValues('org.jahia.modules.test');
    return (
        <>
            <p>configValues.configKey1={configValues.configKey1}</p>
            <p>configValues.configKey2={configValues.configKey2}</p>
        </>
    )
}

TestConfig.jahiaComponent = {
    nodeType: 'npmExample:testJConfig',
    name: 'react',
    displayName: 'test jConfig (react)',
    componentType: 'view'
}

In the above example we import the server object from the @jahia/js-server-core library and access its config field that is actually implemented using a Java class that gives us access to functions to access module configuration.

Here’s a quick overview of all the Java objects exposed by the server object:

import {ConfigHelper, GQLHelper, OSGiHelper, RegistryHelper, RenderHelper} from 'org.jahia.modules.npm.modules.engine.js.server';

/**
 * A set of helpers that provide common functionality provided by Jahia for Javascript server-side rendering
 */
export const server: {
    /**
     * This helper provides access to OSGi configuration
     */
    config: ConfigHelper,
    /**
     * This helper provides access Jahia's GraphQL API, to execute queries and mutations
     */
    gql: GQLHelper,
    /**
     * This helper provides access to OSGi bundle for resource loading and service access
     */
    osgi: OSGiHelper,
    /**
     * This helper provides access to Jahia's registry API, to register new UI objects or retrieving existing ones
     */
    registry: RegistryHelper,
    /**
     * This helper provides rendering functions such as registering page resources, adding cache dependencies or rendering components
     */
    render: RenderHelper
};

You can find the HTML documentation for this object here: https://jahia.github.io/js-server-core/variables/types_manual_server.server.html

From there you can access all the different functions that are available on the different helper Java classes and use them in your JavaScript modules.

JavaScript Modules Reference HTML Documentation

The complete HTML documentation for all the services, functions, and objects exposed by the @jahia/js-server-core project is available here:

https://jahia.github.io/js-server-core/

Project Folder Structure

Simple (basic) project structure

Here’s a very basic project structure that will be most common to most projects.

package.json: the JSON NPM package description
webpack.config.js: the Webpack configuration
images: module images
css: module static stylesheet files
locales: label translation files
src: the directory where all the source files are
definitions.cnd: the content type definition file
.env.example: the default example deployment configuration (see here)
Other folders: static asset folders

Complex (complete) project structure

In the following table, we give a much more detailed and exhaustive description of the possible contents of a project.

File/Folder	Description
`package.json`	NPM project descriptor
`webpack.config.js`	WebPack configuration
`definitions.cnd`	Content node type definitions
`import.xml`	A default JCR import file will be used to import the initial content required by the module.
`css`	Publicly accessible CSS
`images`	Publicly accessible images
`images/template-preview/template.png`	This image will be displayed when selecting the template set to use when creating a new site.
`icons`	Icons for the content types declared in the module. See this resource for more information.
`javascript`	Publicly accessible JavaScript
`src`	Top directory for all JavaScript source code
`src/client`	Top directory for all client-side JavaScript source code
`src/server`	Top directory for all server-side (SSR) JavaScript source code
`src/server/views/[nodeType]/[NodeTypeAndViewName].jsx`	For a given nodeType, the directory and file name structure are recommended. Example: src/server/views/event/EventDefault.jsx
`src/server/templates/page/[PageAndTemplateName].jsx`	For page templates. For a home page template, here is an example: src/server/templates/page/PageHome.jsx
`src/server/templates/[nodeType]/[NodeTypeAndTemplateName].jsx`	For content templates.
`src/server/components/[ComponentName].jsx`	React SSR generic reusable components. Example: src/server/components/Header.jsx, a reusable Header component.
`resources/[module-name]_[language_code].properties`	Java server-side resources bundle. Used to internationalize content node type definitions and other server resources. The `module_name` is the same as the name in the package.json/name property. The `language_code` is an ISO-compliant language code as defined here: https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html
`locales/[language_code].json`	JavaScript JSON resource bundles for internationalization. These are accessible to both the server-side and client-side JavaScript code. The language code is the same as defined for the Java resources.
`settings`	The settings folder may contain resources such as content editor form overrides, configurations, and more
`settings/configurations`	A directory containing module configuration files, either in properties (.cfg) or Yaml (.yml) format. These properties will then be accessible in JavaScript modules through the `server.config.*` helper functions
`settings/jahia-content-editor-forms`	Contains configurations for customizing / overriding Jahia’s automatic content editor form generation.
`settings/rules.drl`	A Jahia Drools rules definition file. These rules use the Drools language syntax to be able to react to events such as a node creation or a property change in the JCR. For more information, you can use this resource.
`settings/import.zip`	Experimental: An import ZIP file that can contain multiple XML files to be imported, such as content initial import (import.xml), permissions (permissions.xml), roles (roles.xml)
`settings/patches`	Experimental: Migrations scripts
`settings/graphql-extension.sdl`	Experimental: Schema Definition Language (SDL) GraphQL extensions.
`settings/jexperience`	Experimental: jCustomer custom objects.

Comparison with Java modules

The structure is not that different from that of Java modules. The following table highlights the main differences. All the other file locations are similar.

JavaScript Modules	Java Modules	Purpose
`package.json / webpack.config.js`	`pom.xml`	Project descriptor
`import.xml`	`META-INF/import.xml`	Initial content import
`definitions.cnd`	`META-INF/definitions.cnd`	Content type definitions
`settings/*`	`META-INF/*`	All other settings