Creating a new module
Using the Jahia Studio to create a new project
The easiest way to create a new module is simply to create it using the Jahia Studio. This allows you to create and modify module or template projects directly from the Jahia server development environment. It will by default use the OSGi packaging and all you will have to do is simply customize it for your needs.
Using a Maven Archetype
We provide a Maven archetype to get started quickly with a new project. The Maven Archetype is also used internally by the Jahia Studio to initialize a new project. The steps below guide you through the process of creating a new project.
- Create a new project using a Maven Archetype:
mvn archetype:generate -Dfilter=org.jahia.archetypes:
- Select the required archetype, e.g.:
2: remote -> org.jahia.archetypes:jahia-module-archetype (Archetype for creating a new module project to be run on a Jahia server)
- Chose the latest archetype version available from the list
- Enter project metadata and confirm
- Change into project directory and build using:
mvn clean install
You can then open the Maven project in your favorite IDE and start building your Jahia OSGi module.
From scratch
First and foremost, if you’re ok using the Jahia Modules parent project, it will automatically configure both the Felix Maven Bundle Plugin and Jahia Maven Plugin to use defaults that make sense for most projects. To do so simply set as a parent to your Maven project:
<parent>
<artifactId>jahia-modules</artifactId>
<groupId>org.jahia.modules</groupId>
<version>8.0.0.0</version>
<relativePath/>
</parent>
If you prefer not to use Jahia module parent project, you will have to setup the plugins yourself, as explained here. To build an OSGi project, it is recommended to use the Felix Maven Bundle Plugin to help with the basic packaging. This is fairly easy to setup. First change the project’s packaging to bundle:
<packaging>bundle</packaging>
Then configure and add the plugin to the project:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-Name>${project.name}</Bundle-Name>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
<Bundle-Category>jahia-module</Bundle-Category>
<Implementation-Title>${project.name}</Implementation-Title>
<Implementation-Version>${project.version}</Implementation-Version>
<Implementation-Vendor>${project.organization.name}</Implementation-Vendor>
<Implementation-URL>${project.organization.url}</Implementation-URL>
<Specification-Title>${project.name}</Specification-Title>
<Specification-Version>${project.version}</Specification-Version>
<Specification-Vendor>${project.organization.name}</Specification-Vendor>
<!-- Jahia manifest attributes -->
<Jahia-Depends>default</Jahia-Depends>
<Jahia-Module-Type>module</Jahia-Module-Type>
<Jahia-Root-Folder>${project.artifactId}</Jahia-Root-Folder>
<Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
<Jahia-Static-Resources>/css,/icons,/images,/img,/javascript</Jahia-Static-Resources>
<Export-Package></Export-Package>
This is the default minimal configuration for building a Jahia OSGi module bundle.
However, there are a few things that the Felix Bundle Maven plugin cannot do, it cannot scan in non-Java resources for package uses such as:
- JSPs
- Taglibs
- Groovy files
- Spring descriptors
- Content definitions
- Content import files
Fortunately, we provide a goal in the Jahia Maven Plugin that will integrate with the Felix Bundle plugin that will scan all the standard Jahia module resources for you and build the required import package statements in the Felix Bundle plugin configuration.
Here is an example of setting up the Jahia Maven Plugin to scan for dependencies:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-Name>${project.name}</Bundle-Name>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
<Bundle-Category>jahia-module</Bundle-Category>
<Implementation-Title>${project.name}</Implementation-Title>
<Implementation-Version>${project.version}</Implementation-Version>
<Implementation-Vendor>${project.organization.name}</Implementation-Vendor>
<Implementation-URL>${project.organization.url}</Implementation-URL>
<Specification-Title>${project.name}</Specification-Title>
<Specification-Version>${project.version}</Specification-Version>
<Specification-Vendor>${project.organization.name}</Specification-Vendor>
<!-- Jahia manifest attributes -->
<Jahia-Depends>default</Jahia-Depends>
<Jahia-Module-Type>module</Jahia-Module-Type>
<Jahia-Root-Folder>${project.artifactId}</Jahia-Root-Folder>
<Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
<Jahia-Static-Resources>/css,/icons,/images,/img,/javascript</Jahia-Static-Resources>
<Export-Package></Export-Package>
<!-- uncomment if you also configure the Jahia Maven plugin jahia:dependencies goal
<Import-Package>*,${jahia.plugin.projectPackageImport}</Import-Package>
<Provide-Capability>${jahia.plugin.providedNodeTypes}</Provide-Capability>
<Require-Capability>${jahia.plugin.requiredNodeTypes}</Require-Capability>
-->
<Embed-Dependency>*; scope=compile; type=!pom;
inline=true</Embed-Dependency>
<Embed-Transitive>true</Embed-Transitive>
<_removeheaders>
Include-Resource,
Private-Package,
Embed-Dependency,
Embed-Transitive
</_removeheaders>
</instructions>
<archive>
<addMavenDescriptor>false</addMavenDescriptor>
</archive>
</configuration>
</plugin>
The plugin will generate the value for the property jahia.plugin.projectPackageImport that was already inserted in the Felix Maven Bundle Plugin configuration we had previously setup. Now the project is ready for building, which you can simply do using:
mvn clean install
Note, please, if your module uses node type or mixin definitions from another module, it is recommended to explicitly define the dependency between modules.
OSGi enables you to hot deploy packaged modules at runtime. Deploy-free coding builds on top of OSGi's capabilities and makes it possible to use changes made in file's source code without needing any redeployment. Deploy-free coding only requires an initial deployment using Jahia's Maven plugin.
Using deploy-free coding
- Create your module’s source code project.
- Compile and deploy it to your Jahia server that must be on the same file system as your project. The initial deployment “links” source code with Jahia server. Note that the file system could also be a network shared file system.
- Modify static resources directly in your source code. Jahia will pick up the changes directly from the source. No deployment is needed.
How deploy-free coding works
When building the project, the Jahia Maven Plugin will add a special MANIFEST.MF
header that points to the source code location with an absolute path. This is configured in the Felix Maven Bundle plugin by the following line:
<Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
Upon generation of the MANIFEST.MF
inside the JAR, it will look something like this:
Jahia-Source-Folders: /home/jahia/modules/assets
When a request comes in to a /modules/assets URL, Jahia will use the Jahia-Source-Folders manifest header (if present) to look for the source code of the project. If it is present, it will try to access the requested resource directly from the source folder instead of using the contents of the bundle. There are some limitations. Not all files can be directly used as some require compilation or internal caches that may interfere with the proper detection of file modifications. Here is a list of resource types that are supported with deploy-free coding:
- JSP
- HTML
- Images
- CSS
- Javascript
- Velocity
- Other static file types such as documents and text files
The following resources types are not supported:
- Groovy files (due to the internal Groovy engine class cache)
- Java classes
- Java libraries
Of course, for the file types that don’t work with deploy-free coding, you can still hot deploy them using OSGi bundle redeployment. So, for those file types the deployment life cycle is a little longer but still much faster than in previous versions of Jahia.
Releasing modules
When releasing modules, it is recommended that you remove the Jahia-Source-Folders configuration attribute from the Felix Maven Bundle plugin configuration. This is just to avoid any potential lookups in case the source folders also exist on the server. It will also prevent unnecessary file lookups.