Version 1 (modified by jannekevdp@…, 3 years ago)

--

=Technical Documentation=

==Javascript Classes== The DbNP Project contains several Javascript classes which can dynamically add functionality to the pages which are developed. All of these classes rely on the jQuery library so make sure jQuery is available before using any of these classes. Note that I am using the Grails notation of including Javascript as the whole project is built in  Grails. Note that I tend to use ( yui compressed) minified Javascript and css for the production version of the application using an if statement.

===Ontology Chooser=== The Ontology Chooser integrates with the  NCBO Ontologies and build upon the jQuery-ui autocomplete functionality.

====Code==== Source can be found here:  ontology-chooser.js  ontology-chooser.min.js

====Usage==== First require the Ontology Chooser Javascript code in your project (note the minified Javascript):

<g:if env="production"> <script type="text/javascript" src="${resource(dir: 'js', file: 'ontology-chooser.min.js')}"></script> </g:if><g:else> <script type="text/javascript" src="${resource(dir: 'js', file: 'ontology-chooser.js')}"></script> </g:else>

Within your page, you can define your form text input fields to be ontology fields by adding a rel tag:

<input type="text" name="..." rel="ontologies-all" /> <input type="text" name="..." rel="ontologies-1132" /> <input type="text" name="..." rel="ontologies-1000,1031" />

The first input element will use all available ontologies, while the second one only uses the  NCBI Species Ontology which has Ontology ID 1132. The third uses two ontologies, both  Mouse adult gross anatomy (Ontology ID: 1000) as well as  Mouse pathology (Ontology ID: 1031). All available ontologies can be found at the  NCBO BioPortal.

To actually attach the Ontology Chooser to the ontology fields you need to instantiate the Ontology Chooser using Javascript like this:

// initialize the ontology chooser new OntologyChooser?().init();

Note that you should do this when the DOM ( Document Object Model) is ready otherwise it will not work properly. So probably you would require the following code in order to do so:

<script type="text/javascript"> // jQuery way to execute code when DOM is ready $(function() {

// initialize the ontology chooser new OntologyChooser?().init();

} </script>

====After initialization==== After initializing the ontology fields and selecting one of the provided suggestions in the ontology autocomplete list, three hidden fields will be automatically inserted (if they do not yet exist) into the DOM. Or (if they do exist) their values will be changed accordingly:

<input type="hidden" name="fieldName-concept_id" value="..."/> <input type="hidden" name="fieldName-ontology_id" value="..."/> <input type="hidden" name="fieldName-full_id" value="..."/>

Where fieldName is the name of the corresponding ontology field.

Upon selecting one of the provided suggestions these hidden fields will be filled

====CSS==== The following style sheet elements are used by the ontology chooser. This CSS is already included in the default application wide stylesheet. However, if one would like to implement this somewhere else, this CSS can be used to tweak the look and feel:

.ui-autocomplete .ui-menu-item {

font-size: 10px;

} .ui-autocomplete .about {

font-size: 8px; color: #006DBA;

} .ui-autocomplete .from {

font-size: 8px; color: #666;

}

====Example==== A screenshot of what the above example looks like:<br /> [[Image:dbnp-ontology-all.png]]<br />

If the name of this fields was myOntology the three hidden fields accompanying this ontology field would look like this (upon selecting the first suggestion):

<input type="hidden" name="myOntology-concept_id" value="A_Mouse" /> <input type="hidden" name="myOntology-ontology_id" value="42693" /> <input type="hidden" name="myOntology-full_id" value=" http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#A_Mouse" />

====Advanced Example==== For more advanced behavior, the Ontology Chooser can be instantiated to automatically show and hide a DOM element. This functionality is useful for showing a submit button when there are search results and the user has actually selected one of the results, or hide the submit button when there are no results. You can use this by instantiating the Ontology Chooser like this:

$(function() {

// initialize the ontology chooser new OntologyChooser?().init({showHide: $('div#button')});

});

with -for example- the following HTML / GSP (Grails / Groovy Server Pages):

&lt;div id="termForm"&gt;

&lt;g:form action="pages" name="wizardForm" id="wizardForm"&gt;

&lt;div id="label"&gt;search term: &lt;/div&gt; &lt;div id="term"&gt;&lt;g:textField name="term" rel="ontology-${ontologies}" size="40" /&gt;&lt;/div&gt; &lt;div id="button"&gt;&lt;g:submitButton name="add" value="Add term" /&gt;&lt;/div&gt;

&lt;/g:form&gt;

&lt;/div&gt;

