JavaScript Modules Reference Documentation

May 25, 2024

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. You can find more information about this file here: https://academy.jahia.com/documentation/jahia/jahia-8/developer/module-development/understanding-jahia-modules
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 overriding Jahia’s automatic content editor form generation. You can learn more about the capabilities and how to use these configurations here: https://academy.jahia.com/documentation/jahia/jahia-8/developer/extending-and-customizing-jahia-ui/customizing-content-editor-forms/customizing-content-editor-forms
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: https://academy.jahia.com/documentation/jahia/jahia-8/developer/leveraging-jahia-backend-capabilities/creating-rules-and-listeners#addingrules-in-a-module
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. For more information about these, please refer to this resource: https://academy.jahia.com/documentation/jahia/jahia-8/developer/module-development/migration-scripts
settings/graphql-extension.sdl Experimental: SDL GraphQL extensions. See https://academy.jahia.com/documentation/jahia/jahia-8/developer/working-with-our-apis/graphql-api/simplify-your-graphql-api-with-sdl for more information
settings/jexperience Experimental: jCustomer custom objects. See https://academy.jahia.com/documentation/jexperience/jexperience-2.x-and-3.x/developer/jexperience-jahia/deploying-unomijcustomer-objects-from-jahia-modules for more information.

 

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