= MOLGENIS Apps =
[[TOC()]]

Welcome to the MOLGENIS apps project. MOLGENIS apps is a suite of integrated biomedical research tools born from the MOLGENIS community.

== For researchers ==

Find more information at the app homepages:

* [wiki:AnimaldbStart animaldb] -- for tracking research animals
* [wiki:XgapStart xgap] -- for genotype and phenotype experiments
* [wiki:NgsStart ngs] -- LIMS and pipelines for illumina sequencing
* [wiki:MutationStart mutation] -- for rare diseases and mutations
* [wiki:ComputeStart compute] -- for bioinformatics computational workflows

== For developers ==

Developers can download all code as open source at:
http://www.molgenis.org/svn/molgenis_apps/trunk

The MOLGENIS apps project is structured as follows:
* [source:molgenis_apps/trunk/apps /apps] -- apps in the suite, one folder per app.
* [source:molgenis_apps/trunk/modules /modules] -- pieces of reusable software shared between apps, one folder per module
* [source:molgenis_apps/trunk/generated /generated] -- autogenerated code by MOLGENIS (svn:ignore), one folder for java, python, cpp, sql.
* [source:molgenis_apps/trunk/dist /dist] -- where all outputs of the build process are collected (svn:ignore)
* [source:molgenis_apps/trunk/WebContent /WebContent] -- images, style sheets and scripts to serve on the web 
* [source:molgenis_apps/trunk/build_xgap.xml /build_xyz.xml] -- script to automatically build a complete app from above (build_<name>.xml == apps/<name>)

== Getting started ==

We assume you use Eclipse and pre-installed MySQL and Tomcat as described [MolgenisOnWindows here].

Todo:
1. Checkout molgenis/trunk and molgenis_apps/trunk from http://www.molgenis.org/svn [[BR]]=> this will result in two project folders, molgenis and molgenis_apps respectively.
2. Go inside molgenis_apps and right-click on the build_...xml of your choice and choose 'run as...' => 'run as Ant' [[BR]] => this will result in all code being generated and assembled.
3. Right-click on molgenis_apps project and choose 'refresh' [[BR]] => this will make Eclipse refresh and show the source folders of your project.
4. Right-click on molgenis_apps project and choose 'run as' => 'run on server' [[br]] => if you choose Tomcat in the wizard you can get your app started.

Also see [http://dl.dropbox.com/u/1839500/molgenisappsbasics.mp4 this movie]

[[BIG TODO: database is now not automatically created. It would be great if this goes via user interface]].

== Description of all project elements ==

> We must decide what to do with plugin templates that are generated into handwritten/java. These are ignored by the build script, but can be useful if you have a new plugin. We could consider to make a special folder for this or something. And hopefully to make the generator check before it spits out the plugin (again and again).

=== build scripts ===
Each app can be build automatically by running {{{ant build_xyz.xml}}} or in eclipse, right-click and choose 'run as'->'Ant build'. 
For example: build_xgap.xml builds a runnable version of xgap. 

The build scripts provide the following standard methods:
* clean -- cleans the generated folders
* generate -- generates all code using MOLGENIS
* compile -- compile generated code and imported modules
* test -- run the test cases defined in this app + dependent modules
* update-eclipse -- update Eclipse to only show selected app + modules
* (todo) create-jar -- create a standalone executable jar of this app
* (todo) create-war -- create a mysql + tomcat deployable war of this app

At every change in SVN, hudson will run clean-generate-compile-test and sent emails if errors are found.




=== /apps ===
Apps are applications designed to be used by an end-user. For example: /apps/xgap. 

Each app is structured as follows: 
* root package org.molgenis.<appname> contains specific sources and resourses
* <appname>.properties file has settings for this app [move to build.xml?]
* <appname>.testng.xml files lists all tests for this app (see hudson)
* <appname>_ui.xml lists the user interface design for this app

Developers of apps have complete freedom to do what they want within their app as other apps will ignore any code in these folders.

=== /modules ===
Modules are bundles of code that are shared between two or more apps. For example: /modules/auth.

Each module is structured as follows:
* root package org.molgenis.<modulename> contains specific sources and resourses
* <modulename>.properties file has settings to setup a test molgenis for this module only (see hudson)
* <modulemame>.testng.xml files lists all tests for this module (see hudson)
* <modulename>_ui.xml lists a user interface design for this module; apps may choose to [ref] import this ui design into their application.

Developers of modules are required to:
* ensure stability of the modules by providing sufficient tests and stable programming interfaces. 
* mark yet unstable modules with a suffix as '-dev'. For example /modules/matrix-dev. 
* when changing an existing module copy it into a -dev version and develop on that until the code is stable before promoting it to stable
* monitor the tests of all dependent apps on hudson and fix or undo any problems they you may have caused.

=== /generated (svn:ignore) ===
This folder contains all program resources autogenerated by the build script.
Typically, there are:
* /java -- generated java
* /python -- generated python
* /cpp -- generated c++ code

NB: this folder is never committed to SVN (svn:ignore).
=== /WebContent ===
All resources for the web, such as images, css and javascript, can be stored in /WebContent. 
Each app or module will create subfolders. For example:

* /res -- contains resource files that are created by hand
  * /css -- contains css files
    * /xgap -- contains xgap specific css files
  * /img -- contains images
    * /xgap -- contains xgap specific css files
  * /scritps -- contains scripts.
    * /xgap -- contains xgap specific css files
* /generated-res -- contains generator produced resource files (svn:ignore).

=== /dist (svn:ignore) ===

This folder contains all resources produced by the build script.
This includes:

* /dist/classes -- all compiled class files and copy of *.property and *.ftl files
* /dist/test-output -- result of the tests
* /dist/javadoc -- generated javadoc for your app
* /dist/<name>.war -- generated war for deployment on tomcat and mysql
* /dist/<name>.jar -- generated jar for standalone running of the app

== Creating a new app ==

In order to create a new app you must:

1. create a new folder in /apps/<name>. This folder should contain:
  * package org.molgenis.<name>
  * <name>.properties file
 
2. create a new build script: build_<name>.xml. This file should contain:

{{{
!#xml
<project>
	<!-- this name is used to name the war file -->
	<property name="app_name" value="appname" />

	<!-- this holds all the settings for the generator -->
	<property name="app_properties" value="apps/${app_name}/org/molgenis/${app_name}/${app_name}.properties"/>
	
	<!-- this determines what additional modules should be loaded -->
	<path id="app.class.path">
		<pathelement location="apps/${app_name}" />
                <!-- below optional dependencies on modules -->
		<pathelement location="modules/datamodel" />
		<pathelement location="modules/auth" />
		<pathelement location="modules/pheno" />
		<pathelement location="modules/search" />	
	</path>

	<!-- below, import all tasks from build_common: clean, generate, compile, test, war, standalone-jar -->
	<import file="build_common.xml" />

</project>
}}}