Form Basics

Introduction
Form Structure

Introduction

The forms for data entry are managed through one main XML file - botany.views.xml. There may also be form layouts in common.views.xml, in general, if it is being edited for use at RBGE it has been moved to botany.views.xml.

The xml files have two main sections:

Views
ViewDefs

The Views section is rarely edited. In part this is used to control whether the default view is a table or a grid. The ViewDefs section is where the layout of the form is done.

The xml document contains the layouts for all the forms we have worked on at RBGE and is quite difficult to navigate. I have tried to improve this by ordering all the forms alphabetically, grouping related forms where needed (e.g. Gift, GiftAgent, GiftPreparation). I have added a list at the top of the file to show what is included in it. I have also added headings to make it possible to search for a particular part using SECTION:[form].

Commented out code is indicated by 

Form structure

Heading

A section of a form is bracketed by

<viewdef 
            type="form"
            name="AccessionAgent"
            class="edu.ku.brc.specify.datamodel.AccessionAgent"
            gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
            settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
            <desc><![CDATA[The Accession form.]]></desc>
            <enableRules/> 
...

</viewdef>

type:'form' 'formtable'
name:name of the table in the Specify schema
class: not edited
gettable: not edited
settable: not edited
<desc>: description of the form, used in views. CDATA[] indicates that the text in [] is character data and is not to be treated as XML
<enableRules>: some forms have information filled in from the base form. Generally not edited.

Column Layout

The next section lays out the spacing of the sections of the form:

            <columnDef>105px,2px,453px,5px,110px,2px,155px,p:g</columnDef>
            <columnDef os="lnx">135px,2px,520px,5px,98px,2px,155px,p:g</columnDef>
            <columnDef os="mac">130px,2px,551px,5px,153px,2px,189px,p:g</columnDef>
            <columnDef os="exp">p,2px,p,5px,85px,2px,p:g(2),p:g</columnDef>
            <rowDef auto="true" cell="p" sep="2px"/>

The first four rows are for layouts for different Operating Systems:

Windows
Linux
Mac
Elastic

All follow the same format.

2 data entry fields:

Label	Space	Field	Space	Label	Space	Label
105px	2px	453px	5px	110px	2px	155px	p:g

3 data entry fields:

Label	Space	Field	Space	Label	Space	Field	Space	Label	Space	Field			p:g
100px	2px	125px	5px	75px	2px	128px	5px	80px	2px	140px	35px	0px	p:g

If any adjustments need to be made to the size of either the label or field length, the total number of pixels has to remain the same. Often there are some 'spare' pixels at the end of a row (e.g. 35px in the 3 field example). This can be used to add/remove pixels from other sections.

Adjustments should be made to all OS options. In general try and keep the proportions of each section the same.

Certain field types require a minimum length of field e.g. Query Combo Boxes, so this needs to be taken into consideration when changing field sizes.

Rows

The rows of a form are defined in the section betwen <rows>...</rows>

The content for each individual row is between <row>...</row>. The total number of fields in a row can't be greater than the number of columns defined at the top of each form section.

            <rows>
                <row>
                    <cell type="label" labelfor="1"/>
                    <cell type="field" id="1" name="agent" uitype="querycbx" initialize="name=Agent;title=Agent"/>
                    <cell type="label" labelfor="2"/>
                    <cell type="field" id="2" name="role" uitype="combobox"/>
                </row>
                <row>
                    <cell type="label" labelfor="remarks"/>
                    <cell type="field" id="remarks" name="remarks" uitype="textareabrief" rows="2" colspan="6"/>
                </row>
            </rows>

Labels

Most field types have a label, Tick boxes are an exception to this (see Field Types). It forms a pair with the definition for the field type.

<cell type="label" labelfor="3"/>

cell type="label" defines that this is a label rather than a field 'labelfor="remarks"` is equal to the id in the field row

QueryCombo Box

<cell type="label" labelfor="borrowAgent"/>
<cell type="field" id="borrowAgent" name="agent" uitype="querycbx" initialize="name=Agent;title=Agent"/>

Picklist

<cell type="label" labelfor="method"/>
<cell type="field" id="method" name="text1" uitype="combobox"/>

