How Do I create My Own Geppetto Application?

Creating your own Geppetto application is very simple, as simple as cloning geppetto-application repository (to use it as a template) and then modifying ./components/Application.js with your custom code. You might want to create a GitHub repository to contain your files and then replace the content of the folder org.geppetto.frontend/scr/main/webapp with the content of your repository. The default Geppetto application repository contains also other files that might be of interest:

  • The .eslintrc.js file will allow you to configure linting rules on top of the default rules we are already enforcing for the default Geppetto applications. Check the default linting rules we are inheriting from geppetto-client repository here.
  • In GeppettoConfiguration.json file you will have to specify how are you planning to use the Geppetto application. Is it going to be embedded in an iframe? are you planning to use a context path? Would you like to use a different color scheme for built-in Geppetto components?
  • The package.json file is installing NPM geppetto-client package (which contains all the different npm packages required for the default Geppetto application to work). But you can include extra npm packages there that you are planning to use in your custom Geppetto application.
  • Finally webpack.config.js controls the way your custom Geppetto application will be build.

Coming back to the main file (./components/Application.js), you can define there your own js functions as needed and interact with the Geppetto API to add components that Geppetto makes available. For example, the following code adds the 3D canvas component to the background element with id=”sim” (a commonly used component conveniently provided by Geppetto):

//Canvas initialization
<div id="sim">
    <Canvas
        id="CanvasContainer"
        name={"Canvas"}
        ref="canvasRef"
    />
</div>

Or as another example, the code below is injecting a logo component to the element with id=”geppettologo” (again, conveniently provided by Geppetto; it appears in the top right) and then injecting a Link button component, that links to the source code on GitHub, while also specifying a position for this element:

<Logo
    logo='gpt-gpt_logo'
    id="geppettologo"
/>

<div id="github-logo">
    <LinkButton
        left={41}
        top={390}
        icon='fa fa-github' 
        url='https://github.com/openworm/org.geppetto'
    />
</div>

NOTE: Since Geppetto exposes a dependency to react.js (much of its internals use this framework), we highly encourage you to write your custom code as React components. But nothing will stop you from adding DOM elements with jQuery (or vanilla js). If a DOM element is not specified, the component will be added in a floating window (also known as a “Geppetto widget”).

Geppetto Application Examples

You can achieve virtually any look & feel with a Geppetto application. We provide below some examples of UIs built as Geppetto applications (code also linked if available as open source software):

geppetto-default: the default Geppetto application we know and love, available on live.geppetto.org. _images/default.pngGeppetto default application

geppetto-osb: Geppetto application for Open Source Brain, a repository of open source computational neuroscience models that features a Geppetto based 3D viewer of morphologies and simulation environment. _images/osb.pngGeppetto OSB application

geppetto-vfb: Geppetto application for Virtual Fly Brain, a reference for drosopohila neuroanatomy and ontology. _images/vfb.pngGeppetto VFB application

geppetto-hm: Patienthm.org, portal and atlas of all Patient HM imaging data entirely built as a Geppetto application. _images/hm1.pngGeppetto HM application - MRI _images/hm2.pngGeppetto HM application - Big image viewer

geppetto-netpyne: Geppetto application for NetPyNE, a python package to facilitate the development, parallel simulation and analysis of biological neuronal networks using the NEURON simulator. _images/netpyne.pngGeppetto NetPyNE application

How to deploy a Geppetto application in my Eclipse environment

In this section we will show you how to deploy a custom Geppetto application to your local Geppetto environment. The below assumes that you already have your Geppetto and Eclipse environment configured locally. If that is not the case, see the following pages:

First of all, starting from our home folder we begin by cloning the custom Geppetto application repository into the Geppetto Frontend’s webapp folder, located in the geppetto-sources folder.

cd geppetto-sources
cd org.geppetto.frontend/src/main
git clone https://github.com/MyGitHubUser/geppetto-custom-application webapp

Once done we will need to update our org.geppetto.frontend project to take into account the changes made. We can start by right clicking on the bundle org.geppetto.frontend->Maven->Update Project. Then, we right click again on org.geppetto.frontend->Run As->Maven Install. This will re-build our bundle and npm will automatically redeploy the frontend to the Virgo server’s folder so that we can use the new application. Once the server finishes starting all the bundles, we can open the Geppetto frontend homepage with our browser and see our loaded application working.

Geppetto Build

  • Geppetto Configuration
  • Maven Profiles
  • Development Build
  • Production Build

Geppetto Configuration

