Creating a module

A JHipster module is a Yeoman generator that is composed with a specific JHipster sub-generator to inherit some of the common functionality from JHipster. A JHipster module can also register itself to act as a hook from the JHipster generator.

JHipster modules are listed on the JHipster marketplace.

This allows to create third-party generators that have access to the JHipster variables and functions, and act like standard JHipster sub-generators.
The hook mechanism invokes third-party generators before and after app generation and entity generation.

Example

The JHipster Fortune module generates a “fortune cookie” page in a JHipster-generated application.

It is our sample module that showcases how you can use JHipster’s variables and functions in order to create your own generator.

Or, you can use the JHipster module generator to help you to initialize your module.

Basic rules for a JHipster module

A JHipster module:

is an NPM package, and is a Yeoman generator.
follows an extension of the Yeoman rules listed at http://yeoman.io/generators/ and can be installed, used and updated using the “yo” command. Instead of being prefixed by “generator-“, it is prefixed by “generator-jhipster-“, and instead of having just the “yeoman-generator” keyword, it must have 2 keywords, “yeoman-generator” and “jhipster-module”.
A JHipster module registering as a hook should not call process.exit in its generators being hooked.

Composability

A JHipster module uses the new “composability” feature from Yeoman, described at http://yeoman.io/authoring/composability.html to have access to JHipster’s variables and functions.

For this, it composes with the “jhipster:modules” sub generator:

compose: function() {
    this.composeWith('jhipster:modules', {
        options: {
            jhipsterVar: jhipsterVar,
            jhipsterFunc: jhipsterFunc
        }
    });
},

Hooks

JHipster will call certain hooks before and after some of its tasks, currently available and planned tasks are listed below.

Post Entity creation hook
Pre Entity creation hook [planned]
Post App creation hook [planned]
Pre App creation hook [planned]

JHipster module generator now has option to generate this.
A JHipster module can register to act as a hook when its main generator is run by the end user. You need to call the registerModule method available in jhipsterFunc from your main (app) generator to register as hook, you need to pass the below parameters in the method as below

jhipsterFunc.registerModule(npmPackageName, hookFor, hookType[, callbackSubGenerator[, description]])

npmPackageName npm package name of the generator. e.g: jhipster-generator-fortune
hookFor which Jhipster hook from above this should be registered to ( values must be entity or app)
hookType where to hook this at the generator stage ( values must be pre or post)
callbackSubGenerator [optional] sub generator to invoke, if this is not given the module’s main (app) generator will be called, e.g: bar or foo generator
description [optional] description of the generator, if this is not given we will generate a default based on the npm name given

Variables available (source here)

Global variables:

baseName: the name of the application
packageName: the Java package name
angularAppName: the AngularJS application name
javaDir: the directory for the Java application, including the package folders
resourceDir: the directory containing the Java resources (always src/main/resources)
webappDir: the directory containing the Web application (always src/main/webapp)

And all the variables from the JHipster .yo-rc.json file:

authenticationType: the type of authentication
hibernateCache: the Hibernate 2nd level cache
clusteredHttpSession: whether a clustered HTTP session is used
websocket: whether WebSockets are used
databaseType: the type of database used
devDatabaseType: the database used in “dev” mode
prodDatabaseType: the database used in “prod” mode
searchEngine: whether a search engine is used
useSass: if Sass is used for CSS pre-processing
buildTool: the Java build tool
frontendBuilder: the front-end (JavaScript/CSS/HTML) build tool
enableTranslation: if translations are enabled
enableSocialSignIn: if social login is enabled
testFrameworks: an array of the test frameworks selected

Functions available (source here)

addJavaScriptToIndex: add a JavaScript file to the index.html
addMessageformatLocaleToIndex: add a message format locale (for i18n)
addElementToMenu: add an entry in the navigation menu
addEntityToMenu: add an entity in the entity navigation sub-menu
addElementToAdminMenu: add an entry in the admin navigation sub-menu
addElementTranslationKey: add a new translation key in the global.json file
addEntityTranslationKey: add a new translation key for an entity in the global.json file
addAdminElementTranslationKey: add a new translation key for an admin sub-menu in the global.json file
addGlobalTranslationKey: add a new translation key in the global.json file
addTranslationKeyToAllLanguages: add a new translation key for all installed languages using methods addElementTranslationKey, addEntityTranslationKey, addAdminElementTranslationKey
getAllSupportedLanguages: get the list of languages supported by Jhipster
getAllInstalledLanguages: get the list of languages installed by current application
addChangelogToLiquibase: add a new changelog in the Liquibase master.xml file
addColumnToLiquibaseEntityChangeset: add new columns to the Liquibase changelog for an entity
dateFormatForLiquibase: creates a new timestamp to be used by a Liquibase changelog
copyI18nFilesByName: copy i18n files
addMavenDependency: add a new maven dependency in the pom.xmlfile
addMavenPlugin: add a new maven plugin in the pom.xml file
addGradleDependency: add a new gradle dependency
addGradlePlugin: add a new gradle plugin
applyFromGradleScript: apply script from another gradle file
addBowerDependency: add a new package in the bower.json file
addBowerOverride: add an override configuration in the bower.json file
addAngularJsModule: add a new module in the app.js file
addAngularJsConfig: add a new config in the app.js file
addAngularJsInterceptor : register an AngularJS interceptor in the app.js file
addMainCSSStyle: add a new style in the main.css file
addMainSCSSStyle: add a new style in the main.scss file
copyTemplate: copy a template from source to a destination after stripping any translation content when translation is disabled
copyHtml: short hand method for copyTemplate which is defaulted to action stripHtml
copyJs: short hand method for copyTemplate which is defaulted to action stripJs
rewriteFile: add the given content above a specific custom needle in a file
replaceContent: replace the given content for a specific pattern/regex in a file
registerModule: register to act as a hook from app or entity generator
updateEntityConfig: update the json configuration file for an entity with given key and value
getModuleHooks: get the array of all registered hooks for the application

Registering a module to the JHipster marketplace

To have your module available in the JHipster marketplace, you need to make sure you have the 2 keyword yeoman-generator and jhipster-module in your published npm package.json.
If you find any entry in the marketplace which is not a JHipster module, you can help to blacklist it by adding it to the blacklistedModules section of the modules-config.json file by doing a Pull Request to the jhipster/jhipster.github.io project.

Your module will become “verified” if the JHipster team verifies it.

Once you publish your module to NPM, your module will become available in our marketplace.