| | 1 | {{{ |
| | 2 | #!docbook |
| | 3 | <?xml version="1.0" encoding="UTF-8"?> |
| | 4 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| | 5 | "http://www.docbook.org/xml/4.4/docbookx.dtd"> |
| | 6 | <book lang="en"> |
| | 7 | <bookinfo> |
| | 8 | <title>MOLGENIS 3.0.3 manual</title> |
| | 9 | |
| | 10 | <subtitle>How to quickly generate your own biodatabase using the MOLGENIS |
| | 11 | suite.</subtitle> |
| | 12 | |
| | 13 | <author> |
| | 14 | <affiliation> |
| | 15 | <orgname>University of Groningen</orgname> |
| | 16 | </affiliation> |
| | 17 | |
| | 18 | <firstname>Morris</firstname> |
| | 19 | |
| | 20 | <surname>Swertz et al</surname> |
| | 21 | |
| | 22 | <email>molgenis-users@lists.sourceforge.net</email> |
| | 23 | </author> |
| | 24 | |
| | 25 | <copyright> |
| | 26 | <year>2001-2008</year> |
| | 27 | </copyright> |
| | 28 | |
| | 29 | <!-- <revhistory> |
| | 30 | <revision> |
| | 31 | <revnumber>0.1</revnumber> |
| | 32 | <date>2008-09-05</date> |
| | 33 | </revision> |
| | 34 | </revhistory>--> |
| | 35 | |
| | 36 | <abstract> |
| | 37 | <para>MOLGENIS is the 'holistic' model-driven database platform that |
| | 38 | allows you to store and query any (biological) data you want .... as |
| | 39 | long as you tell it in a model how your data looks like ;-) This manual |
| | 40 | helps you to get started.</para> |
| | 41 | |
| | 42 | <para>With MOLGENIS you can compactly model the structure of your data, |
| | 43 | and the way you want to see it on screen, using a simple XML language. |
| | 44 | At the push of a button, the MOLGENIS generators automatically produce |
| | 45 | all the program code of your desired software instance. With each |
| | 46 | MOLGENIS instance you get 'for free' : <itemizedlist> |
| | 47 | <listitem> |
| | 48 | <para>a generated user interface to upload and query data in a web |
| | 49 | browser;</para> |
| | 50 | </listitem> |
| | 51 | |
| | 52 | <listitem> |
| | 53 | <para>a <ulink url="http://www.r-project.org"> |
| | 54 | R-project</ulink>interface to connect your favorite statistical |
| | 55 | tools;</para> |
| | 56 | </listitem> |
| | 57 | |
| | 58 | <listitem> |
| | 59 | <para>the web service interface to integrate e.g. NCBI, Ensembl, |
| | 60 | KEGG, using <ulink |
| | 61 | url="http://taverna.sourceforge.net">Taverna</ulink>;</para> |
| | 62 | </listitem> |
| | 63 | |
| | 64 | <listitem> |
| | 65 | <para>and a plug-in mechanism so you can easily add your custom |
| | 66 | programs to the generated software.</para> |
| | 67 | </listitem> |
| | 68 | </itemizedlist> And if you don't like what you see, or if your |
| | 69 | experiments change, you can quickly re-run the generator to accomodate. |
| | 70 | Thus in quick iterations you can produce the databases biologists want |
| | 71 | to have.</para> |
| | 72 | |
| | 73 | <para>MOLGENIS has been born from the demanding domain of life sciences |
| | 74 | (although it is not limited to that domain). Currently, MOLGENIS has |
| | 75 | been succesfull for microarray experiments, proteomics experiments, |
| | 76 | genetical genomics experiments, animal observations and first initatives |
| | 77 | have been started towards biobanking. MOLGENIS is open-source and free |
| | 78 | for use by academics, we only ask that you cite our work:</para> |
| | 79 | |
| | 80 | <para><itemizedlist> |
| | 81 | <listitem> |
| | 82 | <para>Swertz & Jansen:<ulink |
| | 83 | url="http://www.ncbi.nlm.nih.gov/pubmed/17297480">Beyond |
| | 84 | standardization: dynamic software infrastructures for systems |
| | 85 | biology.</ulink> Nature Reviews Genetics 8: 235-243.</para> |
| | 86 | </listitem> |
| | 87 | |
| | 88 | <listitem> |
| | 89 | <para>Swertz et al: <ulink |
| | 90 | url="http://www.ncbi.nlm.nih.gov/pubmed/15059831">Molecular |
| | 91 | Genetics Information System (MOLGENIS) alternatives in developing |
| | 92 | local experimental genomics databases.</ulink> Bioinformatics 20: |
| | 93 | 2075-83</para> |
| | 94 | </listitem> |
| | 95 | </itemizedlist></para> |
| | 96 | |
| | 97 | <para>We are happy to collaborate and help you generate interesting |
| | 98 | MOLGENIS instances for your research domain and co-author publications |
| | 99 | on these systems together. For commercial use of MOLGENIS we have a |
| | 100 | separate license.</para> |
| | 101 | </abstract> |
| | 102 | </bookinfo> |
| | 103 | |
| | 104 | <part> |
| | 105 | <title>Using the MOLGENIS generator</title> |
| | 106 | |
| | 107 | <chapter id="chapter.installation"> |
| | 108 | <title>Getting started</title> |
| | 109 | |
| | 110 | <abstract> |
| | 111 | <para>This chapter describes what software and procedures are needed |
| | 112 | to get started using MOLGENIS. The next chapters explain you how to |
| | 113 | configure MOLGENIS to your needs.</para> |
| | 114 | </abstract> |
| | 115 | |
| | 116 | <sect1> |
| | 117 | <title>Install the necessary software (only once)</title> |
| | 118 | |
| | 119 | <para>MOLGENIS is known to run happily at Windows, Linux and Mac. To |
| | 120 | get going, download and install the following:</para> |
| | 121 | |
| | 122 | <procedure> |
| | 123 | <step> |
| | 124 | <para>Java 6 JDK <ulink |
| | 125 | url="http://java.sun.com/javase/downloads/">http://java.sun.com/javase/downloads/</ulink></para> |
| | 126 | |
| | 127 | <para>Just install with standard options.</para> |
| | 128 | </step> |
| | 129 | |
| | 130 | <step> |
| | 131 | <para>Tomcat >=5 web server <ulink |
| | 132 | url="http://tomcat.apache.org/">http://tomcat.apache.org/</ulink></para> |
| | 133 | |
| | 134 | <para>Rember the root password you are asked!</para> |
| | 135 | |
| | 136 | <para>Don't run Tomcat as a service; we will start and stop it |
| | 137 | ourself.</para> |
| | 138 | </step> |
| | 139 | |
| | 140 | <step> |
| | 141 | <para>Mysql >=5.1 database <ulink |
| | 142 | url="http://dev.mysql.com/downloads/mysql/5.1.html">http://dev.mysql.com/downloads/mysql/5.1.html |
| | 143 | </ulink></para> |
| | 144 | |
| | 145 | <para>During installation of the windows version you need to tick |
| | 146 | 'innodb'.</para> |
| | 147 | |
| | 148 | <para><emphasis role="italic">Remember your root |
| | 149 | password!</emphasis></para> |
| | 150 | </step> |
| | 151 | |
| | 152 | <step> |
| | 153 | <para>Eclipse Integrated Development Environment <ulink |
| | 154 | url="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/ |
| | 155 | </ulink></para> |
| | 156 | |
| | 157 | <para>You need to install the J2EE version (which allows you to |
| | 158 | start/stop tomcat)</para> |
| | 159 | </step> |
| | 160 | |
| | 161 | <step> |
| | 162 | <para>(Optional) MOLGENIS autogenerates documentation for your |
| | 163 | application. This includes a graphical representation your model |
| | 164 | in UML format. This requires GraphViz to work:</para> |
| | 165 | |
| | 166 | <para>Download and install graphviz from |
| | 167 | http://www.graphviz.org/Download.php</para> |
| | 168 | |
| | 169 | <para>Make sure your PATH is set to run 'dot.exe' from the |
| | 170 | commandline.</para> |
| | 171 | </step> |
| | 172 | |
| | 173 | <step> |
| | 174 | <para>The latest 'molgenis_workspace.zip' from <ulink |
| | 175 | url="http://molgenis.sourceforge.net">http://molgenis.sourceforge.net</ulink> |
| | 176 | and unzip</para> |
| | 177 | |
| | 178 | <para>Just download and unzip. A directory 'molgenis_workspace' is |
| | 179 | created.</para> |
| | 180 | </step> |
| | 181 | |
| | 182 | <step> |
| | 183 | <para>Create a database in mysql and give molgenis permission to |
| | 184 | populate it.</para> |
| | 185 | |
| | 186 | <para>Open mysql.exe as root user</para> |
| | 187 | |
| | 188 | <para><emphasis role="italic">Under windows in "C:\Program |
| | 189 | Files\MySQL Server 5.1\bin\mysql.exe - u root -p</emphasis></para> |
| | 190 | |
| | 191 | <para><emphasis role="italic">Remember your root password from |
| | 192 | step 3!</emphasis></para> |
| | 193 | |
| | 194 | <para>Type the following to create a database 'molgenis' and |
| | 195 | provide rights to the molgenis generator to change it using |
| | 196 | password 'molgenis': <programlisting><code> |
| | 197 | create database molgenis; |
| | 198 | grant all privileges on molgenis.* to molgenis@localhost identified by 'molgenis'; |
| | 199 | flush privileges; |
| | 200 | use molgenis; |
| | 201 | </code></programlisting></para> |
| | 202 | </step> |
| | 203 | </procedure> |
| | 204 | </sect1> |
| | 205 | |
| | 206 | <sect1 id="intro.generating"> |
| | 207 | <title>Generating your custom MOLGENIS database</title> |
| | 208 | |
| | 209 | <procedure> |
| | 210 | <step> |
| | 211 | <para>Start eclipse and open the molgenis workspace (as downloaded |
| | 212 | above). All that you need is in project 'molgenis_distro'.</para> |
| | 213 | </step> |
| | 214 | |
| | 215 | <step> |
| | 216 | <para>Edit the design files. A MOLGENIS typically has two design |
| | 217 | files, in this case:</para> |
| | 218 | |
| | 219 | <para><emphasis role="italic">molgenis_db.xml</emphasis> |
| | 220 | containing the structure of your data and</para> |
| | 221 | |
| | 222 | <para><emphasis role="italic">molgenis_ui.xml |
| | 223 | </emphasis>containing a blueprint of your user interface</para> |
| | 224 | |
| | 225 | <para>You can edit them to adapt MOLGENIS to your needs, see other |
| | 226 | chapters.</para> |
| | 227 | </step> |
| | 228 | |
| | 229 | <step> |
| | 230 | <para>Generate the MOLGENIS as blueprinted</para> |
| | 231 | |
| | 232 | <para>Go to the folder 'handwritten/java' and right-click |
| | 233 | 'MolgenisGenerate'</para> |
| | 234 | |
| | 235 | <para>Choose 'run as' and then 'run as java application'</para> |
| | 236 | |
| | 237 | <para>The generator will be started and its progress shown on |
| | 238 | Console.</para> |
| | 239 | |
| | 240 | <para>Eclipse has to be told new code has been generated: |
| | 241 | right-click on project 'molgenis' and choose 'refresh'.</para> |
| | 242 | |
| | 243 | <tip> |
| | 244 | <para>Next time you can choose the green 'play' button on the |
| | 245 | toolbar to run the generator and/or database updater.</para> |
| | 246 | </tip> |
| | 247 | </step> |
| | 248 | |
| | 249 | <step> |
| | 250 | <para>Update the database with the newly generated |
| | 251 | structure</para> |
| | 252 | |
| | 253 | <para>You can either copy-paste the file |
| | 254 | 'generated/sql/createTables.sql into mysql' or</para> |
| | 255 | |
| | 256 | <para>right-click the class |
| | 257 | 'handwritten/java/MolgenisUpdateDatabase' and select 'run as |
| | 258 | application' do it automatically</para> |
| | 259 | |
| | 260 | <warning> |
| | 261 | <para>The database update program will overwrite any data in |
| | 262 | your database. <emphasis role="italic">The program will ask you |
| | 263 | 'y' or 'n' whether you really want to overwrite the existing |
| | 264 | database.</emphasis>. Don't use this on a database already |
| | 265 | filled. Instead change the database by hand using 'alter table' |
| | 266 | commands as described at <ulink |
| | 267 | 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> |
| | 268 | </warning> |
| | 269 | </step> |
| | 270 | |
| | 271 | <step> |
| | 272 | <para>Run the MOLGENIS and see if you like it already.</para> |
| | 273 | |
| | 274 | <para>Right-click the 'molgenis' project folder and choose 'run |
| | 275 | as' and ' run on server</para> |
| | 276 | |
| | 277 | <para>(First time only) you have to choose the server (Apache |
| | 278 | Tomcat) and set the path (e.g. C:\Program Files\Apache Software |
| | 279 | Foundation\Tomcat 5.5).</para> |
| | 280 | |
| | 281 | <para>Now Tomcat will be started and a browser shown with your |
| | 282 | MOLGENIS.</para> |
| | 283 | |
| | 284 | <para>Alternatively you can view molgenis in your favorite browser |
| | 285 | at <ulink url="">http://localhost:8080/molgenis</ulink></para> |
| | 286 | </step> |
| | 287 | </procedure> |
| | 288 | |
| | 289 | <para>That is all there is too it :-)</para> |
| | 290 | </sect1> |
| | 291 | |
| | 292 | <sect1> |
| | 293 | <title>Frequently asked questions</title> |
| | 294 | |
| | 295 | <sect2> |
| | 296 | <title>Changing the database</title> |
| | 297 | |
| | 298 | <para>Obviously, when generating more than one MOLGENIS one might |
| | 299 | want to change e.g. database location (to allow for multiple). These |
| | 300 | options can be set in the file 'molgenis.properties'. MOLGENIS is a |
| | 301 | standard Tomcat/Servlet application. Hence, when changing the |
| | 302 | database settings also need to be changed in |
| | 303 | WebContent/META-INF/context.xml. The MOLGENIS generator does this |
| | 304 | automatically</para> |
| | 305 | </sect2> |
| | 306 | |
| | 307 | <sect2> |
| | 308 | <title>Does MOLGENIS also work on Postgresql</title> |
| | 309 | |
| | 310 | <para>Experimentally yes. When you change in molgenis.properties |
| | 311 | also the driver to use 'org.postgresql.Driver' then the generator |
| | 312 | assumes Postgresql and generates suitable code. Remember to give |
| | 313 | your MOLGENIS user suitable privileges.</para> |
| | 314 | </sect2> |
| | 315 | |
| | 316 | <sect2> |
| | 317 | <title>Can I split my models over multiple XML files</title> |
| | 318 | |
| | 319 | <para>Yes you can. Actually this is a great way to make reusable |
| | 320 | modules from your models to in alternative combinations. Inside the |
| | 321 | molgenis.properties file you can specify this:</para> |
| | 322 | |
| | 323 | <programlisting> |
| | 324 | # xml file with entity descriptions |
| | 325 | model_database = model_part1.xml, model_part2.xml, model_part3.xml |
| | 326 | </programlisting> |
| | 327 | |
| | 328 | <para>You can use the 'module' syntax to make these modules also |
| | 329 | visible in the documentation. See <link |
| | 330 | linkend="ref.module"><module></link></para> |
| | 331 | </sect2> |
| | 332 | |
| | 333 | <sect2> |
| | 334 | <title>Can I set login and authorization</title> |
| | 335 | |
| | 336 | <para>No, not yet. This is back on the drawing board.</para> |
| | 337 | </sect2> |
| | 338 | |
| | 339 | <sect2> |
| | 340 | <title>Can I add my own 'trigger' when 'add', 'update' or 'delete' |
| | 341 | is called</title> |
| | 342 | |
| | 343 | <para>When an entity object is saved it goes through a so-called |
| | 344 | mapper that translates the object to e.g. the mySql database. It is |
| | 345 | possible to plug-in a decorator to change that behaviour, e.g. to |
| | 346 | check certain contraints, or to automatically process the data. In |
| | 347 | the XML you can use the 'decorator' tab. Then a plugin will be |
| | 348 | generated in the folder handwritten/java with in the example the |
| | 349 | name 'my.decorators.MyEntityMapperDecorator'. To this class you can |
| | 350 | add extra code. See the section on how to write a <link |
| | 351 | linkend="plugin.mapper.decorator">MappingDecorator</link> plugin for |
| | 352 | details.</para> |
| | 353 | |
| | 354 | <programlisting> <entity name="MyEntity" decorator="my.decorators.MyEntityMapperDecorator"> |
| | 355 | ... |
| | 356 | </entity> </programlisting> |
| | 357 | </sect2> |
| | 358 | </sect1> |
| | 359 | </chapter> |
| | 360 | |
| | 361 | <chapter id="chapter.example"> |
| | 362 | <title>Example MOLGENIS instance</title> |
| | 363 | |
| | 364 | <subtitle>How to build a MOLGENIS variant in three steps</subtitle> |
| | 365 | |
| | 366 | <sect1> |
| | 367 | <title>Step 1: what do you want to have?</title> |
| | 368 | |
| | 369 | <para>Say, for example you are just starting genetical genomics |
| | 370 | experiments. You start sketching and you decide that you want to see |
| | 371 | on your screen an input box for (1) experiments, with beneat it input |
| | 372 | boxes to edit your (2) traits (e.g. probes/genes/markers), (3) |
| | 373 | subjects (e.g. mice), and (4) assays (e.g. microarray hybridizations, |
| | 374 | qtl profiles) with (5) data (e.g. probe intensities, genotypes). |
| | 375 | Conceptually, that is something as you see below:</para> |
| | 376 | |
| | 377 | <figure> |
| | 378 | <title>Example of an bio-experimental data structure</title> |
| | 379 | |
| | 380 | <graphic fileref="images/figure2.1.png" scalefit="1" width="100%" /> |
| | 381 | </figure> |
| | 382 | </sect1> |
| | 383 | |
| | 384 | <sect1> |
| | 385 | <title>Step 2: what you want to see?</title> |
| | 386 | |
| | 387 | <para>We assume you started Eclipse as described above. In eclipse you |
| | 388 | describe your user interface in a simple xml file using MOLGENIS user |
| | 389 | interface description language', i.e., in the project 'molgenis' you |
| | 390 | edit 'molgenis_ui.xml<emphasis role="italic"></emphasis>'.</para> |
| | 391 | |
| | 392 | <para>The screenshot belows show how you can describe the |
| | 393 | userinterface, that consists of a “form” to show “Experiment” |
| | 394 | entities. This form has a submenu (ExperimentMenu) showing showing the |
| | 395 | “Traits” and “Subjects” and “Assay” entities. And underneath “Assay” |
| | 396 | we want to see yet another subform with the related data: <figure> |
| | 397 | <title>Example of a user interface description</title> |
| | 398 | |
| | 399 | <graphic fileref="images/figure2.2.png" scalefit="1" width="100%" /> |
| | 400 | </figure></para> |
| | 401 | </sect1> |
| | 402 | |
| | 403 | <sect1> |
| | 404 | <title>Step 3: how is your data structured?</title> |
| | 405 | |
| | 406 | <para>In eclipse you describe your user interface in a simple xml file |
| | 407 | using MOLGENIS user interface description language', i.e., in the |
| | 408 | project 'molgenis' you edit 'molgenis_db.xml<emphasis |
| | 409 | role="italic"></emphasis>'.</para> |
| | 410 | |
| | 411 | <para>Below we detail how the data structure can be described in the |
| | 412 | domain specific language of MOLGENIS. Most of it is self-explanatory |
| | 413 | but we highlight some statements: <itemizedlist> |
| | 414 | <listitem> |
| | 415 | <para>Implements=”Identifiable” means that the entity has the |
| | 416 | same properties as ‘Identifiable’, i.e. each entity has and |
| | 417 | auto-generated Id and a Name. This allows easy reuse of data |
| | 418 | structures. Note that 'Identifiable' itself is abstract, meaning |
| | 419 | that it is just used for modeling purposes only.</para> |
| | 420 | </listitem> |
| | 421 | |
| | 422 | <listitem> |
| | 423 | <para>type=”xref” and xref_field=”Experiment.Id” indicates that |
| | 424 | the field Experiment of Subject should cross reference (x ref) |
| | 425 | to an existing Experiment, using Id to uniquely identify this |
| | 426 | Experiment.</para> |
| | 427 | </listitem> |
| | 428 | |
| | 429 | <listitem> |
| | 430 | <para>Cross references are used to automatically link forms |
| | 431 | together, i.e. when viewing experiments only the related |
| | 432 | Subjects are shown using the subject.experiment to experiment.id |
| | 433 | cross references.</para> |
| | 434 | </listitem> |
| | 435 | </itemizedlist><figure> |
| | 436 | <title>Example of a data structure description</title> |
| | 437 | |
| | 438 | <graphic fileref="images/figure2.3.png" scalefit="1" width="100%" /> |
| | 439 | </figure></para> |
| | 440 | </sect1> |
| | 441 | |
| | 442 | <sect1> |
| | 443 | <title>Result.</title> |
| | 444 | |
| | 445 | <para>Generate and run your MOLGENIS as described in <link |
| | 446 | linkend="intro.generating">Chapter 1, section 2</link>. The expected |
| | 447 | result will now look like shown in the figure below (without the |
| | 448 | example data that we added to show how it works): [TODO replace with |
| | 449 | example showing also R and webservices interface]. And of course, if |
| | 450 | you don't like it yet you can edit the files above and regenerate in a |
| | 451 | few minutes.<figure> |
| | 452 | <title>Example of a generated MOLGENIS</title> |
| | 453 | |
| | 454 | <graphic fileref="images/figure2.4.png" scalefit="1" width="100%" /> |
| | 455 | </figure></para> |
| | 456 | </sect1> |
| | 457 | </chapter> |
| | 458 | </part> |
| | 459 | |
| | 460 | <part> |
| | 461 | <title>MOLGENIS little language reference</title> |
| | 462 | |
| | 463 | <chapter id="chapter.ref.db"> |
| | 464 | <title>The data model language</title> |
| | 465 | |
| | 466 | <subtitle>Description of XML elements and their usage.</subtitle> |
| | 467 | |
| | 468 | <sect1 id="ref.application"> |
| | 469 | <title><application></title> |
| | 470 | |
| | 471 | <para>Application contains the blueprint for the whole system. For |
| | 472 | example:</para> |
| | 473 | |
| | 474 | <example> |
| | 475 | <title>Using <application>.</title> |
| | 476 | |
| | 477 | <programlisting language="xml"> |
| | 478 | <molgenis name="myfirstdb" label="My First Database"> |
| | 479 | <menu name="mainmenu"> ... |
| | 480 | <entity name="firstentity"/> |
| | 481 | <module name="mymodule"/> |
| | 482 | ... |
| | 483 | </molgenis></programlisting> |
| | 484 | </example> |
| | 485 | |
| | 486 | <para>Optional attributes:</para> |
| | 487 | |
| | 488 | <itemizedlist> |
| | 489 | <listitem> |
| | 490 | <para>name="name": name of your MOLGENIS blueprint. This will be |
| | 491 | used by the generator to generate java packages.</para> |
| | 492 | </listitem> |
| | 493 | |
| | 494 | <listitem> |
| | 495 | <para>label="your label": Label of your MOLGENIS system. This will |
| | 496 | be shown on the screen as well as heading in the generated |
| | 497 | documentation.</para> |
| | 498 | </listitem> |
| | 499 | </itemizedlist> |
| | 500 | |
| | 501 | <para>Can contain:</para> |
| | 502 | |
| | 503 | <itemizedlist> |
| | 504 | <listitem> |
| | 505 | <para>Exactly one <menu> or one <form> as main |
| | 506 | screen.</para> |
| | 507 | </listitem> |
| | 508 | |
| | 509 | <listitem> |
| | 510 | <para>Zero or one <description> elements describing the |
| | 511 | application</para> |
| | 512 | </listitem> |
| | 513 | |
| | 514 | <listitem> |
| | 515 | <para>Many <entity> elements describing the data structure. |
| | 516 | See <link linkend="ref.entity"><entity></link></para> |
| | 517 | </listitem> |
| | 518 | |
| | 519 | <listitem> |
| | 520 | <para>Many <module> elements describing the data structure. |
| | 521 | These are containers to group <entity>.See <link |
| | 522 | linkend="ref.module"><module></link></para> |
| | 523 | </listitem> |
| | 524 | </itemizedlist> |
| | 525 | </sect1> |
| | 526 | |
| | 527 | <sect1 id="ref.entity"> |
| | 528 | <title><entity></title> |
| | 529 | |
| | 530 | <para>A entity defines the structure of a biological dat entity (i.e., |
| | 531 | a table in the database). For example:</para> |
| | 532 | |
| | 533 | <example> |
| | 534 | <title>Using <entity>.</title> |
| | 535 | |
| | 536 | <programlisting> |
| | 537 | <entity name="unique_name"> |
| | 538 | <description>Thisis my first entity.</description> |
| | 539 | <field name="name" type="string"/> |
| | 540 | <field name="investigation" type="string"/> |
| | 541 | <unique fields="name,investigation"/> |
| | 542 | </entity></programlisting> |
| | 543 | </example> |
| | 544 | |
| | 545 | <para>Required attributes:</para> |
| | 546 | |
| | 547 | <itemizedlist> |
| | 548 | <listitem> |
| | 549 | <para>name="name": globally unique name for this entity (within |
| | 550 | this blueprint).</para> |
| | 551 | </listitem> |
| | 552 | </itemizedlist> |
| | 553 | |
| | 554 | <para>Optional attributes:</para> |
| | 555 | |
| | 556 | <itemizedlist> |
| | 557 | <listitem> |
| | 558 | <para>label="Nice screen name": an user-friendly alias to show as |
| | 559 | form header (default: copied from name).</para> |
| | 560 | </listitem> |
| | 561 | |
| | 562 | <listitem> |
| | 563 | <para>extends="other_entity": you can use inheritance to make your |
| | 564 | entity inherit the fields of its 'superclass' using |
| | 565 | extends.</para> |
| | 566 | </listitem> |
| | 567 | |
| | 568 | <listitem> |
| | 569 | <para>abstract="true": you define what programmers call |
| | 570 | 'interfaces'. This are abstract objects that you can use as |
| | 571 | 'contract' for other entities to 'implement'..</para> |
| | 572 | </listitem> |
| | 573 | |
| | 574 | <listitem> |
| | 575 | <para>implements="abstract_entity": you can use inheritance to |
| | 576 | make your entity inherit the fields of its 'interface' using |
| | 577 | implements and refering to 'abstract' entities. The implemented |
| | 578 | fields are copied to this entity.</para> |
| | 579 | </listitem> |
| | 580 | |
| | 581 | <listitem> |
| | 582 | <para>decorator="package.class": you can add custom code to change |
| | 583 | the way entities are added, updated and removed. See the section |
| | 584 | on how to write a<link |
| | 585 | linkend="plugin.mapper.decorator">MappingDecorator</link>MappingDecorator |
| | 586 | plugin.</para> |
| | 587 | </listitem> |
| | 588 | </itemizedlist> |
| | 589 | |
| | 590 | <example> |
| | 591 | <title>Using inheritance: implements and extends</title> |
| | 592 | |
| | 593 | <programlisting> |
| | 594 | <entity name="bicycle"> |
| | 595 | <description>This my general entity</description> |
| | 596 | <field name="name" type="string"/> |
| | 597 | </entity> |
| | 598 | <entity name="mountainbike" extends="bicycle"> |
| | 599 | <description>This type of bicycle has a name, but also number of gears</description> |
| | 600 | <field name="numberOfGears" type="int"/> |
| | 601 | </entity></programlisting> |
| | 602 | </example> |
| | 603 | |
| | 604 | <para>Application can contain:</para> |
| | 605 | |
| | 606 | <itemizedlist> |
| | 607 | <listitem> |
| | 608 | <para>Zero or one <description> to describe this |
| | 609 | entity.</para> |
| | 610 | </listitem> |
| | 611 | |
| | 612 | <listitem> |
| | 613 | <para>One or more <field> that detail entity |
| | 614 | structure.</para> |
| | 615 | </listitem> |
| | 616 | |
| | 617 | <listitem> |
| | 618 | <para>Zero or more <unique> indicating unique constraints on |
| | 619 | field(s).</para> |
| | 620 | </listitem> |
| | 621 | </itemizedlist> |
| | 622 | </sect1> |
| | 623 | |
| | 624 | <sect1 id="ref.field"> |
| | 625 | <title><field></title> |
| | 626 | |
| | 627 | <para>A field defines one property of an entity (i.e., a table |
| | 628 | column). For example:</para> |
| | 629 | |
| | 630 | <example> |
| | 631 | <title>Using <field>.</title> |
| | 632 | |
| | 633 | <programlisting> |
| | 634 | <field name="unique_name" type="string" description="this is my first field"/> |
| | 635 | |
| | 636 | <field name="unique_name" type="xref" xref_field="entity_name.field_name"/> |
| | 637 | |
| | 638 | <field name="unique_name" type="enum" enum_options="[option1,option2]"/></programlisting> |
| | 639 | </example> |
| | 640 | |
| | 641 | <para>Required attributes:</para> |
| | 642 | |
| | 643 | <itemizedlist> |
| | 644 | <listitem> |
| | 645 | <para>name="name": locally unique name for this entity (within |
| | 646 | this entity).</para> |
| | 647 | </listitem> |
| | 648 | |
| | 649 | <listitem> |
| | 650 | <para>type="type": define the type of data that can be stored in |
| | 651 | this field, either:</para> |
| | 652 | |
| | 653 | <itemizedlist> |
| | 654 | <listitem> |
| | 655 | <para>type="string": a single line text string of variable |
| | 656 | length, max 255 chars.</para> |
| | 657 | </listitem> |
| | 658 | |
| | 659 | <listitem> |
| | 660 | <para>type="int": a natural number.</para> |
| | 661 | </listitem> |
| | 662 | |
| | 663 | <listitem> |
| | 664 | <para>type="boolean": a boolean.</para> |
| | 665 | </listitem> |
| | 666 | |
| | 667 | <listitem> |
| | 668 | <para>type="decimal": a decimal number.</para> |
| | 669 | </listitem> |
| | 670 | |
| | 671 | <listitem> |
| | 672 | <para>type="date": a date.</para> |
| | 673 | </listitem> |
| | 674 | |
| | 675 | <listitem> |
| | 676 | <para>type="datetime": a date that includes the time.</para> |
| | 677 | </listitem> |
| | 678 | |
| | 679 | <listitem> |
| | 680 | <para>type="file": attaches a file to the entity.</para> |
| | 681 | </listitem> |
| | 682 | |
| | 683 | <listitem> |
| | 684 | <para>type="text": a multiline textarea of max 2gb.</para> |
| | 685 | </listitem> |
| | 686 | |
| | 687 | <listitem> |
| | 688 | <para>type="xref": references to a field in another entity |
| | 689 | specified by xref_field attribute (required for xref). This |
| | 690 | will be shown as variable lookup-list.</para> |
| | 691 | </listitem> |
| | 692 | |
| | 693 | <listitem> |
| | 694 | <para>type="mref": many-to-many references to a field in |
| | 695 | another entity specified by xref_field attribute (required for |
| | 696 | mref). This will be shown as multiple select lookup-list. |
| | 697 | (Under the hood, a link table is generated)</para> |
| | 698 | </listitem> |
| | 699 | |
| | 700 | <listitem> |
| | 701 | <para>type="enum": references to a fixed look-up list options, |
| | 702 | specificed by enum_options attribute (required for |
| | 703 | enum)</para> |
| | 704 | </listitem> |
| | 705 | </itemizedlist> |
| | 706 | </listitem> |
| | 707 | </itemizedlist> |
| | 708 | |
| | 709 | <para>Optional attributes:</para> |
| | 710 | |
| | 711 | <itemizedlist> |
| | 712 | <listitem> |
| | 713 | <para>label="Nice screen name": an user-friendly alias to show as |
| | 714 | form header (default: copied from name).</para> |
| | 715 | </listitem> |
| | 716 | |
| | 717 | <listitem> |
| | 718 | <para>unique="true": values of this field must be unique within |
| | 719 | the entity (default: "false")</para> |
| | 720 | </listitem> |
| | 721 | |
| | 722 | <listitem> |
| | 723 | <para>nillable="true": this field can be left blank (default: |
| | 724 | "false")</para> |
| | 725 | </listitem> |
| | 726 | |
| | 727 | <listitem> |
| | 728 | <para>readonly="true": this field cannot be edited once they are |
| | 729 | saved (default: "false")</para> |
| | 730 | </listitem> |
| | 731 | |
| | 732 | <listitem> |
| | 733 | <para>length="n" (string only): limits the length of a string to |
| | 734 | 1<=n<=255 (default: "255").</para> |
| | 735 | </listitem> |
| | 736 | |
| | 737 | <listitem> |
| | 738 | <para>xref_field="entityname.fieldname": specifies a entity and |
| | 739 | field that this xref field must reference to, separated by '.' |
| | 740 | (default: required for xref)</para> |
| | 741 | </listitem> |
| | 742 | |
| | 743 | <listitem> |
| | 744 | <para>xref_label="{afield} {anotherfield}": makes labels for the |
| | 745 | xref options based on fields of the referenced entity, indicated |
| | 746 | between '{}' (default: copied from xref_field).</para> |
| | 747 | </listitem> |
| | 748 | |
| | 749 | <listitem> |
| | 750 | <para>enum_options"[value1,value2]": the fixed list of options for |
| | 751 | this enum (default: required for enum).</para> |
| | 752 | </listitem> |
| | 753 | |
| | 754 | <listitem> |
| | 755 | <para>description="One line description": describes this field |
| | 756 | which the user can see when (s)he mouses over the field (default: |
| | 757 | "").</para> |
| | 758 | </listitem> |
| | 759 | </itemizedlist> |
| | 760 | |
| | 761 | <para>Field can contain no other elements:</para> |
| | 762 | </sect1> |
| | 763 | |
| | 764 | <sect1 id="ref.unique"> |
| | 765 | <title><unique>.</title> |
| | 766 | |
| | 767 | <para>A unique defines which properties of an entity (i.e., table |
| | 768 | columns) should be unique. There are two ways to make a field |
| | 769 | unique.</para> |
| | 770 | |
| | 771 | <para>A single column is unique:</para> |
| | 772 | |
| | 773 | <example> |
| | 774 | <title>Using <unique> on single columns.</title> |
| | 775 | |
| | 776 | <programlisting> |
| | 777 | <molgenis> |
| | 778 | <entity name="entity1"> |
| | 779 | <field name="f1" type="string" unique="true"/> |
| | 780 | <field name="f2" type="string"/> |
| | 781 | <field name="f3" type="string"/> |
| | 782 | </entity> |
| | 783 | </molgenis></programlisting> |
| | 784 | </example> |
| | 785 | |
| | 786 | <para>Explanation: field "f1" is made unique via unique="true". This |
| | 787 | means that there cannot be two entities with f1="x"</para> |
| | 788 | |
| | 789 | <para>The combination of two or more columns is unique:</para> |
| | 790 | |
| | 791 | <example> |
| | 792 | <title>Using <unique> over multiple columns.</title> |
| | 793 | |
| | 794 | <programlisting> |
| | 795 | <molgenis> |
| | 796 | <entity name="entity1"> |
| | 797 | <field name="f1" type="string"/> |
| | 798 | <field name="f2" type="string"/> |
| | 799 | <field name="f3" type="string"/> |
| | 800 | <unique fields="f1,f2"/> |
| | 801 | </entity> |
| | 802 | </molgenis></programlisting> |
| | 803 | </example> |
| | 804 | |
| | 805 | <para>Explanation: The combination of "f1" and "f2" is unique. This |
| | 806 | means that there can be two entities with f1="x" but only if the |
| | 807 | values for f2 differ.</para> |
| | 808 | |
| | 809 | <para>Required attributes:</para> |
| | 810 | |
| | 811 | <itemizedlist> |
| | 812 | <listitem> |
| | 813 | <para>field="field1,field2": a comma separated list of unique |
| | 814 | fields.</para> |
| | 815 | </listitem> |
| | 816 | </itemizedlist> |
| | 817 | |
| | 818 | <para>Note: You can add as many unique constraints you like.</para> |
| | 819 | </sect1> |
| | 820 | |
| | 821 | <sect1 id="ref.module"> |
| | 822 | <title><module></title> |
| | 823 | |
| | 824 | <para>A module can be used to group entities in your model. This will |
| | 825 | show up in the generated documentation.</para> |
| | 826 | |
| | 827 | <example> |
| | 828 | <title>Using <module> to group entities.</title> |
| | 829 | |
| | 830 | <programlisting> |
| | 831 | <molgenis> |
| | 832 | <module name="module1"> |
| | 833 | <description>This is my first module</description> |
| | 834 | <entity name="entity1"> |
| | 835 | <field name="f1" type="string" unique="true"/> |
| | 836 | <field name="f2" type="string"/> |
| | 837 | <field name="f3" type="string"/> |
| | 838 | </entity> |
| | 839 | <entity name="entity2"> |
| | 840 | <field name="f1" type="string" unique="true"/> |
| | 841 | <field name="f2" type="string"/> |
| | 842 | <field name="f3" type="string"/> |
| | 843 | </entity> |
| | 844 | </module> |
| | 845 | </molgenis></programlisting> |
| | 846 | </example> |
| | 847 | </sect1> |
| | 848 | </chapter> |
| | 849 | |
| | 850 | <chapter id="chapter.ref.ui"> |
| | 851 | <title>The user interface language</title> |
| | 852 | |
| | 853 | <sect1 id="ref.form"> |
| | 854 | <title><form></title> |
| | 855 | |
| | 856 | <para>A form shows the records of its entity on screen. A form may |
| | 857 | have tabbed (menu) or un-tabbed (form) subscreens. For example:</para> |
| | 858 | |
| | 859 | <example> |
| | 860 | <title>Using <form>.</title> |
| | 861 | |
| | 862 | <programlisting> |
| | 863 | <form name="myname" entity="myentity"> |
| | 864 | <form name="myname" entity="mysubentity"/> |
| | 865 | </form> |
| | 866 | |
| | 867 | <form name="myname" entity="myentity" viewtype="list" limit="10"/></programlisting> |
| | 868 | </example> |
| | 869 | |
| | 870 | <para>Required attributes:</para> |
| | 871 | |
| | 872 | <itemizedlist> |
| | 873 | <listitem> |
| | 874 | <para>name="name": locally unique name for this screen element |
| | 875 | (within its container).</para> |
| | 876 | </listitem> |
| | 877 | |
| | 878 | <listitem> |
| | 879 | <para>entity="myentity": which data entity will be loaded (i.e., |
| | 880 | points to a <entity name="myentity"/>).</para> |
| | 881 | </listitem> |
| | 882 | </itemizedlist> |
| | 883 | |
| | 884 | <para>Optional attributes:</para> |
| | 885 | |
| | 886 | <itemizedlist> |
| | 887 | <listitem> |
| | 888 | <para>label="Nice screen name": an user-friendly alias to show as |
| | 889 | form header (default: copied from name).</para> |
| | 890 | </listitem> |
| | 891 | |
| | 892 | <listitem> |
| | 893 | <para>viewtype="record" or viewtype="list": whether the form |
| | 894 | should start with a list or per-record (default: "record").</para> |
| | 895 | </listitem> |
| | 896 | |
| | 897 | <listitem> |
| | 898 | <para>limit="10": how many records must be shown in the list |
| | 899 | (default: "5").</para> |
| | 900 | </listitem> |
| | 901 | |
| | 902 | <listitem> |
| | 903 | <para>readonly="true": can the records be edited or is the form |
| | 904 | readonly (default: "false").</para> |
| | 905 | </listitem> |
| | 906 | </itemizedlist> |
| | 907 | |
| | 908 | <para>Application can contain:</para> |
| | 909 | |
| | 910 | <itemizedlist> |
| | 911 | <listitem> |
| | 912 | <para>Zero or more <menu> as subscreen(s).</para> |
| | 913 | </listitem> |
| | 914 | |
| | 915 | <listitem> |
| | 916 | <para>Zero or more <form> as subscreen(s).</para> |
| | 917 | </listitem> |
| | 918 | </itemizedlist> |
| | 919 | </sect1> |
| | 920 | |
| | 921 | <sect1 id="ref.menu"> |
| | 922 | <title><menu></title> |
| | 923 | |
| | 924 | <para>A menu shows tabs on screen for each contained subscreen |
| | 925 | (menu,form). For example:</para> |
| | 926 | |
| | 927 | <example> |
| | 928 | <title>Using <menu>.</title> |
| | 929 | |
| | 930 | <programlisting> |
| | 931 | <menu name="menuname"> |
| | 932 | <form name="myfirsttab" entity="formentity"/> |
| | 933 | <menu name="mysecondtab">... |
| | 934 | <form name="mythirdtab" entity="formentity"/> |
| | 935 | </menu> </programlisting> |
| | 936 | </example> |
| | 937 | |
| | 938 | <para>Required attibutes:</para> |
| | 939 | |
| | 940 | <itemizedlist> |
| | 941 | <listitem> |
| | 942 | <para>name="menuname": locally unique name for this screen element |
| | 943 | (within its container).</para> |
| | 944 | </listitem> |
| | 945 | </itemizedlist> |
| | 946 | |
| | 947 | <para>Optional attributes:</para> |
| | 948 | |
| | 949 | <itemizedlist> |
| | 950 | <listitem> |
| | 951 | <para>startswith="mysubelement": subscreen tab that is selected |
| | 952 | when menu is first shown (default: first subscreen).</para> |
| | 953 | </listitem> |
| | 954 | </itemizedlist> |
| | 955 | |
| | 956 | <para>Application can contain:</para> |
| | 957 | |
| | 958 | <itemizedlist> |
| | 959 | <listitem> |
| | 960 | <para>Zero or more <menu> as subscreen(s).</para> |
| | 961 | </listitem> |
| | 962 | |
| | 963 | <listitem> |
| | 964 | <para>Zero or more <form> as subscreen(s).</para> |
| | 965 | </listitem> |
| | 966 | </itemizedlist> |
| | 967 | </sect1> |
| | 968 | |
| | 969 | <sect1 id="ref.plugin"> |
| | 970 | <title><plugin></title> |
| | 971 | |
| | 972 | <para>A entity defines the structure of a biological dat entity (i.e., |
| | 973 | a table in the database). For example:</para> |
| | 974 | |
| | 975 | <example> |
| | 976 | <title>Using <plugin> example.</title> |
| | 977 | |
| | 978 | <programlisting> |
| | 979 | <plugin name="MyPlugin" type="plugins.myplugin.MyPluginScreen"/> |
| | 980 | </programlisting> |
| | 981 | </example> |
| | 982 | |
| | 983 | <para>Required attributes:</para> |
| | 984 | |
| | 985 | <itemizedlist> |
| | 986 | <listitem> |
| | 987 | <para>name="name": globally unique name for this entity (within |
| | 988 | this blueprint).</para> |
| | 989 | </listitem> |
| | 990 | |
| | 991 | <listitem> |
| | 992 | <para>type="package.class": reference to a java class in your |
| | 993 | handwritten/java folder. If it doesn't exist a boilerplate class |
| | 994 | will be auto-generated for you. See the section on <link |
| | 995 | linkend="plugin.screen">Plugin</link> screens to see how to edit |
| | 996 | this file.</para> |
| | 997 | </listitem> |
| | 998 | </itemizedlist> |
| | 999 | |
| | 1000 | <para>Optional attributes:</para> |
| | 1001 | |
| | 1002 | <itemizedlist> |
| | 1003 | <listitem> |
| | 1004 | <para>label="Nice screen name": an user-friendly alias to show as |
| | 1005 | form header (default: copied from name).</para> |
| | 1006 | </listitem> |
| | 1007 | </itemizedlist> |
| | 1008 | |
| | 1009 | <para></para> |
| | 1010 | </sect1> |
| | 1011 | </chapter> |
| | 1012 | |
| | 1013 | <chapter> |
| | 1014 | <title>Adding custom plug-ins to the generated software</title> |
| | 1015 | |
| | 1016 | <sect1> |
| | 1017 | <title>Introduction</title> |
| | 1018 | |
| | 1019 | <para>See the examples in the molgenis distro. At the moment there are |
| | 1020 | two types of plug-ins.</para> |
| | 1021 | |
| | 1022 | <itemizedlist> |
| | 1023 | <listitem> |
| | 1024 | <para>Plugin of a screen</para> |
| | 1025 | </listitem> |
| | 1026 | |
| | 1027 | <listitem> |
| | 1028 | <para>MapperDecorator to change what happens when 'add', 'update' |
| | 1029 | or 'delete' is called</para> |
| | 1030 | </listitem> |
| | 1031 | </itemizedlist> |
| | 1032 | |
| | 1033 | <para>Alternatively, you can also move generated code to the |
| | 1034 | handwritten section and edit that (advanced users).</para> |
| | 1035 | </sect1> |
| | 1036 | |
| | 1037 | <sect1 id="plugin.screen"> |
| | 1038 | <title>Adding a plug-in screen</title> |
| | 1039 | |
| | 1040 | <para>This feature allows you to produce a custom screen that does |
| | 1041 | whatever you want it to do. The procedure consists of three |
| | 1042 | steps:</para> |
| | 1043 | |
| | 1044 | <orderedlist> |
| | 1045 | <listitem> |
| | 1046 | <para><emphasis role="bold">Add the plugin to the model. |
| | 1047 | </emphasis>Describe where you want to put your plugin in the |
| | 1048 | MOLGENIS 'UI' XML. The plugin 'type' points to a java class that |
| | 1049 | is typically stored in handwritten/java.</para> |
| | 1050 | |
| | 1051 | <programlisting><molgenis> |
| | 1052 | <plugin name="MyPlugin" type="plugins.myplugin.MyPluginScreen" /> |
| | 1053 | </molgenis></programlisting> |
| | 1054 | |
| | 1055 | <para>When you now run the generator an 'boilerplate'' screen |
| | 1056 | plugin class will be generated inside the folder handwritten/java |
| | 1057 | (unless the file allready consists). In this case a class called |
| | 1058 | 'plugins.myplugin.MyPluginScreen.java'. Next to that also a layout |
| | 1059 | template is generated to layout the contents of your plugin in |
| | 1060 | 'plugins.myplugin.MyPluginScreen.ftl'. </para> |
| | 1061 | </listitem> |
| | 1062 | |
| | 1063 | <listitem> |
| | 1064 | <para><emphasis role="bold">Edit the plugin class. </emphasis>The |
| | 1065 | following empty plugin class is generated for you to change to |
| | 1066 | make it do whatever you want (its name depends on you plugin class |
| | 1067 | name):</para> |
| | 1068 | |
| | 1069 | <programlisting>package plugins.myplugin; |
| | 1070 | |
| | 1071 | import org.molgenis.assets.screen.Screen; |
| | 1072 | import org.molgenis.assets.screen.plugin.PluginScreen; |
| | 1073 | import org.molgenis.util.Tuple; |
| | 1074 | |
| | 1075 | public class MyPluginScreen extends PluginScreen |
| | 1076 | { |
| | 1077 | public MyPluginScreen(String name, Screen parent) |
| | 1078 | { |
| | 1079 | super(name, parent); |
| | 1080 | } |
| | 1081 | |
| | 1082 | @Override |
| | 1083 | public String getViewName() |
| | 1084 | { |
| | 1085 | return "plugins_myplugin_MyPluginScreen"; |
| | 1086 | } |
| | 1087 | |
| | 1088 | @Override |
| | 1089 | public String getViewTemplate() |
| | 1090 | { |
| | 1091 | return "plugins/myplugin/MyPluginScreen.ftl"; |
| | 1092 | } |
| | 1093 | |
| | 1094 | @Override |
| | 1095 | public void handleRequest(Tuple request) |
| | 1096 | { |
| | 1097 | |
| | 1098 | try |
| | 1099 | { |
| | 1100 | Database db = this.getDatabase(); |
| | 1101 | //String action = request.getString("__action"); |
| | 1102 | // |
| | 1103 | //if( action.equals("do_add") ) |
| | 1104 | //{ |
| | 1105 | // Experiment e = new Experiment(); |
| | 1106 | // //read the request directly into the entity using matching field/input names |
| | 1107 | // e.set(request); |
| | 1108 | // db.add(e); |
| | 1109 | //} |
| | 1110 | } |
| | 1111 | catch(Exception e) |
| | 1112 | { |
| | 1113 | //... |
| | 1114 | } |
| | 1115 | |
| | 1116 | } |
| | 1117 | |
| | 1118 | @Override |
| | 1119 | public void reload() |
| | 1120 | { |
| | 1121 | try |
| | 1122 | { |
| | 1123 | Database db = this.getDatabase(); |
| | 1124 | //Query q = db.query(Experiment.class); |
| | 1125 | //q.like("name", "test"); |
| | 1126 | //List<Experiment> recentExperiments = q.find(); |
| | 1127 | // |
| | 1128 | ////do something |
| | 1129 | } |
| | 1130 | catch(Exception e) |
| | 1131 | { |
| | 1132 | //... |
| | 1133 | } |
| | 1134 | } |
| | 1135 | }</programlisting> |
| | 1136 | |
| | 1137 | <para>Edit the function 'handleRequest' to process user requests. |
| | 1138 | A simple 'helloWorld' example is commented out. Edit the function |
| | 1139 | 'reload' to indicate what needs to be done if the page is reloaded |
| | 1140 | by the user (so, after a handleRequest). This function is |
| | 1141 | typically us ined to retrieve data from the database. Again, a |
| | 1142 | simple 'helloWorld' example is in the comments.</para> |
| | 1143 | </listitem> |
| | 1144 | |
| | 1145 | <listitem> |
| | 1146 | <para><emphasis role="bold">Edit the plugin layout.</emphasis>The |
| | 1147 | following empty layout template is generated for you. This |
| | 1148 | template is written using the Freemarker language (<ulink |
| | 1149 | url="???">http://freemarker.org/docs/index.html</ulink>) and |
| | 1150 | allows you to change to layout it in the way you like (its name |
| | 1151 | depends on you plugin class name):</para> |
| | 1152 | |
| | 1153 | <programlisting><#macro plugins_myplugin_MyPluginScreen> |
| | 1154 | <#assign model = screen.model> |
| | 1155 | <!-- normally you make one big form for the whole plugin--> |
| | 1156 | <form method="post" enctype="multipart/form-data" name="${screen.name}"> |
| | 1157 | <!--needed in every form: to redirect the request to the right screen--> |
| | 1158 | <input type="hidden" name="__target" value="${screen.name}"" /> |
| | 1159 | <!--needed in every form: to define the action. This can be set by the submit button--> |
| | 1160 | <input type="hidden" name="__action" /> |
| | 1161 | |
| | 1162 | <!-- this shows a title and border --> |
| | 1163 | <div class="formscreen"> |
| | 1164 | <div class="form_header" id="${screen.getName()}"> |
| | 1165 | ${screen.label} |
| | 1166 | </div> |
| | 1167 | <div class="screenbody"> |
| | 1168 | <div class="screenpadding"> |
| | 1169 | <#--begin your plugin--> |
| | 1170 | |
| | 1171 | <input name="myinput" value="${screen.getMyValue()}"> |
| | 1172 | <input type="submit" value="Change name" onclick="__action.value='do_myaction';return true;"/> |
| | 1173 | |
| | 1174 | <#--end of your plugin--> |
| | 1175 | </div> |
| | 1176 | </div> |
| | 1177 | </div> |
| | 1178 | </form> |
| | 1179 | </#macro> |
| | 1180 | </programlisting> |
| | 1181 | |
| | 1182 | <para>Notice that an html form is already generated for you, |
| | 1183 | including some basic layout. In MOLGENIS, a form must always have |
| | 1184 | two hidden parameters called __target and __action: </para> |
| | 1185 | |
| | 1186 | <itemizedlist> |
| | 1187 | <listitem> |
| | 1188 | <para>The __target parameter routes any user request back to |
| | 1189 | you plugin class (using the screen name, in this example |
| | 1190 | 'MyPlugin'). </para> |
| | 1191 | </listitem> |
| | 1192 | |
| | 1193 | <listitem> |
| | 1194 | <para>The __action parameter is not actually required but has |
| | 1195 | been a good design pattern to simplify event handling when |
| | 1196 | your plugin has multiple buttons. Then, each action button has |
| | 1197 | a small piece of 'onclick' javascript to set the value of the |
| | 1198 | action before submit (return true makes the submit go forward. |
| | 1199 | </para> |
| | 1200 | </listitem> |
| | 1201 | </itemizedlist> |
| | 1202 | |
| | 1203 | <para>For example here:</para> |
| | 1204 | |
| | 1205 | <programlisting><input type="submit" value="Change name" onclick="__action.value='do_myaction';return true;"/></programlisting> |
| | 1206 | </listitem> |
| | 1207 | </orderedlist> |
| | 1208 | </sect1> |
| | 1209 | |
| | 1210 | <sect1 id="plugin.mapper.decorator"> |
| | 1211 | <title>Adding a mapping decorator</title> |
| | 1212 | |
| | 1213 | <para>Sometimes you want to slightly alter the default behavior of the |
| | 1214 | MOLGENIS add, update and delete functions, e.g. to check certain |
| | 1215 | contraints, or to automatically process a attached file of data. In |
| | 1216 | MOLGENIS, when an entity object is saved it goes through a so-called |
| | 1217 | mapper that translates the object to e.g. the mySql database. Using |
| | 1218 | 'MappingDecorator' is possible to plug-in a decorator to change that |
| | 1219 | behaviour.The procedure consists of two steps:</para> |
| | 1220 | |
| | 1221 | <orderedlist> |
| | 1222 | <listitem> |
| | 1223 | <para><emphasis role="bold">Add the plugin to the model. |
| | 1224 | </emphasis>Describe which entity you want to decorate in the |
| | 1225 | MOLGENIS 'DB' XML. The 'decorator' attribute' points to a java |
| | 1226 | class should be stored iin handwritten/java.</para> |
| | 1227 | |
| | 1228 | <programlisting> <molgenis> |
| | 1229 | ... |
| | 1230 | <entity name="MyEntity" decorator="my.decorators.MyEntityMapperDecorator"> |
| | 1231 | ... |
| | 1232 | </entity> |
| | 1233 | ... |
| | 1234 | </molgenis></programlisting> |
| | 1235 | |
| | 1236 | <para>When you now run the generator an 'empty' decorator plugin |
| | 1237 | class will be generated inside the folder handwritten/java (unless |
| | 1238 | the file allready consists). In this case a class called |
| | 1239 | 'my.decorators.MyEntityMapperDecorator'.</para> |
| | 1240 | </listitem> |
| | 1241 | |
| | 1242 | <listitem> |
| | 1243 | <para><emphasis role="bold">Edit the plugin class. </emphasis>The |
| | 1244 | following empty plugin class is generated (its name depends on you |
| | 1245 | plugin class name as stated in 'decorator' above). Just add code |
| | 1246 | before or after the 'super' calls to change the pre/post update |
| | 1247 | behavior of your database. The commented sections give pointers on |
| | 1248 | how that can work:<programlisting>public class MyEntityMapperDecorator extends MappingDecorator<example.data.types.MyEntity> |
| | 1249 | { |
| | 1250 | //JDBCMapper is the generated class that we change in this plugin |
| | 1251 | public MyEntityMapperDecorator(JDBCMapper generatedMapper) |
| | 1252 | { |
| | 1253 | super(generatedMapper); |
| | 1254 | } |
| | 1255 | |
| | 1256 | @Override |
| | 1257 | public int add(List<example.data.types.MyEntity> entities) throws SQLException, DatabaseException |
| | 1258 | { |
| | 1259 | // add your pre-processing here, e.g. |
| | 1260 | // for (example.data.types.MyEntity e : entities) |
| | 1261 | // { |
| | 1262 | // e.setTriggeredField("Before add called!!!"); |
| | 1263 | // } |
| | 1264 | |
| | 1265 | // here we call the standard 'add' |
| | 1266 | int count = super.add(entities); |
| | 1267 | |
| | 1268 | // add your post-processing here |
| | 1269 | // if you throw and exception the previous add will be rolled back |
| | 1270 | |
| | 1271 | return count; |
| | 1272 | } |
| | 1273 | |
| | 1274 | @Override |
| | 1275 | public int update(List<example.data.types.MyEntity> entities) throws SQLException |
| | 1276 | { |
| | 1277 | |
| | 1278 | // add your pre-processing here, e.g. |
| | 1279 | // for (example.data.types.MyEntity e : entities) |
| | 1280 | // { |
| | 1281 | // e.setTriggeredField("Before update called!!!"); |
| | 1282 | // } |
| | 1283 | |
| | 1284 | // here we call the standard 'update' |
| | 1285 | int count = super.update(entities); |
| | 1286 | |
| | 1287 | // add your post-processing here |
| | 1288 | // if you throw and exception the previous add will be rolled back |
| | 1289 | |
| | 1290 | return count; |
| | 1291 | } |
| | 1292 | |
| | 1293 | @Override |
| | 1294 | public int remove(List<example.data.types.MyEntity> entities) throws SQLException |
| | 1295 | { |
| | 1296 | // add your pre-processing here |
| | 1297 | |
| | 1298 | // here we call the standard 'remove' |
| | 1299 | int count = super.remove(entities); |
| | 1300 | |
| | 1301 | // add your post-processing here, e.g. |
| | 1302 | // if(true) throw new SQLException("Because of a post trigger the remove is cancelled."); |
| | 1303 | |
| | 1304 | return count; |
| | 1305 | } |
| | 1306 | } |
| | 1307 | </programlisting></para> |
| | 1308 | </listitem> |
| | 1309 | </orderedlist> |
| | 1310 | </sect1> |
| | 1311 | |
| | 1312 | <sect1> |
| | 1313 | <title>Java API basics</title> |
| | 1314 | |
| | 1315 | <para>TODO</para> |
| | 1316 | </sect1> |
| | 1317 | </chapter> |
| | 1318 | </part> |
| | 1319 | |
| | 1320 | <!-- |
| | 1321 | <part> |
| | 1322 | <title>MOLGENIS end user manual.</title> |
| | 1323 | <subtitle>How to use a MOLGENIS instance.</subtitle> |
| | 1324 | <chapter> |
| | 1325 | <title>Using the user interface</title> |
| | 1326 | <sect1> |
| | 1327 | <title>TODO</title> |
| | 1328 | <para/> |
| | 1329 | </sect1> |
| | 1330 | </chapter> |
| | 1331 | <chapter> |
| | 1332 | <title>Using the R interface</title> |
| | 1333 | <sect1> |
| | 1334 | <title>TODO</title> |
| | 1335 | <para/> |
| | 1336 | </sect1> |
| | 1337 | </chapter> |
| | 1338 | <chapter> |
| | 1339 | <title>Using the Web service interface</title> |
| | 1340 | <sect1> |
| | 1341 | <title>TODO</title> |
| | 1342 | <para/> |
| | 1343 | </sect1> |
| | 1344 | </chapter> |
| | 1345 | <chapter> |
| | 1346 | <title>Using the tab delimited file import/export</title> |
| | 1347 | <sect1> |
| | 1348 | <title>TODO</title> |
| | 1349 | <para/> |
| | 1350 | </sect1> |
| | 1351 | </chapter> |
| | 1352 | <chapter> |
| | 1353 | <title>FAQ</title> |
| | 1354 | <sect1> |
| | 1355 | <title>TODO</title> |
| | 1356 | <para/> |
| | 1357 | </sect1> |
| | 1358 | </chapter> |
| | 1359 | </part>--> |
| | 1360 | </book> |
| | 1361 | |
| | 1362 | }}} |
