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. Geppetto 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. Geppetto OSB application

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

geppetto-hm: Patienthm.org, portal and atlas of all Patient HM imaging data entirely built as a Geppetto application. Geppetto HM application - MRI Geppetto 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. Geppetto 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:

• Source Setup on OSX and Linux or Source Setup on Windows
• Instructions for setting up Geppetto on Eclipse Neon

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¶

Clone geppetto-client inside geppetto-application, then change package.json in geppetto-application as follow

// package.json
"devDependencies": {
    "@geppettoengine/geppetto-client": "file:./geppetto-client"
  },

Then run 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.

NOTE: remember to restore geppetto-client to the right version before pushing your changes.

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.