TracNav(MolgenisGuide)?

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 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

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

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

  <field name="displayname" unique="true"/>
  

• Optional (‘nillable’) string fields for firstname, lastname and midinitials:

  <field name="firstname" nillable="true"/>
  <field name="midinitials" nillable="true"/>
  <field name="lastname" nillable="true"/>
  

• An optional field of type date for birthday:

  <field name="birthday" type="date" nillable="true"/>
  

Create a “Address” data type

• Create the entity again

  <entity name="Address">
  

• A unique, automatic numeric identifier field that MOLGENIS will use to refer addresses.

  <field name="address_id" type="autoid"/>
  

• Add the phone number field:

  <field name="phone"/>
  

• Add a field where the user can choose from an enumeration of options whether the address is ‘home’,’work’,or ‘mobile’:

  <field name="address_type" type="enum" enum_options="[home,work,mobile]"/>
  

Link Addresses to Contact.

• In the Address entity create a ​ForeignKey reference to Contact

  <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 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