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.
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
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>
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 |
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.
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)
}
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.
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>
Last modified 3yr ago