Geppetto lets you configure your deployment with a set of parameters that are defined in org.geppetto.frontend/src/main/webapp/GeppettoConfiguration.json. This file exposes the following parameters:

  • contextPath: The context path is the prefix of the URL path to access Geppetto. Typically contextPath is “org.geppetto.frontend” for development and “/” for production. Assuming a local development environment with contextPath “org.geppetto.frontend”, you will access Geppetto at localhost: localhost:8080/org.geppetto.frontend

  • useSsl: If true, Geppetto will be configured to use https instead of http.

  • embedded: Geppetto is configured to work as an embedded instance inside an iframe. This means CORS will be enabled, a postMessage channel will be available for the main frame, some layout and href calls customization, etc.

  • embbedderURL: If running in embedded mode, this specifies the URL of the main frame container. For security reasons Geppetto will only accept cross-origin calls from this URL.

  • noTest: If true, tests are suppressed during the build process. If false, tests will be run as part of the build process.

  • themes: Defines a Geppetto “theme”. So far, we only expose a few parameters defining colours. Below you can find a list of the parameters exposed that can be overridden by your custom theme file:

    @primary_color: #fc6320;
    @secondary_color: #fc401a;
    @background_color_body_0: #141a1e;
    @background_color_body_50: #5c6268;
    @background_color_body_73: #60666d;
    @background_color_body_100: #515359;
    @background_color_widget: rgb(66, 59, 59);
    

In order to implement a new theme, a less file needs to be created defining some or all these parameters and the theme needs to be specified in the themes and set to true.

This is how the default (and recommended for development environments) GeppettoConfiguration.json looks:

{
  "_README" : "http://docs.geppetto.org/en/latest/build.html",
  "contextPath": "org.geppetto.frontend",
  "useSsl": false,
  "embedded": false,
  "embedderURL": ["/"],
  "rootRedirect":"",
  "noTest": false,
  "themes": "css/colors",
  "properties": {
    "title" : "geppetto",
    "description": "Geppetto is an open-source platform to build web-based tools to visualize and simulate neuroscience data and models. This is a live deployment to showcase its functionalities.",
    "type": "website",
    "url": "http://live.geppetto.org",
    "icon" :"geppetto/style/favicon.png",
    "image": "http://www.geppetto.org/images/logo.png"
  } 
}

Maven Profiles

The Java based backend of Geppetto is built using Maven, with the “mvn -Dhttps.protocols=TLSv1.2 install” command. Maven allows for different build steps to be specified for different environments, and Geppetto provides a development and a production profile (see below for how to trigger different builds). Builds can be triggered at the root from the org.geppetto bundle and parameters will be propagated to the children (child bundles are defined in org.geppetto/pom.xml). Maven builds can also be triggered for individual bundles from the specific bundle root that needs to be built.

Building for development

mvn -Dhttps.protocols=TLSv1.2 install

When the command “mvn -Dhttps.protocols=TLSv1.2 install” is executed, none of the optimization tasks are run. When doing development, it is not necessary to run the production build unless you wish to simulate a production environment.

The default Geppetto application repository within org.geppetto.frontend relies on geppetto-client npm package to bring the Geppetto build-in components to the client. If you neeed a development version of geppetto-client, please follow these steps:

  1. Go to org.geppetto.frontend/src/main/webapp.
  2. Clone geppetto-client git clone https://github.com/openworm/geppetto-client.git.
  3. cd geppetto-client.
  4. Install the npm packages required by geppetto-client npm install.
  5. Create a symlink from geppetto-client folder to a global folder npm link.
  6. Go back to org.geppetto/ , you could run cd ../../../../org.geppetto/.
  7. Run mvn -Dhttps.protocols=TLSv1.2 install in org.geppetto (as usual).
  8. Move to the folder utilities/source_setup and copy the files to virgo server cd utilities/source_setup; python update_server.py (as usual).
  9. Go to org.geppetto.frontend/src/main/webapp with cd ../../../org.geppetto.frontend/src/main/webapp
  10. Create a symlink from the global geppetto-client folder to Geppetto application npm link @geppettoengine/geppetto-client.
  11. Start virgo virgo startup.sh going back to the folder where the server has been installed, using the script within bin/startup.sh (as usual).
  12. From the webapp folder run npm start.
  13. Now changes to /org.geppetto.frontend/src/main/webapp/geppetto-client files will automatically update localhost:8081/org.geppetto.frontend

NOTE: up to npm version 6.9.0, the command npm install removes all symlinks to packages from the node_module folder. This behaviour will be removed in npm@7+ but until then, the maven command:

mvn -Dhttps.protocols=TLSv1.2 install,

will remove your symlink to geppetto-client from org.geppetto.frontend/src/main/webapp.

Building for production

mvn -Dhttps.protocols=TLSv1.2 install -P master

Some optimization tasks are applied to the org.geppetto.frontend bundle to optimise performance and security. To see the difference between profiles have a look at org.geppetto.frontend/src/main/webapp/package.json.

Overriding Geppetto Parameters with mvn

Geppetto configuration settings can be overwritten by passing the parameters to the “mvn -Dhttps.protocols=TLSv1.2 install” command. An example follows:

mvn -Dhttps.protocols=TLSv1.2 install "-DcontextPath=theearth" "-DuseSsl=true" "-Dembedded=true" "-DembedderURL=universe,milkyway"

NOTES

At this point when you run:

npm run build,

in Geppetto application to generate the bundle files, we are also bundling files from geppetto-client package. In the future, we will completely decouple gepetto-client from geppetto-application so that geppetto-client can be seen as a truly independent and ready to use npm package.