Text

<cell type="label" labelfor="description"/>
<cell type="field" id="description" name="text1" uitype="text" colspan="5"/>

Text Area

<cell type="label" labelfor="remarks"/>
<cell type="field" id="remarks" name="remarks" uitype="textareabrief" rows="2" colspan="6"/>

Number

<cell type="label" labelfor="numberOfParcels"/>
<cell type="field" id="numberOfParcels" name="number2" uitype="text"/>

Integer

<cell type="label" labelfor="numPackages"/>
<cell type="field" id="numPackages" name="integer1" uitype="text"/>

Date

Without precision

<cell type="label" labelfor="dateClosed"/>
<cell type="field" id="dateClosed" name="dateClosed" uitype="formattedtext" uifieldformatter="Date" default="today"/>

With precision

<cell type="label" labelfor="detDate"/>
<cell type="field" id="detDate" uitype="plugin" name="this" initialize="name=PartialDateUI;df=determinedDate;tp=determinedDatePrecision" uifieldformatter="Date"/>

###Tickbox

<cell type="field" id="transfer" uitype="checkbox" name="yesNo2" initialize="editable=true"/>

Spinner

<cell type="label" labelfor="quantity"/>
<cell type="field" id="quantity" name="quantity" uitype="spinner" initialize="max=2000"/>

Timestamp

<cell type="label" labelfor="timestampCreated"/>
<cell type="field" id="timestampCreated" name="timestampCreated" uitype="label" readonly="true"/>

Subview

<cell type="subview" viewname="AgentSpecialty" id="AgentSpeciality" name="agentSpecialties" colspan="19"/>

Seperator

With text:

<cell type="separator" label="Attachments" colspan="19"/>

Without text:

<cell type="separator" label="" colspan="19"/>

Field Modifiers

Readonly

readonly="true" the field will display data, but it will not be editable by the user, e.g. Legacy Number from BG-BASE. uitype="label" will display the data as if it were a label (darker text)

Colspan

colspan="" field will span number of columns specied between "". Count the number of columns, including spaces, specified in the column layout. If the number is higher than the number of available columns it will cause an error when the form is imported into Specify

Rows

rows="" field will run over the number of rows specified between "".

Set Default View to Table

The table or grid isn't always the default view for some sub-forms, however it can be a more useful way to see a summary of the information.

To change the view from form to grid:

Add defaulttype="table" to the subview code

e.g.

<row>
     <cell type="subview" viewname="Determination" id="6" name="determinations" defaulttype="table" colspan="13" rows="5"/>
</row>

Create a new viewdef by copying the viewdef from the main view for the table. Change:

type="formtable"
name
<desc>

Main view:

     type="form"
     name="Determination Abridged"
     class="edu.ku.brc.specify.datamodel.Determination"
     gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
     settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
     <desc><![CDATA[Determination subform for Collection Object form.]]></desc>
     <enableRules/>

Table/Grid view:

<viewdef
     type="formtable"
     name="Determination Table"
     class="edu.ku.brc.specify.datamodel.Determination"
     gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
     settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
     <desc><![CDATA[Determination subform table for Collection Object form.]]></desc>
     <definition>Determination</definition>
</viewdef>

In the views section at the top of the page, copy and paste the two rows (to give a total of 4). Change the altview name to match the name in the viewdef, change the viewdef to match the name of the viewdef in the viewdefs section of the xml file. In the example below an additional viewdef was created to hold an abridged version of the data, so this is what is named in the view:

<view name="Determination"
     class="edu.ku.brc.specify.datamodel.Determination"
     busrules="edu.ku.brc.specify.datamodel.busrules.DeterminationBusRules" 
     isexternal="true"
     resourcelabels="false">
     <desc><![CDATA[Subform within the Collection Object form.]]></desc>
     <altviews>
          <altview name="Determination Table View" viewdef="Determination Abridged Table" mode="view"/>
          <altview name="Determination Table Edit" viewdef="Determination Abridged Table" mode="edit"/>
          <altview name="Determination View" viewdef="Determination" mode="view"/>
          <altview name="Determination Edit" viewdef="Determination" mode="edit" default="true"/>
     </altviews>
</view>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly