Note: If you are looking for instructions on how to edit forms in Specify, please see this guide! The fundamentals of form modification are the same between Specify 6 and 7. The entire form system is documented for Specify 7 on the GitHub Wiki for advanced users.
Using Forms in Specify 7
A form is a page or dialog in which data can be viewed, entered, or edited. Specify categorizes forms as Data forms, which are used to enter collection data, and Interactions, which are used to record transactions of either data or collection objects.
Each discipline has access to a set of forms for both data and interactions, specific to their discipline. The following sections describe basic concepts for using the form system. A separate section of help exists for both Data and Interactions forms.
Note: At this time, Specify 7 does not include a visual form editing tool. You can edit any form by creating and/or modifying the view definitions in the App Resources viewer.
It is important to note that the forms have been created to be extremely flexible. Forms can reside at any level of the hierarchy shown below:
By default, view definitions are pulled from the Discipline level in Specify, which means that all Collections within a Discipline access the same default forms, but custom form sets can be reimported at any institutional level. You can see all the default forms in this directory that can be downloaded, modified, and reimported in the app resource viewer.
For instance, the default form set for a discipline could be exported, edited, and reimported at a collection level, allowing all users in that collection to use the new set of forms.
Members of the Specify Collections Consortium may contact our help desk at email@example.com for help editing their forms.
More on Editing Forms
The names of tables and fields used for display within Specify, (labels), can be edited using the Schema Config tool.
Specify 7 reads column definitions from the
<columnDef os="lnx"> tag (or
<columnDef> as a fallback if the first one is missing).
<columnDef>100px,2px,195px,5px,86px,2px,210px,5px,74px,2px,146px,15px,p:g </columnDef> <columnDef os="lnx"> 115px,2px,195px,5px,125px,2px,210px,5px,125px,2px,131px,15px,p:g </columnDef> <columnDef os="mac"> 130px,2px,215px,5px,138px,2px,260px,5px,138px,2px,155px,15px,p:g </columnDef> <columnDef os="exp">p,2px,min(p;220px),5px:g,p,2px,p,5px:g,p,2px,200px,p,p:g </columnDef>
Note: You can see in-depth documentation of the form system available on the GitHub Wiki.
For compatibility reasons with Specify 6, every other column in the definition string is ignored (those are used as column separators in Specify 6).
Thus, for the following string
115px,2px,195px,5px,125px,2px,210px,5px,125px,2px,131px,15px,p:g, only these columns would be rendered:
Each column that is defined like
115px is interpreted as a fixed width in pixels in Specify 6, but Specify 7 interprets those as fractions instead to make forms more flexible. Somewhat technical introduction to fractions.
If column is not defined as a pixel value (i.e,
p or any other value), its size would be dynamically determined based on the content within it. It may be desirable to define all columns as automatically sized to make column sizes flexible.
Specify includes extensive controls for limiting access to data for each user. Specify reads the permissions for the user based on their roles and policies configured in the Security & Accounts panel, then displays the correct tables and tools based on these permissions.
Forms are categorized for the data that resides in each table (Collection Object, Taxon, Geography, etc.); however, much of the data within the tables is also linked to related tables. This prevents users from needing to retype the same information and assures that information is entered only one way (for example John Smith is not also entered as J. Smith or John Smyth). Separating data into fields within tables with relationships also allows data to be searched in a more precise way.
A relationship involving a primary and related table in which many primary records are linked to a single related record in the related table is referred to as having a many-to-one relationship. For example, many Collection Object records might be linked to the same Locality record because the specimens were all found at the same location.
Related tables with a many-to-one relationship to the primary table are represented on the form as a formatted field with buttons to edit, add and search for a record within the table. The field format typically consists of one primary field within the table, but may be represented by more than one field typically separated by a comma.
A relationship involving a primary and related table in which a single primary record links to many related records in the related table is referred to as a one-to-many relationship. For example, several Collection Object records would be linked to a single record in the Collection Event table because all the specimens were collected during the same event.
Query Combo Box
Related tables with a many-to-one relationship display on a form as a Query Combo Box.
There are control buttons next to the Query Combo Box that each active a specific action in a dialog:
Edit – Allow editing the currently selected record
Add – Create a new record in the related table
Search – Search for records in the related table
Related tables with a one-to-many relationship to the primary table are included on the form as a sub form with navigation controls.
Data is added and edited in sub forms the same way that it is added and edited to forms. Boxes are used in the same way and required fields have a bold label.
These can be displayed in two ways:
Specify’s forms use a variety of boxes, buttons, and panels to enter and display data, called controls.
At the top of each subview, you can see a :plus: and icon to the right of the relationship’s name (Determinations is the name of the
determinations field in the Schema Config in this database, and it is being represented as a subview).
The :plus: creates new records in that relationship (i.e. adding a new determination or preparation) and will automatically open the new form in the subview.
The will delete the record in the relationship.
Navigation is present on sub forms that are part of the main form, but only when viewed as a Form, not as a Grid.
≪ navigates to the first record in the set
< goes to the previous record in the set
> goes to the next record in the set
≫ navigates to the last record in the set
You can select the first number to activate a hidden number field. You can enter any number in the set (i.e. 1, 2, 150, 220) and you will immediately jump to that record.
The icon brings up the form meta menu which enables advanced form display options for the user.
The meta menu enables the user to:
- Configuring carry forward on a field-by-field basis
- Enable or disable auto-numbering
- Customizing Form type (autogenerated or predefined)
- Inspecting the edit history of a record
- Querying on tree usages
- Querying on pick list usages
- Forms can now be switched temporarily to read-only mode
- Setting subview sort order
- Switching subviews between grid or subform display format
- Opening the Form definition
- Copying a link to a Collection Object record
- Field labels can be disabled temporarily, displaying the database field names instead
- The ability to run a report/label for a given record on any table
Main Form Control
By default, the table icon will appear in the top left of the form.
To the right of the table name, you will see the “formatted” display of that record. See instructions on how to edit a table format for more information.
Inside a Record Set
Navigation control within a record set is found at the top of each form. The controls for the paginator are the same as explanined above.
Number boxes accept any numerical input. Simply click in the box or use the Tab key to apply focus in the box, then type in the numerical data. The box will not accept any characters except for numeric input.
Text boxes accept any type of input. Simply click in the box or use the Tab key to apply focus in the box, then type in the data.
Note: To change the length of a Text and/or Number Box choose System > Schema Configuration.
Query Combo Box
A Query Combo Box represents a many-to-one relationship with another record in another table. Data for each record in the table is formatted to display enough fields within the table for the desired record to be recognized within a list of records.
A Query Combo Box used to represent the Taxon, Geography, Storage, Lithostratigraphy and Chronostratigraphy tables will use the format for the Full Name, which is configured in the Taxon Tree Definition.
The Query Combo Box allows data to be searched and chosen from a related table, not typed directly into the box. Data chosen from the list links the current record with a record in a related table. This eliminates the need to retype data. It is possible to type data directly into the box, but the box will not accept the data; the data must first be added to the table by clicking the :plus: button and creating a new record.
Choose data from a list:
- Type the first letter, or first few letters of the term you wish to use in the box, then either click on the down button or use the down-arrow key on the keyboard. A list of data starting with the typed letter(s) will appear.
- If Specify can not find a match based on the typed letters, then an button will appear. Click the button or press the enter key to add a new record.
- If the required data is not in the resulting list, either press the enter key when ‘Add’ is in focus, or click the :plus: button, to add a new record.
- Pressing the Esc key will cancel the list box.
Note: Type more letters into the box to reduce the results and expedite the search.
Search for existing data:
Click on the button. A search dialog will appear. The fields visible in this form search dialog depend on the type of table. For example, here is the Agent search dialog:
You can use the full Query Builder from the dialog! This offers greater flexibility in your record discovery.
Type in either the entire name or the first few letters of the search followed by an asterisk (*).
Select a record from the results.
Enter a new record:
- Click on the :plus: button and enter data into the resulting dialog.
Or edit an existing record:
- Choose the record in the list.
- Click the button to open the record in an editable dialog.
Combo boxes are used to display Pick Lists, which allow data to be chosen from a predefined set of options, not typed directly into the box.
- Click on the ⌄ icon on the right, or ↓ key to open the list.
- Click on data to select it or press the enter key when the desired data is in focus.
Date fields require a formatted date and give a prompt for the accepted format.
This includes Full Date, Partial Date, and Year. This can be set in the form definition to be a relative date or an absolute date.
Type the date as shown in the box.
- Choose Full Date for complete dates.
- Choose Mon / Year for incomplete dates which include the month and year.
- Choose Year for incomplete dates which include just the year.
Large Text Field
The large text field is a text field that occupies two rows by default and can be expanded by dragging the bottom right corner.
* Partial dates need to be stored as valid dates in the database (as day, month and year, Specify will use 01 for any missing data. For example, a partial date that displays as 07/2020 is stored in the database as 01/07/2020 and a partial date of 2020 is stored in the database as 01/01/2020. Therefore, if an exact date of 01/01/2020 is queried the partial date (2020) will be included in the return data.
Note: The default for the date format is Full Date, but this can be changed by editing the field on the form. For instance, if you only wish to input the Year it is possible to set the form default to Year and input the data without having to click on the Date Combo Box and select Year.
In most Collection Object forms the Cataloged Date is editable, but if it is left blank it is automatically set to the current date upon saving the record.
In most Collection Object forms, the Cataloger field is editable in the first new record, then automatically added and not editable in any additional forms created by clicking the add :plus: button. To enter a new Cataloger simply click the Data Entry icon in the Taskbar to open a new Collection Object form.
Formatted Number Fields
Any string can be formatted to a numbering scheme in System > Schema Configuration. Typical fields that are formatted with a numbering scheme are Catalog Number, Accession Number, Loan Number and Gift Number. Once these fields are formatted, they can either be entered manually or auto increment using Auto Numbering.
Timestamp Modified is found at the bottom of the Collection Object form for most Disciplines, and is the date the record was modified. This is not an editable field on a form but it is important to note that it is a searchable field.
Data Entry Fields
Fields that accept data are Data Entry fields. These fields may also be required.
In the above screenshot, Preferred Taxon is read-only while Taxon is editable.
Fields that are read only (not editable) automatically load pre-determined information. You can see that these fields are not editable by the field background that matches the form background.
Examples of these fields are the Collection Name field in the Collection Object form and the Children fields in the Geography, Taxon, Storage, Lithostratigraphy and Chronostratigraphy tables that are also displayed/edited as Trees.
Fields that are required, have a light blue (configurable in user preferences) background. Records can not be saved (the save button for the form will not become enabled) until all required fields contain proper data.
A warning will appear at the bottom of any incomplete required field.
Specify adopts the standard keyboard functions for entering data on forms via keyboard entry. Examples of keyboard strokes for the form controls are described in the control section. The following are a few guidelines:
Tab moves the focus to the next field.
Shift + Tab moves the focus to the previous field.
Spacebar activates a button when selected.
Esc (escape key) closes a combo box.
Return selects a highlighted item within a list.
Ctrl + Enter will save a record or Query.
Ctrl/⌘ + C will copy data within a field.
Ctrl/⌘ + V will paste data into a field.
Ctrl/⌘ + X will delete and copy the data.
Ctrl/⌘ + Z will undo the last action.
Ctrl/⌘ + Y will redo the last action.
Note: All browser keyboard shortcuts will work as expected. These are dependent on your browser and operating system.
If the keyboard functions are not working properly, try to click somewhere else in the application and change the ‘focus’.
Carry forward allows you to configure the clone behavior on a per-field basis. You can select fields (that are not enforced unique) that you wish to preserve when using the Carry Forward functionality in Specify. This extends to entire relationships.
Read more about Carry Forward in the Form Meta Menu documentation.
You can configure Auto Numbering on a per-field basis. In this instance, only the catalog number is auto numbering in this form.
Read more about configuring auto numbering in the Form Meta Menu documentation.
Specify treats the bar code reader as an ordinary data entry device. No special configuration within Specify is necessary. Refer to your bar code reader documentation for instructions on how to install and configure the bar code reader. Once the bar code reader is successfully installed and configured, it should work automatically in Specify 7.
- Activate the Catalog Number field within the Collection Object form by clicking in it.
- Scan the bar code.
- Activate the Search box by clicking in it.
- Scan the bar code.
- Activate a Loan, Gift or Information Request by choosing it in the Interactions Sidebar, this will activate a Catalog Number dialog.
How Editing Affects Related Records
Records that are related, or linked, to other records can not be deleted. For example, a Preparation that is linked to specific Collection Objects can not be deleted while the link and/or Collection Object exists. To delete the Preparation, first edit each Collection Object record and remove the Preparation.
When related records are edited, the data changes in each record that references that data. For example, if the spelling of a name in the Last Name field is changed in the Agent record, the spelling will also change in the Deaccession Agents, Loan Agents, Authors and other records.
Note: Only users with add and edit privileges will be offered the add and edit button on their form.
The following example shows the steps to delete a Collection Object record with Catalog Number 100.
Use Simple Search or the Query Builder to find the Collection Object where Cat # = 100.
Simple Search results with results for Catalog Number 100
Click on the link out icon to navigate to that record.
Click the Delete button in the bottom left of the form.
You can then confirm that you want to permanently delete the item from the database.
Note: There may be records that reference the record you are attempting to delete. In those instances, you can navigate to the records blocking the deletion and evaluate if you should proceed with the deletion process.
If you wish to continue, you must remove the referenced records before deleting the original record.