Skip to content

Deployment

Jump to bottom
pawelld edited this page Sep 23, 2015 · 9 revisions

WeBIAS applications are described by XML definitions, which contain parameter form layout and details on calling the actual program.

XML definition

Sample app definition.

<bias>
    <application id="Test" name="Test" info="Hello World.">
        <description>
                This is the simplest application.
        </description>
        <author>Bioexploratorium</author>
        <email>pawel@bioexploratorium.pl</email>
        <setup>
            <help_url>/media/test-help.html</help_url>
            <param_template>/var/www/WeBIAS/examples/test.py --name="${name.PCDATA}" --mood=${mood.PCDATA}</param_template>
            <param_table_template>examples/Test/param_table.genshi</param_table_template>
        </setup>
    
        <parameters>
            <email/>
            <section id="SectionInput" title="Test application"/>
            <text id="name" name="Name" tip="What is you name?" info="name" optional="no" help="#name"/>

            <select id="mood" name="How are you?" info="mood" optional="no" tip="C'mon, just tell me." help="#mood" >
                <option value="0" text="Fine, thanks."/>
                <option value="1" text="Not bad."/>
                <option value="2" text="Don't even ask."/>
                <option value="3" text="Go away you insensitive clod."/>
            </select>
        </parameters>
    </application>
</bias>

A single XML file may contain several definitions. An application is described by the <application> tag which has to have the following elements and attributes:

Name Description
Attributes
id Id used internally
info Short description presented in the application list
name Named presented to users
Elements
acl A Python list containing roles and/or a set of users allowed to access the application
author Author's name
email Author's e-mail
parameters Description of parameters (see below)
setup Location of files and other information (see below)

The <setup> tag

The <setup> tag contains the following elements:

Name Optional Description
help_url NO URL of the help page
module YES A name of the Python module containing extensions (e.g. fields) required by the application (all modules should be put in the modules directory)
output_files YES A space separated list of wildcards of files which may result from the computation and should be stored with the result
param_table_template YES A name of a custom Genshi template for presenting query
param_template NO A Genshi template converting an XML description of a query into a command line
result_template YES A name of a custom Genshi template of the page presenting query results (param_table_template and result_table_template are embedded in the default template of the results page)
result_table_template YES A name of a custom Genshi template for presenting results

Available form fields

Single value

There are several types of fields for entering single values corresponding to different kinds of form elements (text input, checkbox, dropdown box), as well as different data types. All of them require following attributes:

Name Default value Description
default "" Default value
id N/A Tag name which will be used in XML representation of a query
info N/A Field name to be used in error messages
name N/A Field label
optional "no" Flag indicating if field is optional
tooltip N/A Tooltip to be shown when user hovers over form element

The following field types are supported:

Name Description
checkbox Yes or no choice
email Field for entering submitters e-mail address. No attributes are required. Will be shown only for anonymous users.
file File upload
integer Integer value
float Float value
select Dropdown box. Should contain option tags with attributes value and text.
text Text value of arbitrary length

Special fields

Currently WeBIAS supports the following:

PDB structure

This field type may be used to input a molecular structure from file or a database code. In both cases the actual file is stored with the query. Apart from the regular attributes this field also accepts the source attribute which is a comma delimited list containing sources of structures. It may include:

  • SCOP - a SCOP accession code will be accepted
  • PDB - a PDB code will be accepted
  • file - arbitrary files may be uploaded

Form fields allowing upload and text input will be shown according to the source attribute.

This field type requires BioPython.

Groups

In some cases it is beneficial to have a certain set of parameters to behave as a single entity. For example it may be desirable to have two mutually exclusive parameters (only one may be supplied), or two optional parameters that have to be entered both at the same time. This functionality may be achieved using a parameter group. It is described by a group tag which contains parameters belonging to the group and may have the following attributes:

Name Default value Description
grouptype N/A Type of the group ("OR", "XOR" or "AND")
help N/A Text to be appended to help_url (If not given, help link for this field will not be rendered.)
id N/A Tag name which will be used in XML representation of a query
info N/A Name to be used in error messages
optional "no" Flag indicating if field is optional
title "" Caption rendered at the top of the frame
tooltip N/A Tooltip to be shown when user hovers over form element

