[[TracNav(MolgenisGuide)]]

[[TOC(inline)]]

= Generating MOLGENIS from scratch, the Address Book Example =
== 1. Create the data model in `addressbook_db.xml` ==
Create a new xml file ‘addressbook_db.xml’ in the root of you application. This file will contain the MOLGENIS model. Use the following template:

{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE molgenis PUBLIC "MOLGENIS 1.0" "http://molgenis.sourceforge.net/dtd/molgenis_v_1_0.dtd">
<molgenis name="addressbook">

</molgenis>
}}}
=== Create a “Contact” data type ===
{{{
#!xml
<molgenis name="addressbook">
  <entity name="Contact">
		
  </entity>
</molgenis>
}}}
=== Add properties to “Contact” ===
 * A unique, automatic numeric identifier field that MOLGENIS will use to refer contacts.
{{{
#!xml
<field name="contact_id" type="autoid"/>
}}}
 * A required and unique string field ‘displayname’ to have a unique label to find Contacts by. Note that if you provide no ‘type’ then type=”string” is implied.
{{{
#!xml
<field name="displayname" unique="true"/>
}}}
 * Optional (‘nillable’) string fields for firstname, lastname and midinitials:
{{{
#!xml
<field name="firstname" nillable="true"/>
<field name="midinitials" nillable="true"/>
<field name="lastname" nillable="true"/>
}}}
 * An optional field of type date for birthday:
{{{
#!xml
<field name="birthday" type="date" nillable="true"/>
}}}

=== Create a “Address” data type ===
 * Create the entity again
{{{
#!xml
<entity name="Address">
}}}
 * A unique, automatic numeric identifier field that MOLGENIS will use to refer addresses.
{{{
#!xml
<field name="address_id" type="autoid"/>
}}}
 * Add the phone number field:
{{{
#!xml
<field name="phone"/>
}}}
 * Add a field where the user can choose from an enumeration of options whether the address is ‘home’,’work’,or ‘mobile’:
{{{
#!xml
<field name="address_type" type="enum" enum_options="[home,work,mobile]"/>
}}}

=== Link Addresses to Contact. ===
 * In the Address entity create a [http://en.wikipedia.org/wiki/Foreign_key ForeignKey] reference to Contact
{{{
#!xml
<field name="contact" type="xref"     
         xref_field="Contact.contact_id"       
         xref_label="displayname"/>
</entity>
}}}

Note that the xref_field refers to unique field ‘contact_id’ in entity ‘Contact’. The xref_label attribute indicates that we want to view references to Contact by ‘displayname’ name instead of the numeric id.

Use of a meaningless numeric ‘id’ next to a meaningful ‘label’ enables us to change the ‘displayname’ name on Contact without the problem of also having to change this on each Address that refers to this contact.

== 2. Model the user interface in `addressbook_ui.xml` ==
* Create a new xml file ‘addressbook_ui.xml’ in the root of you application by copy-pasting the db.xml file. This file will contain the MOLGENIS user interface model.

* We want to show the list of Addresses nested per Contact; for MOLGENIS you simply express this by nesting form elements. If suitable ‘xrefs’ exists these will be used to tie container and nested form together:

{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE molgenis PUBLIC "MOLGENIS 1.0" "http://molgenis.sourceforge.net/dtd/molgenis_v_1_0.dtd">
<molgenis name="addressbook">
  <form entity="Contact" name="Contacts">
    <form entity="Address" name="Addresses" view="list"/>
  </form>
</molgenis>
}}}
== Generate the application ==
=== Configure the `molgenis.properties` file. ===
The `model_database` and `model_userinterface` options point to the XML files where a data model and user interface is specified. Change to point to our newly created `addressbook_db.xml ` and `addressbook_ui.xml` files

{{{
###############################################################
# 1. FILES DESCRIBING YOUR DESIGN USING MOLGENIS XML LANGUAGE 
# can be multiple files ',' separated
###############################################################

# xml file with data model in terms of 'entity' descriptions
model_database = addressbook_db.xml

# xml file with user screen descriptions in terms of 'form', 'menu',..
model_userinterface = addressbook_ui.xml
}}}

=== Create an addressbook mysql instance ===
CreateMysqlDatabase and then edit 'molgenis.properties' file to connect to this database. For example:
{{{
###############################################################
# 2. DATABASE SETTINGS
###############################################################

# MySQL:
# jdbc compatible connection parameters to a database (see doc of database supplier)
db_driver = com.mysql.jdbc.Driver
db_user = molgenis
db_password = molgenis
db_uri= jdbc:mysql://localhost/addressbook
}}}
=== Generate and compile your database ===
See MolgenisGettingStarted

== 3. Expected result ==
[[Image(address-book-screenshot.JPG)]]