{{{
#!docbook
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<book lang="en">
  <bookinfo>
    <title>MOLGENIS 3.0.3 manual</title>

    <subtitle>How to quickly generate your own biodatabase using the MOLGENIS
    suite.</subtitle>

    <author>
      <affiliation>
        <orgname>University of Groningen</orgname>
      </affiliation>

      <firstname>Morris</firstname>

      <surname>Swertz et al</surname>

      <email>molgenis-users@lists.sourceforge.net</email>
    </author>

    <copyright>
      <year>2001-2008</year>
    </copyright>

    <!-- <revhistory>
            <revision>
                <revnumber>0.1</revnumber>
                <date>2008-09-05</date>
            </revision>
        </revhistory>-->

    <abstract>
      <para>MOLGENIS is the 'holistic' model-driven database platform that
      allows you to store and query any (biological) data you want .... as
      long as you tell it in a model how your data looks like ;-) This manual
      helps you to get started.</para>

      <para>With MOLGENIS you can compactly model the structure of your data,
      and the way you want to see it on screen, using a simple XML language.
      At the push of a button, the MOLGENIS generators automatically produce
      all the program code of your desired software instance. With each
      MOLGENIS instance you get 'for free' : <itemizedlist>
          <listitem>
            <para>a generated user interface to upload and query data in a web
            browser;</para>
          </listitem>

          <listitem>
            <para>a <ulink url="http://www.r-project.org">
            R-project</ulink>interface to connect your favorite statistical
            tools;</para>
          </listitem>

          <listitem>
            <para>the web service interface to integrate e.g. NCBI, Ensembl,
            KEGG, using <ulink
            url="http://taverna.sourceforge.net">Taverna</ulink>;</para>
          </listitem>

          <listitem>
            <para>and a plug-in mechanism so you can easily add your custom
            programs to the generated software.</para>
          </listitem>
        </itemizedlist> And if you don't like what you see, or if your
      experiments change, you can quickly re-run the generator to accomodate.
      Thus in quick iterations you can produce the databases biologists want
      to have.</para>

      <para>MOLGENIS has been born from the demanding domain of life sciences
      (although it is not limited to that domain). Currently, MOLGENIS has
      been succesfull for microarray experiments, proteomics experiments,
      genetical genomics experiments, animal observations and first initatives
      have been started towards biobanking. MOLGENIS is open-source and free
      for use by academics, we only ask that you cite our work:</para>

      <para><itemizedlist>
          <listitem>
            <para>Swertz &amp; Jansen:<ulink
            url="http://www.ncbi.nlm.nih.gov/pubmed/17297480">Beyond
            standardization: dynamic software infrastructures for systems
            biology.</ulink> Nature Reviews Genetics 8: 235-243.</para>
          </listitem>

          <listitem>
            <para>Swertz et al: <ulink
            url="http://www.ncbi.nlm.nih.gov/pubmed/15059831">Molecular
            Genetics Information System (MOLGENIS) alternatives in developing
            local experimental genomics databases.</ulink> Bioinformatics 20:
            2075-83</para>
          </listitem>
        </itemizedlist></para>

      <para>We are happy to collaborate and help you generate interesting
      MOLGENIS instances for your research domain and co-author publications
      on these systems together. For commercial use of MOLGENIS we have a
      separate license.</para>
    </abstract>
  </bookinfo>

  <part>
    <title>Using the MOLGENIS generator</title>

    <chapter id="chapter.installation">
      <title>Getting started</title>

      <abstract>
        <para>This chapter describes what software and procedures are needed
        to get started using MOLGENIS. The next chapters explain you how to
        configure MOLGENIS to your needs.</para>
      </abstract>

      <sect1>
        <title>Install the necessary software (only once)</title>

        <para>MOLGENIS is known to run happily at Windows, Linux and Mac. To
        get going, download and install the following:</para>

        <procedure>
          <step>
            <para>Java 6 JDK <ulink
            url="http://java.sun.com/javase/downloads/">http://java.sun.com/javase/downloads/</ulink></para>

            <para>Just install with standard options.</para>
          </step>

          <step>
            <para>Tomcat &gt;=5 web server <ulink
            url="http://tomcat.apache.org/">http://tomcat.apache.org/</ulink></para>

            <para>Rember the root password you are asked!</para>

            <para>Don't run Tomcat as a service; we will start and stop it
            ourself.</para>
          </step>

          <step>
            <para>Mysql &gt;=5.1 database <ulink
            url="http://dev.mysql.com/downloads/mysql/5.1.html">http://dev.mysql.com/downloads/mysql/5.1.html
            </ulink></para>

            <para>During installation of the windows version you need to tick
            'innodb'.</para>

            <para><emphasis role="italic">Remember your root
            password!</emphasis></para>
          </step>

          <step>
            <para>Eclipse Integrated Development Environment <ulink
            url="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/
            </ulink></para>

            <para>You need to install the J2EE version (which allows you to
            start/stop tomcat)</para>
          </step>

          <step>
            <para>(Optional) MOLGENIS autogenerates documentation for your
            application. This includes a graphical representation your model
            in UML format. This requires GraphViz to work:</para>

            <para>Download and install graphviz from
            http://www.graphviz.org/Download.php</para>

            <para>Make sure your PATH is set to run 'dot.exe' from the
            commandline.</para>
          </step>

          <step>
            <para>The latest 'molgenis_workspace.zip' from <ulink
            url="http://molgenis.sourceforge.net">http://molgenis.sourceforge.net</ulink>
            and unzip</para>

            <para>Just download and unzip. A directory 'molgenis_workspace' is
            created.</para>
          </step>

          <step>
            <para>Create a database in mysql and give molgenis permission to
            populate it.</para>

            <para>Open mysql.exe as root user</para>

            <para><emphasis role="italic">Under windows in "C:\Program
            Files\MySQL Server 5.1\bin\mysql.exe - u root -p</emphasis></para>

            <para><emphasis role="italic">Remember your root password from
            step 3!</emphasis></para>

            <para>Type the following to create a database 'molgenis' and
            provide rights to the molgenis generator to change it using
            password 'molgenis': <programlisting><code>
create database molgenis; 
grant all privileges on molgenis.* to molgenis@localhost identified by 'molgenis'; 
flush privileges;
use molgenis; 
                            </code></programlisting></para>
          </step>
        </procedure>
      </sect1>

      <sect1 id="intro.generating">
        <title>Generating your custom MOLGENIS database</title>

        <procedure>
          <step>
            <para>Start eclipse and open the molgenis workspace (as downloaded
            above). All that you need is in project 'molgenis_distro'.</para>
          </step>

          <step>
            <para>Edit the design files. A MOLGENIS typically has two design
            files, in this case:</para>

            <para><emphasis role="italic">molgenis_db.xml</emphasis>
            containing the structure of your data and</para>

            <para><emphasis role="italic">molgenis_ui.xml
            </emphasis>containing a blueprint of your user interface</para>

            <para>You can edit them to adapt MOLGENIS to your needs, see other
            chapters.</para>
          </step>

          <step>
            <para>Generate the MOLGENIS as blueprinted</para>

            <para>Go to the folder 'handwritten/java' and right-click
            'MolgenisGenerate'</para>

            <para>Choose 'run as' and then 'run as java application'</para>

            <para>The generator will be started and its progress shown on
            Console.</para>

            <para>Eclipse has to be told new code has been generated:
            right-click on project 'molgenis' and choose 'refresh'.</para>

            <tip>
              <para>Next time you can choose the green 'play' button on the
              toolbar to run the generator and/or database updater.</para>
            </tip>
          </step>

          <step>
            <para>Update the database with the newly generated
            structure</para>

            <para>You can either copy-paste the file
            'generated/sql/createTables.sql into mysql' or</para>

            <para>right-click the class
            'handwritten/java/MolgenisUpdateDatabase' and select 'run as
            application' do it automatically</para>

            <warning>
              <para>The database update program will overwrite any data in
              your database. <emphasis role="italic">The program will ask you
              'y' or 'n' whether you really want to overwrite the existing
              database.</emphasis>. Don't use this on a database already
              filled. Instead change the database by hand using 'alter table'
              commands as described at <ulink
              url="http://dev.mysql.com/doc/refman/5.0/en/alter-table.html">http://dev.mysql.com/doc/refman/5.0/en/alter-table.html</ulink></para>
            </warning>
          </step>

          <step>
            <para>Run the MOLGENIS and see if you like it already.</para>

            <para>Right-click the 'molgenis' project folder and choose 'run
            as' and ' run on server</para>

            <para>(First time only) you have to choose the server (Apache
            Tomcat) and set the path (e.g. C:\Program Files\Apache Software
            Foundation\Tomcat 5.5).</para>

            <para>Now Tomcat will be started and a browser shown with your
            MOLGENIS.</para>

            <para>Alternatively you can view molgenis in your favorite browser
            at <ulink url="">http://localhost:8080/molgenis</ulink></para>
          </step>
        </procedure>

        <para>That is all there is too it :-)</para>
      </sect1>

      <sect1>
        <title>Frequently asked questions</title>

        <sect2>
          <title>Changing the database</title>

          <para>Obviously, when generating more than one MOLGENIS one might
          want to change e.g. database location (to allow for multiple). These
          options can be set in the file 'molgenis.properties'. MOLGENIS is a
          standard Tomcat/Servlet application. Hence, when changing the
          database settings also need to be changed in
          WebContent/META-INF/context.xml. The MOLGENIS generator does this
          automatically</para>
        </sect2>

        <sect2>
          <title>Does MOLGENIS also work on Postgresql</title>

          <para>Experimentally yes. When you change in molgenis.properties
          also the driver to use 'org.postgresql.Driver' then the generator
          assumes Postgresql and generates suitable code. Remember to give
          your MOLGENIS user suitable privileges.</para>
        </sect2>

        <sect2>
          <title>Can I split my models over multiple XML files</title>

          <para>Yes you can. Actually this is a great way to make reusable
          modules from your models to in alternative combinations. Inside the
          molgenis.properties file you can specify this:</para>

          <programlisting>
# xml file with entity descriptions
model_database = model_part1.xml, model_part2.xml, model_part3.xml
                    </programlisting>

          <para>You can use the 'module' syntax to make these modules also
          visible in the documentation. See <link
          linkend="ref.module">&lt;module&gt;</link></para>
        </sect2>

        <sect2>
          <title>Can I set login and authorization</title>

          <para>No, not yet. This is back on the drawing board.</para>
        </sect2>

        <sect2>
          <title>Can I add my own 'trigger' when 'add', 'update' or 'delete'
          is called</title>

          <para>When an entity object is saved it goes through a so-called
          mapper that translates the object to e.g. the mySql database. It is
          possible to plug-in a decorator to change that behaviour, e.g. to
          check certain contraints, or to automatically process the data. In
          the XML you can use the 'decorator' tab. Then a plugin will be
          generated in the folder handwritten/java with in the example the
          name 'my.decorators.MyEntityMapperDecorator'. To this class you can
          add extra code. See the section on how to write a <link
          linkend="plugin.mapper.decorator">MappingDecorator</link> plugin for
          details.</para>

          <programlisting>   &lt;entity name="MyEntity" decorator="my.decorators.MyEntityMapperDecorator"&gt;
       ...
   &lt;/entity&gt; </programlisting>
        </sect2>
      </sect1>
    </chapter>

    <chapter id="chapter.example">
      <title>Example MOLGENIS instance</title>

      <subtitle>How to build a MOLGENIS variant in three steps</subtitle>

      <sect1>
        <title>Step 1: what do you want to have?</title>

        <para>Say, for example you are just starting genetical genomics
        experiments. You start sketching and you decide that you want to see
        on your screen an input box for (1) experiments, with beneat it input
        boxes to edit your (2) traits (e.g. probes/genes/markers), (3)
        subjects (e.g. mice), and (4) assays (e.g. microarray hybridizations,
        qtl profiles) with (5) data (e.g. probe intensities, genotypes).
        Conceptually, that is something as you see below:</para>

        <figure>
          <title>Example of an bio-experimental data structure</title>

          <graphic fileref="images/figure2.1.png" scalefit="1" width="100%" />
        </figure>
      </sect1>

      <sect1>
        <title>Step 2: what you want to see?</title>

        <para>We assume you started Eclipse as described above. In eclipse you
        describe your user interface in a simple xml file using MOLGENIS user
        interface description language', i.e., in the project 'molgenis' you
        edit 'molgenis_ui.xml<emphasis role="italic"></emphasis>'.</para>

        <para>The screenshot belows show how you can describe the
        userinterface, that consists of a “form” to show “Experiment”
        entities. This form has a submenu (ExperimentMenu) showing showing the
        “Traits” and “Subjects” and “Assay” entities. And underneath “Assay”
        we want to see yet another subform with the related data: <figure>
            <title>Example of a user interface description</title>

            <graphic fileref="images/figure2.2.png" scalefit="1" width="100%" />
          </figure></para>
      </sect1>

      <sect1>
        <title>Step 3: how is your data structured?</title>

        <para>In eclipse you describe your user interface in a simple xml file
        using MOLGENIS user interface description language', i.e., in the
        project 'molgenis' you edit 'molgenis_db.xml<emphasis
        role="italic"></emphasis>'.</para>

        <para>Below we detail how the data structure can be described in the
        domain specific language of MOLGENIS. Most of it is self-explanatory
        but we highlight some statements: <itemizedlist>
            <listitem>
              <para>Implements=”Identifiable” means that the entity has the
              same properties as ‘Identifiable’, i.e. each entity has and
              auto-generated Id and a Name. This allows easy reuse of data
              structures. Note that 'Identifiable' itself is abstract, meaning
              that it is just used for modeling purposes only.</para>
            </listitem>

            <listitem>
              <para>type=”xref” and xref_field=”Experiment.Id” indicates that
              the field Experiment of Subject should cross reference (x ref)
              to an existing Experiment, using Id to uniquely identify this
              Experiment.</para>
            </listitem>

            <listitem>
              <para>Cross references are used to automatically link forms
              together, i.e. when viewing experiments only the related
              Subjects are shown using the subject.experiment to experiment.id
              cross references.</para>
            </listitem>
          </itemizedlist><figure>
            <title>Example of a data structure description</title>

            <graphic fileref="images/figure2.3.png" scalefit="1" width="100%" />
          </figure></para>
      </sect1>

      <sect1>
        <title>Result.</title>

        <para>Generate and run your MOLGENIS as described in <link
        linkend="intro.generating">Chapter 1, section 2</link>. The expected
        result will now look like shown in the figure below (without the
        example data that we added to show how it works): [TODO replace with
        example showing also R and webservices interface]. And of course, if
        you don't like it yet you can edit the files above and regenerate in a
        few minutes.<figure>
            <title>Example of a generated MOLGENIS</title>

            <graphic fileref="images/figure2.4.png" scalefit="1" width="100%" />
          </figure></para>
      </sect1>
    </chapter>
  </part>

  <part>
    <title>MOLGENIS little language reference</title>

    <chapter id="chapter.ref.db">
      <title>The data model language</title>

      <subtitle>Description of XML elements and their usage.</subtitle>

      <sect1 id="ref.application">
        <title>&lt;application&gt;</title>

        <para>Application contains the blueprint for the whole system. For
        example:</para>

        <example>
          <title>Using &lt;application&gt;.</title>

          <programlisting language="xml">
&lt;molgenis name="myfirstdb" label="My First Database"&gt;
  &lt;menu name="mainmenu"&gt; ...
  &lt;entity name="firstentity"/&gt;
  &lt;module name="mymodule"/&gt;
  ...
&lt;/molgenis&gt;</programlisting>
        </example>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>name="name": name of your MOLGENIS blueprint. This will be
            used by the generator to generate java packages.</para>
          </listitem>

          <listitem>
            <para>label="your label": Label of your MOLGENIS system. This will
            be shown on the screen as well as heading in the generated
            documentation.</para>
          </listitem>
        </itemizedlist>

        <para>Can contain:</para>

        <itemizedlist>
          <listitem>
            <para>Exactly one &lt;menu&gt; or one &lt;form&gt; as main
            screen.</para>
          </listitem>

          <listitem>
            <para>Zero or one &lt;description&gt; elements describing the
            application</para>
          </listitem>

          <listitem>
            <para>Many &lt;entity&gt; elements describing the data structure.
            See <link linkend="ref.entity">&lt;entity&gt;</link></para>
          </listitem>

          <listitem>
            <para>Many &lt;module&gt; elements describing the data structure.
            These are containers to group &lt;entity&gt;.See <link
            linkend="ref.module">&lt;module&gt;</link></para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="ref.entity">
        <title>&lt;entity&gt;</title>

        <para>A entity defines the structure of a biological dat entity (i.e.,
        a table in the database). For example:</para>

        <example>
          <title>Using &lt;entity&gt;.</title>

          <programlisting>
&lt;entity name="unique_name"&gt;
    &lt;description&gt;Thisis my first entity.&lt;/description&gt;
    &lt;field name="name" type="string"/&gt;
     &lt;field name="investigation" type="string"/&gt;
    &lt;unique fields="name,investigation"/&gt;
&lt;/entity&gt;</programlisting>
        </example>

        <para>Required attributes:</para>

        <itemizedlist>
          <listitem>
            <para>name="name": globally unique name for this entity (within
            this blueprint).</para>
          </listitem>
        </itemizedlist>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>label="Nice screen name": an user-friendly alias to show as
            form header (default: copied from name).</para>
          </listitem>

          <listitem>
            <para>extends="other_entity": you can use inheritance to make your
            entity inherit the fields of its 'superclass' using
            extends.</para>
          </listitem>

          <listitem>
            <para>abstract="true": you define what programmers call
            'interfaces'. This are abstract objects that you can use as
            'contract' for other entities to 'implement'..</para>
          </listitem>

          <listitem>
            <para>implements="abstract_entity": you can use inheritance to
            make your entity inherit the fields of its 'interface' using
            implements and refering to 'abstract' entities. The implemented
            fields are copied to this entity.</para>
          </listitem>

          <listitem>
            <para>decorator="package.class": you can add custom code to change
            the way entities are added, updated and removed. See the section
            on how to write a<link
            linkend="plugin.mapper.decorator">MappingDecorator</link>MappingDecorator
            plugin.</para>
          </listitem>
        </itemizedlist>

        <example>
          <title>Using inheritance: implements and extends</title>

          <programlisting>
&lt;entity name="bicycle"&gt;
    &lt;description&gt;This my general entity&lt;/description&gt;
    &lt;field name="name" type="string"/&gt;
&lt;/entity&gt;
&lt;entity name="mountainbike" extends="bicycle"&gt;
    &lt;description&gt;This type of bicycle has a name, but also number of gears&lt;/description&gt;
    &lt;field name="numberOfGears" type="int"/&gt;
&lt;/entity&gt;</programlisting>
        </example>

        <para>Application can contain:</para>

        <itemizedlist>
          <listitem>
            <para>Zero or one &lt;description&gt; to describe this
            entity.</para>
          </listitem>

          <listitem>
            <para>One or more &lt;field&gt; that detail entity
            structure.</para>
          </listitem>

          <listitem>
            <para>Zero or more &lt;unique&gt; indicating unique constraints on
            field(s).</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="ref.field">
        <title>&lt;field&gt;</title>

        <para>A field defines one property of an entity (i.e., a table
        column). For example:</para>

        <example>
          <title>Using &lt;field&gt;.</title>

          <programlisting>
&lt;field name="unique_name" type="string" description="this is my first field"/&gt;
	
&lt;field name="unique_name" type="xref" xref_field="entity_name.field_name"/&gt;
	
&lt;field name="unique_name" type="enum" enum_options="[option1,option2]"/&gt;</programlisting>
        </example>

        <para>Required attributes:</para>

        <itemizedlist>
          <listitem>
            <para>name="name": locally unique name for this entity (within
            this entity).</para>
          </listitem>

          <listitem>
            <para>type="type": define the type of data that can be stored in
            this field, either:</para>

            <itemizedlist>
              <listitem>
                <para>type="string": a single line text string of variable
                length, max 255 chars.</para>
              </listitem>

              <listitem>
                <para>type="int": a natural number.</para>
              </listitem>

              <listitem>
                <para>type="boolean": a boolean.</para>
              </listitem>

              <listitem>
                <para>type="decimal": a decimal number.</para>
              </listitem>

              <listitem>
                <para>type="date": a date.</para>
              </listitem>

              <listitem>
                <para>type="datetime": a date that includes the time.</para>
              </listitem>

              <listitem>
                <para>type="file": attaches a file to the entity.</para>
              </listitem>

              <listitem>
                <para>type="text": a multiline textarea of max 2gb.</para>
              </listitem>

              <listitem>
                <para>type="xref": references to a field in another entity
                specified by xref_field attribute (required for xref). This
                will be shown as variable lookup-list.</para>
              </listitem>

              <listitem>
                <para>type="mref": many-to-many references to a field in
                another entity specified by xref_field attribute (required for
                mref). This will be shown as multiple select lookup-list.
                (Under the hood, a link table is generated)</para>
              </listitem>

              <listitem>
                <para>type="enum": references to a fixed look-up list options,
                specificed by enum_options attribute (required for
                enum)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>label="Nice screen name": an user-friendly alias to show as
            form header (default: copied from name).</para>
          </listitem>

          <listitem>
            <para>unique="true": values of this field must be unique within
            the entity (default: "false")</para>
          </listitem>

          <listitem>
            <para>nillable="true": this field can be left blank (default:
            "false")</para>
          </listitem>

          <listitem>
            <para>readonly="true": this field cannot be edited once they are
            saved (default: "false")</para>
          </listitem>

          <listitem>
            <para>length="n" (string only): limits the length of a string to
            1&lt;=n&lt;=255 (default: "255").</para>
          </listitem>

          <listitem>
            <para>xref_field="entityname.fieldname": specifies a entity and
            field that this xref field must reference to, separated by '.'
            (default: required for xref)</para>
          </listitem>

          <listitem>
            <para>xref_label="{afield} {anotherfield}": makes labels for the
            xref options based on fields of the referenced entity, indicated
            between '{}' (default: copied from xref_field).</para>
          </listitem>

          <listitem>
            <para>enum_options"[value1,value2]": the fixed list of options for
            this enum (default: required for enum).</para>
          </listitem>

          <listitem>
            <para>description="One line description": describes this field
            which the user can see when (s)he mouses over the field (default:
            "").</para>
          </listitem>
        </itemizedlist>

        <para>Field can contain no other elements:</para>
      </sect1>

      <sect1 id="ref.unique">
        <title>&lt;unique&gt;.</title>

        <para>A unique defines which properties of an entity (i.e., table
        columns) should be unique. There are two ways to make a field
        unique.</para>

        <para>A single column is unique:</para>

        <example>
          <title>Using &lt;unique&gt; on single columns.</title>

          <programlisting>
&lt;molgenis&gt;	
  &lt;entity name="entity1"&gt;
    &lt;field name="f1" type="string" unique="true"/&gt;	
    &lt;field name="f2" type="string"/&gt;
    &lt;field name="f3" type="string"/&gt;
  &lt;/entity&gt;	
&lt;/molgenis&gt;</programlisting>
        </example>

        <para>Explanation: field "f1" is made unique via unique="true". This
        means that there cannot be two entities with f1="x"</para>

        <para>The combination of two or more columns is unique:</para>

        <example>
          <title>Using &lt;unique&gt; over multiple columns.</title>

          <programlisting>
&lt;molgenis&gt;
  &lt;entity name="entity1"&gt;
    &lt;field name="f1" type="string"/&gt;
    &lt;field name="f2" type="string"/&gt;
    &lt;field name="f3" type="string"/&gt;
    &lt;unique fields="f1,f2"/&gt;
  &lt;/entity&gt;
&lt;/molgenis&gt;</programlisting>
        </example>

        <para>Explanation: The combination of "f1" and "f2" is unique. This
        means that there can be two entities with f1="x" but only if the
        values for f2 differ.</para>

        <para>Required attributes:</para>

        <itemizedlist>
          <listitem>
            <para>field="field1,field2": a comma separated list of unique
            fields.</para>
          </listitem>
        </itemizedlist>

        <para>Note: You can add as many unique constraints you like.</para>
      </sect1>

      <sect1 id="ref.module">
        <title>&lt;module&gt;</title>

        <para>A module can be used to group entities in your model. This will
        show up in the generated documentation.</para>

        <example>
          <title>Using &lt;module&gt; to group entities.</title>

          <programlisting>
&lt;molgenis&gt;
    &lt;module name="module1"&gt;
        &lt;description&gt;This is my first module&lt;/description&gt;
          &lt;entity name="entity1"&gt;
                &lt;field name="f1" type="string" unique="true"/&gt;	
                &lt;field name="f2" type="string"/&gt;
                &lt;field name="f3" type="string"/&gt;
          &lt;/entity&gt;
          &lt;entity name="entity2"&gt;
                &lt;field name="f1" type="string" unique="true"/&gt;	
                &lt;field name="f2" type="string"/&gt;
                &lt;field name="f3" type="string"/&gt;
          &lt;/entity&gt;
       &lt;/module&gt;
&lt;/molgenis&gt;</programlisting>
        </example>
      </sect1>
    </chapter>

    <chapter id="chapter.ref.ui">
      <title>The user interface language</title>

      <sect1 id="ref.form">
        <title>&lt;form&gt;</title>

        <para>A form shows the records of its entity on screen. A form may
        have tabbed (menu) or un-tabbed (form) subscreens. For example:</para>

        <example>
          <title>Using &lt;form&gt;.</title>

          <programlisting>
&lt;form name="myname" entity="myentity"&gt;
  &lt;form name="myname" entity="mysubentity"/&gt;
&lt;/form&gt;
	
&lt;form name="myname" entity="myentity" viewtype="list" limit="10"/&gt;</programlisting>
        </example>

        <para>Required attributes:</para>

        <itemizedlist>
          <listitem>
            <para>name="name": locally unique name for this screen element
            (within its container).</para>
          </listitem>

          <listitem>
            <para>entity="myentity": which data entity will be loaded (i.e.,
            points to a &lt;entity name="myentity"/&gt;).</para>
          </listitem>
        </itemizedlist>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>label="Nice screen name": an user-friendly alias to show as
            form header (default: copied from name).</para>
          </listitem>

          <listitem>
            <para>viewtype="record" or viewtype="list": whether the form
            should start with a list or per-record (default: "record").</para>
          </listitem>

          <listitem>
            <para>limit="10": how many records must be shown in the list
            (default: "5").</para>
          </listitem>

          <listitem>
            <para>readonly="true": can the records be edited or is the form
            readonly (default: "false").</para>
          </listitem>
        </itemizedlist>

        <para>Application can contain:</para>

        <itemizedlist>
          <listitem>
            <para>Zero or more &lt;menu&gt; as subscreen(s).</para>
          </listitem>

          <listitem>
            <para>Zero or more &lt;form&gt; as subscreen(s).</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="ref.menu">
        <title>&lt;menu&gt;</title>

        <para>A menu shows tabs on screen for each contained subscreen
        (menu,form). For example:</para>

        <example>
          <title>Using &lt;menu&gt;.</title>

          <programlisting>
&lt;menu name="menuname"&gt;
  &lt;form name="myfirsttab" entity="formentity"/&gt;
  &lt;menu name="mysecondtab"&gt;...
  &lt;form name="mythirdtab" entity="formentity"/&gt;
&lt;/menu&gt;	</programlisting>
        </example>

        <para>Required attibutes:</para>

        <itemizedlist>
          <listitem>
            <para>name="menuname": locally unique name for this screen element
            (within its container).</para>
          </listitem>
        </itemizedlist>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>startswith="mysubelement": subscreen tab that is selected
            when menu is first shown (default: first subscreen).</para>
          </listitem>
        </itemizedlist>

        <para>Application can contain:</para>

        <itemizedlist>
          <listitem>
            <para>Zero or more &lt;menu&gt; as subscreen(s).</para>
          </listitem>

          <listitem>
            <para>Zero or more &lt;form&gt; as subscreen(s).</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="ref.plugin">
        <title>&lt;plugin&gt;</title>

        <para>A entity defines the structure of a biological dat entity (i.e.,
        a table in the database). For example:</para>

        <example>
          <title>Using &lt;plugin&gt; example.</title>

          <programlisting>
&lt;plugin name="MyPlugin" type="plugins.myplugin.MyPluginScreen"/&gt;
</programlisting>
        </example>

        <para>Required attributes:</para>

        <itemizedlist>
          <listitem>
            <para>name="name": globally unique name for this entity (within
            this blueprint).</para>
          </listitem>

          <listitem>
            <para>type="package.class": reference to a java class in your
            handwritten/java folder. If it doesn't exist a boilerplate class
            will be auto-generated for you. See the section on <link
            linkend="plugin.screen">Plugin</link> screens to see how to edit
            this file.</para>
          </listitem>
        </itemizedlist>

        <para>Optional attributes:</para>

        <itemizedlist>
          <listitem>
            <para>label="Nice screen name": an user-friendly alias to show as
            form header (default: copied from name).</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </sect1>
    </chapter>

    <chapter>
      <title>Adding custom plug-ins to the generated software</title>

      <sect1>
        <title>Introduction</title>

        <para>See the examples in the molgenis distro. At the moment there are
        two types of plug-ins.</para>

        <itemizedlist>
          <listitem>
            <para>Plugin of a screen</para>
          </listitem>

          <listitem>
            <para>MapperDecorator to change what happens when 'add', 'update'
            or 'delete' is called</para>
          </listitem>
        </itemizedlist>

        <para>Alternatively, you can also move generated code to the
        handwritten section and edit that (advanced users).</para>
      </sect1>

      <sect1 id="plugin.screen">
        <title>Adding a plug-in screen</title>

        <para>This feature allows you to produce a custom screen that does
        whatever you want it to do. The procedure consists of three
        steps:</para>

        <orderedlist>
          <listitem>
            <para><emphasis role="bold">Add the plugin to the model.
            </emphasis>Describe where you want to put your plugin in the
            MOLGENIS 'UI' XML. The plugin 'type' points to a java class that
            is typically stored in handwritten/java.</para>

            <programlisting>&lt;molgenis&gt;
&lt;plugin name="MyPlugin" type="plugins.myplugin.MyPluginScreen" /&gt;
&lt;/molgenis&gt;</programlisting>

            <para>When you now run the generator an 'boilerplate'' screen
            plugin class will be generated inside the folder handwritten/java
            (unless the file allready consists). In this case a class called
            'plugins.myplugin.MyPluginScreen.java'. Next to that also a layout
            template is generated to layout the contents of your plugin in
            'plugins.myplugin.MyPluginScreen.ftl'. </para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Edit the plugin class. </emphasis>The
            following empty plugin class is generated for you to change to
            make it do whatever you want (its name depends on you plugin class
            name):</para>

            <programlisting>package plugins.myplugin;

import org.molgenis.assets.screen.Screen;
import org.molgenis.assets.screen.plugin.PluginScreen;
import org.molgenis.util.Tuple;

public class MyPluginScreen extends PluginScreen
{
   public MyPluginScreen(String name, Screen parent)
   {
      super(name, parent);
   }

   @Override
   public String getViewName()
   {
      return "plugins_myplugin_MyPluginScreen";
   }

   @Override
   public String getViewTemplate()
   {
      return "plugins/myplugin/MyPluginScreen.ftl";
   }

   @Override
   public void handleRequest(Tuple request)
   {

      try
      {
         Database db = this.getDatabase();
        //String action = request.getString("__action");
        //
        //if( action.equals("do_add") )
        //{
        //    Experiment e = new Experiment();
        //    //read the request directly into the entity using matching field/input names
        //    e.set(request);
        //    db.add(e);
        //}
      }
      catch(Exception e)
      {
         //...
      }

   }

   @Override
   public void reload()
   {
      try
      {
         Database db = this.getDatabase();
         //Query q = db.query(Experiment.class);
         //q.like("name", "test");
         //List&lt;Experiment&gt; recentExperiments = q.find();
         //
         ////do something
      }
      catch(Exception e)
      {
         //...
      }
   }
}</programlisting>

            <para>Edit the function 'handleRequest' to process user requests.
            A simple 'helloWorld' example is commented out. Edit the function
            'reload' to indicate what needs to be done if the page is reloaded
            by the user (so, after a handleRequest). This function is
            typically us ined to retrieve data from the database. Again, a
            simple 'helloWorld' example is in the comments.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Edit the plugin layout.</emphasis>The
            following empty layout template is generated for you. This
            template is written using the Freemarker language (<ulink
            url="???">http://freemarker.org/docs/index.html</ulink>) and
            allows you to change to layout it in the way you like (its name
            depends on you plugin class name):</para>

            <programlisting>&lt;#macro plugins_myplugin_MyPluginScreen&gt;
&lt;#assign model = screen.model&gt;
&lt;!-- normally you make one big form for the whole plugin--&gt;
&lt;form method="post" enctype="multipart/form-data" name="${screen.name}"&gt;
   &lt;!--needed in every form: to redirect the request to the right screen--&gt;
   &lt;input type="hidden" name="__target" value="${screen.name}"" /&gt;
   &lt;!--needed in every form: to define the action. This can be set by the submit button--&gt;
   &lt;input type="hidden" name="__action" /&gt;
   
&lt;!-- this shows a title and border --&gt;
   &lt;div class="formscreen"&gt;
      &lt;div class="form_header" id="${screen.getName()}"&gt;
      ${screen.label}
      &lt;/div&gt;
      &lt;div class="screenbody"&gt;
         &lt;div class="screenpadding"&gt;
&lt;#--begin your plugin--&gt;

&lt;input name="myinput" value="${screen.getMyValue()}"&gt;
&lt;input type="submit" value="Change name" onclick="__action.value='do_myaction';return true;"/&gt;

&lt;#--end of your plugin--&gt;
         &lt;/div&gt;
      &lt;/div&gt;
   &lt;/div&gt;
&lt;/form&gt;
&lt;/#macro&gt;
</programlisting>

            <para>Notice that an html form is already generated for you,
            including some basic layout. In MOLGENIS, a form must always have
            two hidden parameters called __target and __action: </para>

            <itemizedlist>
              <listitem>
                <para>The __target parameter routes any user request back to
                you plugin class (using the screen name, in this example
                'MyPlugin'). </para>
              </listitem>

              <listitem>
                <para>The __action parameter is not actually required but has
                been a good design pattern to simplify event handling when
                your plugin has multiple buttons. Then, each action button has
                a small piece of 'onclick' javascript to set the value of the
                action before submit (return true makes the submit go forward.
                </para>
              </listitem>
            </itemizedlist>

            <para>For example here:</para>

            <programlisting>&lt;input type="submit" value="Change name" onclick="__action.value='do_myaction';return true;"/&gt;</programlisting>
          </listitem>
        </orderedlist>
      </sect1>

      <sect1 id="plugin.mapper.decorator">
        <title>Adding a mapping decorator</title>

        <para>Sometimes you want to slightly alter the default behavior of the
        MOLGENIS add, update and delete functions, e.g. to check certain
        contraints, or to automatically process a attached file of data. In
        MOLGENIS, when an entity object is saved it goes through a so-called
        mapper that translates the object to e.g. the mySql database. Using
        'MappingDecorator' is possible to plug-in a decorator to change that
        behaviour.The procedure consists of two steps:</para>

        <orderedlist>
          <listitem>
            <para><emphasis role="bold">Add the plugin to the model.
            </emphasis>Describe which entity you want to decorate in the
            MOLGENIS 'DB' XML. The 'decorator' attribute' points to a java
            class should be stored iin handwritten/java.</para>

            <programlisting> &lt;molgenis&gt;
  ...
  &lt;entity name="MyEntity" decorator="my.decorators.MyEntityMapperDecorator"&gt;
     ...
  &lt;/entity&gt; 
  ...
&lt;/molgenis&gt;</programlisting>

            <para>When you now run the generator an 'empty' decorator plugin
            class will be generated inside the folder handwritten/java (unless
            the file allready consists). In this case a class called
            'my.decorators.MyEntityMapperDecorator'.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Edit the plugin class. </emphasis>The
            following empty plugin class is generated (its name depends on you
            plugin class name as stated in 'decorator' above). Just add code
            before or after the 'super' calls to change the pre/post update
            behavior of your database. The commented sections give pointers on
            how that can work:<programlisting>public class MyEntityMapperDecorator extends MappingDecorator&lt;example.data.types.MyEntity&gt;
{
   //JDBCMapper is the generated class that we change in this plugin
   public MyEntityMapperDecorator(JDBCMapper generatedMapper)
  {
     super(generatedMapper);
   }

   @Override
   public int add(List&lt;example.data.types.MyEntity&gt; entities) throws SQLException, DatabaseException
   {
      // add your pre-processing here, e.g.
      // for (example.data.types.MyEntity e : entities)
      // {
      //    e.setTriggeredField("Before add called!!!");
      // }

      // here we call the standard 'add'
      int count = super.add(entities);

      // add your post-processing here
      // if you throw and exception the previous add will be rolled back

      return count;
   }

   @Override
   public int update(List&lt;example.data.types.MyEntity&gt; entities) throws SQLException
   {

      // add your pre-processing here, e.g.
      // for (example.data.types.MyEntity e : entities)
      // {
      //      e.setTriggeredField("Before update called!!!");
      // }

      // here we call the standard 'update'
      int count = super.update(entities);

      // add your post-processing here
      // if you throw and exception the previous add will be rolled back

      return count;
   }

   @Override
   public int remove(List&lt;example.data.types.MyEntity&gt; entities) throws SQLException
   {
      // add your pre-processing here

      // here we call the standard 'remove'
      int count = super.remove(entities);

      // add your post-processing here, e.g.
      // if(true) throw new SQLException("Because of a post trigger the remove is cancelled.");

      return count;
   }
}
</programlisting></para>
          </listitem>
        </orderedlist>
      </sect1>

      <sect1>
        <title>Java API basics</title>

        <para>TODO</para>
      </sect1>
    </chapter>
  </part>

  <!--
    <part>
        <title>MOLGENIS end user manual.</title>
        <subtitle>How to use a MOLGENIS instance.</subtitle>
        <chapter>
            <title>Using the user interface</title>
            <sect1>
                <title>TODO</title>
                <para/>
            </sect1>
        </chapter>
        <chapter>
            <title>Using the R interface</title>
            <sect1>
                <title>TODO</title>
                <para/>
            </sect1>
        </chapter>
        <chapter>
            <title>Using the Web service interface</title>
            <sect1>
                <title>TODO</title>
                <para/>
            </sect1>
        </chapter>
        <chapter>
            <title>Using the tab delimited file import/export</title>
            <sect1>
                <title>TODO</title>
                <para/>
            </sect1>
        </chapter>
        <chapter>
            <title>FAQ</title>
            <sect1>
                <title>TODO</title>
                <para/>
            </sect1>
        </chapter>
    </part>-->
</book>

}}}