Validation of the parameter groups proceeds as follows:

  1. Each of the group elements is validated. If any turns out to be invalid (i.e. contains wrong input or is not optional and empty), the group is considered invalid.
  2. If the group is optional and all its elements are empty, it is considered valid.
  3. Depending on the group type and the number of non empty elements it is valid when:
    1. grouptype is "AND" and all elements are not empty
    2. grouptype is "OR" and at least one element is not empty
    3. grouptype is "XOR" and exactly one element is not empty

Parameter groups may be nested.

Variable number of parameters

It is possible to render forms with a variable number of parameters. It may be particularly useful if an application is capable to operate on an arbitrary number of files or other arguments. The <vargroup> tag is similar in syntax to the <group> tag described above. It should contain one or more parameters. If several parameters are used, they behave like in AND group during validation. The <vargroup> tag may have the following attributes:

Name Default value Description
help N/A Text to be appended to help_url (If not given, help link for this field will not be rendered.)
id N/A Tag name which will be used in XML representation of a query
info N/A Name to be used in error messages
max no limit Max. number of parameters
min 0 Min. number of parameters
optional "no" Flag indicating if field is optional
title "" Caption rendered at the top of the frame
tooltip N/A Tooltip to be shown when user hovers over form element

Other

Form elements may be also organized by dividing them into sections. Such division is only used for rendering and may be achieved by using a <section> tag. This tag is rendered as a divisor between parameters and cannot contain any elements. Accepted attributes:

Name Default value Description
help N/A Text to be appended to (If not given, help link for this field will not be rendered.)
info N/A Name to be used in error messages
title "" Caption rendered at the top of the frame
tooltip N/A Tooltip to be shown when user hovers over form element

XML representation of queries and results

Actual parameters are internally represented in XML format. Each single value or group parameter is encoded with a tag with a name given by parameter id. Group nesting is preserved. Additionally tags are given a type attribute with values: value, file, group. If a parameter belongs to a variable group it is also given an index attribute (NOTE: only parameters directly contained in a <vargroup> tag may have this attribute. This guarantees consistent behavior, when variable groups are nested.). Results of computations should be returned in the same format. Sample query in XML format:

<query>
    <name type="value">John</name>;
    <mood type="value">0</mood>;
</query>

Templates for presenting parameters and results

WeBIAS provides generic means for presenting parameters and results. They are designed to render all values encoded in XML format with rudimentary formatting reflecting nesting of group parameters. File values are rendered as links to actual files. Most likely these templates are sufficient only for simplest applications and prototyping. It is strongly encouraged to develop templates specifically tailored to actual applications. WeBIAS uses a Genshi templating engine. XML data is parsed using Gnosis XML Parser and made accessible through query and result objects. A sample template for rendering query parameters is presented below:

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" py:strip="">
    <div id="center">
        <?python
            dict=["Fine, thanks.", "Not bad.", "Don't even ask.", "Go away you insensitive clod."]
        ?>
   
        <p><em>Q:</em>What is your name?</p>
        <p><em>A:</em>${query.tree.name.PCDATA}</p>
  
        <p><em>Q:</em>How are you?</p>
        <p><em>A:</em>${dict[int(query.tree.mood.PCDATA)]}</p>
    </div>
</html>

Grouping applications

Applications may be organized in a tree-like structures. It is achieved by defining application groups which have the following syntax:

<appgroup id="Examples" name="Examples" info="WeBIAS examples">
    <description>
        WeBIAS examples.
    </description>
    <appgroupentry appid="Test"/>
    <appgroupentry appid="groups"/>
    <appgroupentry appid="vargroups"/>
</appgroup>

The appid attribute in a appgroupentry tag may contain an ID of an application or a group. All elements which do not belong to any group will be rendered at a root level. Definitions of application groups may appear in application definition files or in a special file - apps/server_map.xml. Only groups containing at least one enabled (and available to the user) application will be rendered.

Static content

Static files such as CSS styles, JavaScript files, images as well as other files required for published applications may be put in the media subdirectory. Whenever it is necessary to publish HTML content embedded in the portal layout, a page template may be put in the templates/page directory. A template file called example.genshi has the following URL: APP_ROOT+'/page/example'. This feature may be used for publishing documentation for particular applications. Files in the media directory of a server override those installed with a WeBIAS package.

Clone this wiki locally