Developing Apps in MOLGENIS

You can create add-on user interfaces using html+javascript. To be able to host your app inside MOLGENIS, you need to create an archive in a specific format. To get started right away, you can download an example archive here. Following paragraphs will explain in detail how to construct and configure your resources to make it a certified MOLGENIS app.

Archive structure

If you downloaded the example archive, you probably noticed that the structure of the archive is pretty straight forward.

|-- config.json
|-- index.html
|-- app-template.html
|-- js
    |-- example.js
|-- css
    |-- example.css

The index.html is your main entry point, and the contents will be interpreted and rendered by a FreeMarker engine. Relative to your index.html you can include js and css.

note: If you use absolute paths, MOLGENIS is unable to serve your resources properly

Example

The following example assumes we have a setup according to the tree structure shown in the previous paragraph.

index.html

<html>
  <head>
    <link href="css/example.css"/>
  </head>
  <body>
    <div class="container">
      <h1>This is an example of including resources with relative paths</h1>
    </div>
    <script src="js/example.js"></script>
  </body>
</html>

example.js

alert('this is a wonderful example')

example.css

.container {
    background: blue;
    height: 400px;
    width: 100%
}

For production usage

app-template.html

This file is needed by the target MOLGENIS-instance. It will be used to render the index.html for the production app.

<div id="app"></div>

Configuration

The config.json is a small configuration file that will tell MOLGENIS about your app. It contains the following parameters

Parameter
type
mandatory
Description

label

string

yes

The label used to name your app in the app manager screen

description

string

yes

A description for your app. Useful for making your app more findable in the app manager

version

string

yes

The version of your app. Used to manage app version, updating etc etc..

apiDependency

string

yes

The version of the MOLGENIS REST api you used in your app. Can be used to give warnings about possible incompatibility with a specific version of MOLGENIS

name

string

yes

The name of the app. May not contain '/'

includeMenuAndFooter

boolean

yes

If you want MOLGENIS to serve your app with the standard header (with menu and polyfill), and footer, set this value to true

runtimeOptions

object

no

A map containing initial parameters you might want to give to your app on init

Example

The following example shows every possible configuration option currently available

config.json

{
	"label": "Example app",
	"description": "This is an example app",
	"version": "v1.0.0",
	"apiDependency": "v2",
	"name": "example",
	"includeMenuAndFooter": true,
	"runtimeOptions": {
		"language": "en"
	}
}

Note that you can not create a config.json on your root path of the project. It will not build anymore.

Available javascript variables

MOLGENIS deploys apps with a bit of system information inside a global variable to get your app up and running. These are described below.

window.__INITIAL_STATE__ = {
  baseUrl: '', // This is the root URL
  lng: '', // the language set by the system, allows you to implement i18n
  fallbackLng: '' // the fallback language set by the system, defaults to english (en)
}

App resource caching

To enable caching of your resources, ensure your resource files have a hash code included in their file names. So instead of example.js, use example.0943Ajd09834fd.js.

Build tools like webpack already generate your source files with a hash code included in the file name.

Using webpack for rapid app prototyping

To use webpack in rapid prototyping of your MOLGENIS apps, use the standard webpack template and make some small tweaks to make it a build -> compress -> upload workflow.

First you need to install 2 plugins:

yarn --dev add zip-webpack-plugin@2.0.0
yarn --dev add generate-json-webpack-plugin

Make sure that you set the following two parameters in your production config.

In config/index.js

const packageJson = require('../package')

module.exports = {
  // ...
  build: {
    // ...
    assetsSubDirectory: '',
    assetsPublicPath: '/plugin/app/' + packageJson.name,
    // ...
  }
}

In build/webpack.prod.conf.js

plugins: [

  ...  

  new HtmlWebpackPlugin({
    filename: process.env.NODE_ENV === 'testing'
      ? 'index.html'
      : config.build.index,
    template: 'app-template.html',
    inject: true,
    minify: {
      removeComments: true,
      collapseWhitespace: true,
      removeAttributeQuotes: true
      // more options:
      // https://github.com/kangax/html-minifier#options-quick-reference
    },
    // necessary to consistently work with multiple chunks via CommonsChunkPlugin
    chunksSortMode: 'dependency'
  }),

  ...   

  new GenerateJsonPlugin('config.json', {
      name: packageJson.name,
      label: packageJson.name,
      description: packageJson.description,
      version: packageJson.version,
      apiDependency: "v2",
      includeMenuAndFooter: true,
      runtimeOptions: {
        language: "en"
      }
    }),

    // copy custom static assets
    new CopyWebpackPlugin([
      {
        from: path.resolve(__dirname, '../static'),
        to: config.build.assetsSubDirectory,
        ignore: ['.*']
      }
    ]),

    new ZipPlugin({
      filename: packageJson.name + '.zip'
    })
  ]

These settings will ensure that your compiled resources are already in the correct file structure, and references to your resources are relative.

app-template.html

This file is needed by the target MOLGENIS-instance. It will be used to render the index.html for the production app.

<div id="app"></div>
PreviousDeveloping frontend in MOLGENISNextUsing an IDE (Intellij)

Last updated