===Select Add More=== Select Add More is a Javascript class which is able to dynamically insert an entry to a select element which -upon selecting- causes a jQuery-ui dialog window to open. The look & feel and behaviour can be defined according to your needs.

====Code==== Source can be found here:  SelectAddMore.js  SelectAddMore.min.js

====Usage==== First require the Javascript code in your project (note the minified Javascript):

<g:if env="production"> <script type="text/javascript" src="${resource(dir: 'js', file: 'SelectAddMore?.min.js')}"></script> </g:if><g:else> <script type="text/javascript" src="${resource(dir: 'js', file: 'SelectAddMore?.js')}"></script> </g:else>

Within your page enter the select element with a user defined rel tag (in this example, we use template as a rel tag):

<select name="template" rel="template" entity="pass-this-on-to-the-dialog">

<option selected="selected" value=""></option> <option value="Academic study">Academic study</option>

</select>

This select element lists an empty option and an 'Academic study' option. Using the Javascript it is possible to dynamically extend this select element with a third 'add / modify...' option which -when selected- opens a jQuery-ui dialog. In order to do so, initialize the SelectAddMore? Javascript class specifying the rel tag of your select element, and specifying what URL to open in the dialog:

// handle template selects new SelectAddMore?().init({

rel : 'template', url : '/gscf/templateEditor', vars : 'entity', // can be a comma separated list of variable names to pass on label : 'add / modify..', style : 'modify', onClose : function(scope) {

refreshWebFlow();

}

});

Note that this should be done after the DOM is ready (see the ontology chooser how to do that).

This code will insert an option with 'add / modify..' as a label, and when selecting it a jQuery dialog will be opened with url '/gscf/templateEditor' and passing '?entity=...' as get variable (as defined by the vars argument). Whenever the dialog is closed, the onClose function is executed.

====GSCF Grails example==== Instead of writing the select element yourself, within the GSCF template you could also write the following code which automatically renders a select element with rel='template. Note that this results in a (Blowfish) encrypted entity for security sake:

<wizard:templateElement name="template" description="Template" entity="${dbnp.studycapturing.Study}" addDummy="true">

The template to use for this study

</wizard:templateElement>

====CSS==== The actual style which is used by the Javascript class is user definable. In the example above the class is instantiated with the modify class. Below is the css for this example:

option.modify {

background: url(../images/icons/famfamfam/layout_add.png) no-repeat left top; background-color: #333; padding-left: 18px; height: 16px; color: #fff; font-weight: bold;

}

====Example==== A screenshot of what the above example looks like:<br /> [[Image:SelectAddMore.png]]

And upon selecting the dialog will fire (developmental screenshot):<br /> [[Image:SelectAddMore.dialog.png]]

===Table Editor=== The table editor provides multi-edit functionality to tables. These tables are defined as a set of HTML elements which -in the user interface- show a table. This can be the table element, but could as well be a set of div elements.

====Code==== Source can be found here:  table-editor.js  table-editor.min.js

====Usage==== First require the Javascript code in your project (note the minified Javascript):

<g:if env="production"> <script type="text/javascript" src="${resource(dir: 'js', file: 'table-editor.min.js')}"></script> </g:if><g:else> <script type="text/javascript" src="${resource(dir: 'js', file: 'table-editor.js')}"></script> </g:else>

Second, define a table containing input elements in your html or code:

&lt;div class="table"&gt;

&lt;div class="row"&gt;

&lt;div class="column"&gt;row 1 column 1&lt;/div&gt; &lt;div class="column"&gt;&lt;input type=... name=.../&gt;&lt;/div&gt; &lt;div class="column"&gt;&lt;select name=.../&gt;&lt;/div&gt; ... &lt;div class="column"&gt;&lt;input type=... name=.../&gt;&lt;/div&gt;

&lt;/div&gt; ... &lt;div class="row"&gt;

&lt;div class="column"&gt;row N column 1&lt;/div&gt; &lt;div class="column"&gt;&lt;input type=... name=.../&gt;&lt;/div&gt; &lt;div class="column"&gt;&lt;select name=.../&gt;&lt;/div&gt; ... &lt;div class="column"&gt;&lt;input type=... name=.../&gt;&lt;/div&gt;

&lt;/div&gt;

&lt;/div&gt;

And instantiate the table editor to make the rows multi-selectable and make any changes made in any input field replicate to selected rows to speed up editing:

new TableEditor?().init('div.table', 'div.row', 'div.column');

Note that this should be done after the DOM is ready (see the ontology chooser how to do that).

====Example==== A screenshot of what it would look like:<br /> [[Image:TableEditor.png]]<br /> Selected rows are in orange, and changes replicate to the other selected rows.

Attachments