Editing Forms

[Specify]

Specify 7

Note: If you are looking to modify your forms in Specify 7, the fundamentals of the Specify 6 guide still apply. We recommend first-time editors use the Specify 6 guide to become familiar with the basics of this process before moving into Specify 7.

Form definitions can be modified in the App Resources viewer in Specify 7. Form definitions can be created and edited at any rank in the institutional hierarchy. The forms are applied in ascending order (User, User Type, Collection, Discipline, Division, Institution).

• Institution
  • Division
    • Discipline
      • Collection
        • User Type
          • User

Default Views

Since Specify 7’s web interface does not have the traditional views files to view and modify, we reccomend downloading your discipline specific views from the GitHub Specify 6 repository.

common.views.xml and global.views.xml contain commonly used tables.

That is, they are tables that are shared by most of the disciplines. For example, the Accession table is in the common.views.xml file. Removing the status field from the Accession table will remove the field in the Accession table for every discipline, unless you copy over the <view> and <viewdef> components into your discipline-specific form definition before making changes.

The commonly used tables were not divided between the two files according to any particular rationale; therefore there is no way to intuit what table will be in either without checking.

• Discipline-specific views

  • botany.views.xml

  • fish.views.xml

  • mammals.views.xml

  • vascplant.views.xml

  • vertpaleo.views.xml

  • reptile.views.xml

  • invertpaleo.views.xml

  • invertebrate.views.xml

  • ento.views.xml

  • herpetology.views.xml

  • bird.views.xml

• common.views.xml
• global.views.xml

Only in Specify 7:

Form definitions are cached by the browser. After any changes to the form definition, users may be required to clean cache for the changes to be reflected. To do that, open a form that was changed, then click on your user name to open the User Tools menu. There, select “Clear Browser Cache” and restart the page afterward.

When editing forms, it is very helpful to see the data model. Each Specify instance comes with a data model viewer. To open it, press on your user name to open the User Tools menu. Then, select “Data Model” under “Developer Tools”. The data model viewer shows data model version that is currently used by your database.

Alternatively, you can use the data model viewer from our demo server: https://sp7demofish.specifycloud.org/specify/datamodel/.

Forms can be edited using the embedded resource editor or using an external XML editor. To access form definitions for your database, click on your user name to open the User Tools menu. Then, select “Resources” from the list and then “View Sets” in the subsequent dialog. Then, select the appropriate view definition file from the sidebar (click on any header to expand it)

Specify 7 form system is largely compatible with Specify 6. It offers lots of flexibility for the placement of fields on the form, enabling plugins and adding subforms/grids. Our wiki houses a general overview of how the form definition system works, which should be a helpful guide for editing form definitions.

7 reads column definitions from the <columnDef os="lnx"> tag ( or <columnDef> as a fallback if the lnx one is missing).

In Specify 7, rather than reading the fixed width in pixels as in Specify 6, it interprets those as fractions instead to make forms more flexible. Somewhat technical introduction to fractions.

When editing the forms, it is essential to find the database field names. You can view the Specify schema while editing the forms to make the process much easier!

` Important: Detailed documentation for the form system in Specify 7 is available on the GitHub Wiki.

---

Specify 6

There are two main means of altering Specify’s forms: using tools in Specify and by editing the code for the forms. Both means have advantages and drawbacks. The tools in Specify offer the ability to make form alterations user-friendly. However, the changes that can be made are severely limited. Editing the code offers the ability to make many more changes but it is not a user-friendly format. For more complex changes such as adding a subview, you will need to contact Specify for assistance. Directions for creating a Query combo box is given in a separate document.

Once Forms have been edited, they must be imported into Specify in order to keep the edited forms from being overwritten. Instructions for importing forms are at the end of the document.

Editing tools in Specify

The main tool provided for editing forms in Specify is the Schema Configuration. Changes made in the Schema Configuration are applied to the collection open at the time of the changes. The changes are not applied to other disciplines but it will be applied to all collections in a single discipline. For example, if the discipline Mammals has two collections, Terrestrial Mammals and Marine Mammals, a change made in the Schema Configuration will affect both collections but it will not affect the Herpetology discipline.

There are four main changes that can be made using Specify’s Schema Localizer; field and table caption changes, hide or unhide a table or field, make a field required, and assign a pick list.

Another more minor editing tool is the Pick List Editor. Although pick lists can be assigned through the Schema Localizer, editing the contents of the picklist is done using the Pick List Editor. (Making a field into a pick list can only be done by editing the code, described below.)

A. The Schema Configuration

Editing the Schema Configuration

Important: If you are looking for the Specify 7 Schema Config instructions, please see this article instead. Editing the Schema Configuration “Schema” or “Interface Schema” in this context refers to the many data tables and fields that reflect the semantics and relationships of the data types processed by biological collections. The Schema Configuration module is a highly functional, though somewhat complex, set of tools created to configure the Specify (interface) schema for individual disc…

To get to the Schema Configuration:

1. In the top menu bar, go to System → Schema Configuration…

2. In the resulting window, highlight the appropriate language by clicking it and click Edit a Schema.

Important - Bear in mind that subviews (sometimes referred to as subforms) are their own table. The fields available for the subview may be different from the form itself. The subview may be listed under the fields available, but the fields available in the subview will not. For example, Address of Record will be listed as a field for the Exchange Out table. However, Address, City, State, etc. will not be listed under the Exchange Out table; they will be listed under the Address of Record table.

See also:

Field Formatting and Auto-Numbering

Specify 6 offers a highly flexible formatting and auto-numbering capability. Many institutions require a specific format for particular identification fields such as Catalog Number, Loan Number and Accession Number. Users can define these fields using a specific format template, each field has the ability to automatically increment a number segment within the string. During data entry the format is used as a ‘template’ so all the values for the field are uniform. For example, a Catalog Number m…

B. The Potential Changes

1. Changing Table and Field Captions

To change a Table caption:

1. In the list of tables in the Schema window, select the table to be edited.
2. Enter the new caption in the Caption field of the Tables section.
3. You may have to restart Specify to see the change take effect.

To change a Field caption

1. In the Tables section of the Schema window, select the table the field to be edited is on.

2. In the Fields section of the Schema window, select the field to be edited.

3. Enter the new caption in the Caption field of the Fields section.

4. Hiding/Unhiding Tables and Fields

To Hide/Unhide a Table:

1. In the list of tables in the Schema window, select the table to be edited.
2. Click the box next to the Hide Table field.
3. If the box is unchecked, the table will not be hidden. If the box is checked, the table will be hidden.

To Hide/Unhide a Field:

1. In the Tables section of the Schema window, select the table the field to be edited is on.

2. In the list of fields in the Fields section, select the field to be edited.

3. Click the box next to the Hide Field field.

4. If the box is checked, the field will be hidden. If the box is unchecked, the field will not be hidden.

5. Making a field Required

To make a field required:

1. In the Tables section of the Schema window, select the table the field to be edited is on.

2. In the list of fields in the Fields section, select the field to be edited.

3. Click the box next to the Is Required field.

4. If the box is checked, the table will be required. If the box is unchecked, the field will not be required.

5. Assigning a Pick list

The list a Pick list field uses can be assigned through the Schema Configuration, however, to make a field into a pick list you must edit the form code and to edit the pick list contents you must use the Pick List editor.

To Assign a Pick List:

1. In the Tables section of the Schema window, select the table the field to be edited is on.
2. In the list of fields in the Fields section, select the field to be edited.
3. In the Field Format field, select Pick List.
4. A new list will be enabled containing a variety of pick list options. Select the appropriate pick list.

To edit a pick list:

Editing a pick list cannot be done through the Schema Localizer or Configuration. You must use the Pick List Editor to edit pick lists.

To get to the Pick List Editor:

1. In the top menu bar, go to System → System Setup → Configuration.
2. In the resulting screen, click Pick List Editor from the Left hand menu.
3. The Pick List Editor will appear
4. From the list of System Pick Lists, find the list to be edited. Either double click on the appropriate list or click on the pencil below the scroll bar. A new window will appear.
5. In the new window, you can edit the Pick List name, add new list items, or delete items.
6. To add new items, click the green plus next to “Pick List Items” and enter the new values. Then click Save. DO NOT click the arrows to review the options or items in the list will be deleted. If this happens, click Cancel without saving and the list will return to the way it was when it was opened.
7. To delete items, click the red minus next to “Pick List Items”. A window will appear asking if you wish to delete the selection. Click Delete if the deletion was intentional and cancel if it was not.

Editing in Specify’s Code

Several form changes are sufficiently complex as to require manipulation of the code itself to accomplish. Changes requiring code manipulation include; changing a field’s spacing, ordering fields, deleting fields, adding fields, changing a field’s format, adding a subview to a table, and creating a new subview.

Before making any changes, Specify and the computer have to be set up for code editing. Also, a basic understanding of how the code works is necessary before alterations are made to it.

As a side note, it may be beneficial or make form modifications easier if you are able to find an example somewhere in Specify’s forms and use it as a model for the modification. For example, if you would like to make the Date Accessioned field on the Accession table have the same format as the Cataloged Date field on the Collection Object table, you can find the Cataloged Date field and use it as a base for changing the Date Accessioned field. It may not always be a true parallel and there may be adaptations that still need to be made such as the field name and id number, but it will give you an idea of what you are trying to achieve.

Important – Before making any changes to Specify code, save a copy of the files you will be editing so they can be referred to later or used instead in case of an emergency.

Note – Some parts of the code may be surrounded by a <!-- and -->. This is called Commenting Out. Effectively, what it does is prevent the part of the code enclosed between the two symbols from being used without deleting the code. Although these are not necessary parts of the code, use caution in deleting them, they may be useful in the future.

Commenting Out can also be a useful tool if you want to edit a field but want to keep a copy of the original. To do this, copy the line being edited and paste it above or below the original line, then add <!-- before the original line and a --> after it. A simpler way to do this may be to use the undo function instead of commenting out.

A. Setting up Specify to show changes

Specify should always be checked immediately after making a change to the code. Specify does not have to be closed to make or view edits. However, Specify does need to be set up to show the edits without closing and reopening.

Checking immediately will show you what the edit looks like and let you know if you need to make further changes. Further, if there is a problem with the edited code, checking immediately will isolate the issue. A problem or an error window will usually appear upon the table edited being reopened.

Specify can be set up to create and show an error log, a list of problems encountered by the code. This option will give an idea of the causes of problems and can be sent to Specify if a problem that cannot be overcome arises.

1. Set up to View Changes

Once the additions below are added, edits to the code will be able to be checked instantaneously. To check the edits once the additions are made, the table that was edited must be reopened, which is accomplished by clicking on the table icon in the left hand menu.

Specify Set up to view changes:

1. In the top menu bar, go to Help and select About.
2. The About Specify window will pop up.
3. Double click the name of your database. In the example below, you would double click “multidata”.
4. A Local Prefs window should appear.
5. Click Add Property.
6. Double click on the new row created. The row should be titled “New Item” with a number following. Double click on the title. A cursor should appear in the row.
7. Replace the property in the column with the line below instead. Make sure it is exactly as below, if it is capitalized or has dashes instead of underscores, there will be no effect.

reload_backstop_views

8. In the Value column, enter “true”.
9. Click Add Property again.
10. Replace the property in the column with the line below.

reload_views

11. In the Value Column, enter “true”.

12. Important – click another line before clicking Close. Clicking another line saves the entries. The resulting Lines should look like the window below.

13. Setting up debug

14. In the top menu bar, go to Help and select About.

15. The About Specify window will pop up.

16. Double click the name of your database. In the example below, you would double click “multidata”.

17. A Local Prefs window should appear.

18. Click Add Property.

19. Double click on the new row created. The row should be titled “New Item” with a number following. Double click on the title. A cursor should appear in the row.

20. Replace the property in the column with the line below instead. Make sure it is exactly as below, if it is capitalized or has dashes instead of underscores, there will be no effect.

debug.menu

8. In the Value column, enter “true”.
9. Important – click another line before clicking Close. Clicking another line saves the entries. The resulting Lines should look like the window below.

Note – The addition of Debug to the menu bar can be undone by changing the “true” value to “false”. Remember to click on another line before closing to save the change.

B. Viewing code

In order to view and edit the code you may need to install a text editor. DO NOT USE WORD FOR EDITING CODE. Most computers come with some kind of text editor. For a program that allows you to do more, Eclipse is a good and free program. It is able to do much more than programs that come with most operating systems but it is also more complex to use and therefore more difficult for novice users to use. PC users can use Notepad which comes with Windows, or Notepad 2 can be downloaded for free. This program is similar to Notepad except it color codes the code according to what it does.

C. Location of the tables

Forms for specify are located in several different files. Most of the files that may need to be edited are located in one folder, the Config folder. Which file you open from there will depend on the table you want to edit.

1. First, you need to find the Config folder. The location of the Specify folder is decided when Specify is installed. The instructions below use the default location for Specify files. If a different location was specified during installation, that location should be used instead.

For a PC

1. Right click on the Start menu and select Explore.
2. In Explore, open Local Disk (C:) →Program Files→ Specify →Config.

In Vista, it may be OS (C:) →Program Files (x86)→ Specify →Config.

For a Mac

1. In Finder.
2. In Finder, open Applications → Specify6 → Config.

For Linux,

1. In the top menu bar, go to Places → Home Folder.

2. In Home Folder, open Specify → Config.

3. There are three main files in which almost all of the codes for tables are located.

1. General Tables –

Two of the folders, common.views.xml and global.views.xml are commonly used tables. That is, they are tables that are shared by most of the disciplines. Editing a table will change it for all disciplines that may use the table. For example, the Accession table is in the common views file. Removing the Status field from the Accession table will remove the field in the Accession table for every discipline.

The commonly used tables were not divided between the two files according to any particular rationale; therefore there is no way to intuit what table will be in either without checking. You may need to use the Find function under Edit in the menu bar to search for the correct table and to determine which file the table code is located in.

They are located in different folders in the Config folder. To get to the common views file, follow the directions above to get to the Config folder, open the Common folder in the Config folder. Once in the common folder, find and open the common.views.xml file.

To get to the global views file, follow the directions to get to the Config folder, open the Backstop folder in the Config folder. Once in the backstop folder, find and open the global.views.xml file.

2. Discipline Specific Tables –

Some tables are discipline specific forms, meaning that they are designed specifically for a particular discipline. Editing these tables will only affect the discipline. These tables are located in folders with the discipline’s name in the Config folder. For example, Herpetology’s tables are located in the herpetology.views.xml file in the Herpetology folder. The tables contained in these files vary, but the Collection Object, Determination, and Collecting Event/Collection Information tables are in the discipline views file for each discipline.

More tables may be located in these files as well. For example, the paleo views files (for Invertebrate and Vertebrate Paleontology disciplines) have Collection Object Citation, Locality, and SubPaleo Context tables in addition to the Collection Object, Determination, and Collection Information. In cases where a table is located in both the discipline specific and general files, the discipline specific tables will overrule the general files. For example, the Locality tables in the Invertpaleo and Vertpaleo views files are what is used by Specify rather than the Locality table from the Common Views file. Therefore, edits in the Common Views Locality table will not be seen in those files with a Locality table in the discipline specific files, such as Fish or Paleo.

To get to the files, follow the directions above to get to the Config folder. In the Config folder, open the folder for the discipline you want to edit, i.e. open Herpetology to work with the Herpetology tables. Once in the Herpetology folder, open the appropriate herpetology.views.xml file. There are three locations for the form files; the Manager file, the Guest file, and the folder level file. These files may be identical if the Manager and Guest forms are identical, or they may be different if the Manager and Guest forms differ. Specify may revert to the folder level file when the Manager or Guest file is deficient or missing something deemed necessary. Unless some alterations have been made to the code after you downloaded Specify, the Manager, Guest, and folder level files should be identical. For information on accessing information or limiting access, please see Specify Help.

D. Selecting the correct table

There are two sections of table code in the form files. The first section is the views section. This section is a list of table views. Table views begin with a <views> and end with the </views>. In between is a list of table views which appear like the text below. You will need to use this section if you add a subview so you can identify the code name for the subview. You only need to edit this section when adding a new table or subview. (See below to see how to add a new subview).

<views>

`<view name=“Accession”

class=“edu.ku.brc.specify.datamodel.Accession”

busrules=“edu.ku.brc.specify.datamodel.busrules.AccessionBusRules”

resourcelabels=“false”>`

<desc>``<![CDATA[The Accession form.]]>``</desc>

<altviews>

<altview name="Accession View" viewdef="Accession" mode="view" default="true"/>

<altview name="Accession Edit" viewdef="Accession" mode="edit"/>

</altviews>

</view>

The second section is the viewdefs section. This section is marked by a <viewdefs> and ends with </viewdefs>. In between are the table definitions, the spacing, fields, and subviews that make up each table. The table codes in this section are the codes that will be manipulated for most of the edits. The table defs are separated by “<viewdef” above the table and a “/viewdef>”, with the table definition between the two. The table will look similar to the code below (edited for form and line length).

<viewdefs>

`<viewdef

type=“form”

name=“Accession”

class=“edu.ku.brc.specify.datamodel.Accession”

gettable=“edu.ku.brc.af.ui.forms.DataGetterForObj”

settable=“edu.ku.brc.af.ui.forms.DataSetterForObj”>`

<desc>``<![CDATA[The Accession form.]]>``</desc>

<enableRules/>

<columnDef>p,0px,max(p;175px),5px, 141px,5px,110px,2px,140px,0px,15px,p:g</columnDef>

<columnDef os="lnx">max(115px;p),2px,max(p;155px),5px,165px, 2px,150px,0px,15px,p:g</columnDef>

<columnDef os="mac">max(130px;p),2px,max(p;208px),5px,160px ,2px,189px,0px,15px,p:g</columnDef>

<columnDef os="exp">p,0px,max(p;175px),5px:g,p, p,2px,max(p;150px),0px,p,p:g</columnDef>

<rowDef auto="true" cell="p" sep="1px"/>

<rows>

<row>

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

<cell type="field" id="1" name="accessionNumber" uitype="formattedtext"/>

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

<cell type="field" id="3" name="type" uitype="combobox" />

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

<cell type="field" id="2" name="status" uitype="combobox"/>

</row>

<row>

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

<cell type="field" id="10" name="modifiedByAgent" uitype="label" readonly="true"/>

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

<cell type="field" id="11" name="timestampModified" uitype="label" cols="20" colspan="2"/>

</row>

</rows>

</viewdef>

But first, you need to find the correct table’s code. Selecting the correct table can sometimes be difficult. The name of the table in Specify can be altered by the user or the programmers. Therefore the name viewed in Specify may not match the name used in the code. The difference may be as simple as the difference between “Agent” and “Agents”. The difference may be a little more complex such as adding or changing a word, such as “Gift Preparations” and “Gift Items”. Or, the difference may be unrecognizable (though this is rare). For example, Chronostratigraphy is named “geologictimeperiod” in the code.

There are several tricks for finding a table in the code if you are unsure of the table’s name. You can use the Find function under Edit in the top menu bar to search for fields that are in the table. You can compare the fields listed in the table’s code to the tables seen in Specify to make sure the tables are the same.

Another method is to use the Schema Localizer and Schema Configuration tools. The name listed in the Tables list is the name used in the code. The name given for Caption, is the name seen on the Specify table, as demonstrated in the image below.

E. Selecting the Correct Form Layout Code

Each table has four different codes for spacing. These codes are marked by “<columnDef>”. These different codes correspond to different form layouts, which can be changed in Specify through the Preferences function. The form layout Specify is in and the code being edited must correspond for the edits to be visible. (To see how to get to Preferences and how to change form layouts, see Specify Help).

<columnDef> corresponds to the Small Font Format (ideal for Windows)

<columnDef os=lnx> corresponds to the Medium Font Format (ideal for Linux)

<columnDef os=mac> corresponds to Large Font Format (ideal for Mac)

<columnDef os=exp> corresponds to Elastic Layout

Troubleshooting

If edits to the code are not immediately visible in the Specify form one or more issues may be the cause.

1. Specify may not be set up to show changes. Specify needs to be set up to show changes to the code. The Local Prefs tool must be set to show code changes. The directions to do this are given in the Setting Up Specify to Show Changes section above.

If you followed the directions and the issue is still present, several issues may be the cause.

1. Reopen the Local Prefs window and check to see if the reload lines were entered (Local Prefs organizes alphabetically according to capitalized or not so it is organized ABC then abc). Make sure that the Property and Value lines that are supposed to be entered are exactly as they are in this document. If the characters are different, if there is a capital letter, a space, or a dash instead of an underscore Specify will not understand the instruction and ignore it.

2. If both lines are not there, they may not have been saved. Reenter the missing line (both Property and Value) and make sure to click another line in the Local Prefs window so the new line is no longer highlighted. This saves the line. Then close the window.

3. The Value may not have been entered or saved. Both the reload_views and the reload_backstop_views Properties should have values of “true”. If they do not, click on the Value corresponding to the Property and enter “true”. Then click another line to save the line before closing.

4. The preference may be correct and one of the following options may be the cause instead of the set up.

5. The wrong table is being edited. Make sure that the table you are editing is the one you are looking at in Specify. Try deleting a field in the code. If the table does not change, you are either not editing the correct table or Specify was not set up to show edits immediately. If you restart Specify and reopen the table and the edit now appears, Specify has not been set up to show immediate changes. If the change still doesn’t appear, the wrong table code is being edited (undo the field delete in the code before moving on). You may want to check the Schema Configuration to see if the name of the table is correct (though not all subviews are listed in the Schema Configuration or Localizer, subview names can be checked by looking at the code for the table they are on, the name will be listed exactly as it is for the subview table’s code.)

6. If you are working on spacing and Specify is not reflecting the changes made, you may be editing the wrong table or Specify may not be set up to show changes (see (2) above to see how to check if it is the wrong table or Specify is not set up). If Specify is set up correctly and you are editing the correct table, the code being edited may not correspond to the form layout in which Specify is set. To check to see if it is a different code, make a small change to the spacing in each of the four layout codes one at a time. You should see a change resulting from one of the changes. If you do not see any changes, you may be editing the incorrect table or Specify may not be set up to show changes. See sections above on how to set up Specify to show changes and to find the correct table.

D. Columns

The forms in Specify are arranged according to a column layout. Columns determine the width of fields, labels, and spaces in the form. Columns can be made to be different set widths or they can be set to expand or contract to the size required by the fields in that column.

1. The spacing used for a table will apply to every row in the table, you cannot give each row different spacing (though you can fudge it a bit using column spans as described below). This means that all of the fields in a column share the same width. If the first field in the third row requires a great deal of space but the first field in the first row doesn’t require much space at all, the table spacing for that column must be set to allow for the largest field. In the image below, the red lines indicate where the columns are. Note that in the third column, the Start Date field had to be extended to match the length of the Issued By field, which requires much more space.

2. The column spacing can appear to be broken up by subviews. Each subview has its own column spacing because each subview is its own table. However, the subview’s length in the table is set according to the table’s columns. The column spacing within the subview is independent because it is its own table, but the subview has a set width it is allowed, determined by the column spacing on the table in which it appears.

In a case where there are subviews between two parts of a table, the column spacing will continue to the rest of the form after the subviews. For example, in the image below Geo Coord Details and Locality Details are both subviews on the Locality form. The Elevation section is a continuation of the Locality form, indicated by the red lines. Both the Geo Coord Details subview and the Locality Details subview have unique column spacing as indicated by the green and purple lines respectively. Note that the Geo Coord Details and Locality Details subviews end at the same place as the top section and the Elevation section. The spacing in the subviews can be set to be longer than the table they are on but this will result in only part of the subview being shown and a scroll bar at the bottom of the subview.

Column spacing in subviews can be set to be similar or identical to the spacing of the table they are in such as the Geo Ref Det Date and Range fields, which have been set to replicate the columns on the Locality table. However, the same spacing may not work for all tables. Different tables use different fields and may have different captions, both of which may require more or less space than other fields and labels. For example, the first fields in the table and subviews have been set to start at the same point. However, whereas the first field in Locality Details can be the same length as the Locality fields, the first field in the Geo Coord Details subview requires more space and must therefore be longer.

3. Each field consists of three parts; a label, a space, and the field itself. If it is followed by another field, there will also be a space between the first field and the next. Thus, the form layout spacing for a row with three fields will be:

Label A, space, Field A, space, Label B, space Field B, space, Label C, space, Field C

On the form, this layout looks like the image below:

In the code, this may look like the following (bear in mind, the numerical values can change depending on the field and the desired layout):

4. The spacing in the form layout is unique to each table. The spacing has to be set for each Table and each subview on each table. The spacing is not automatic. Spacing can be set to be identical between different tables,

E. Code Symbols

Column size can be forced or it can be as needed (expand or shrink depending on what the field or label requires). To force a column size constants are used, to let size be as needed resizing is used. The code used by Specify for forms is very complex and offers a variety of sizing options. A few of the more popular options are discussed below, including constants, resizers, and bounders. For more in depth discussion of the potential code options, please refer to “The JGoodies Forms Framework” by Karsten Lentzsch.

1. Constants

Constants set a determined length for a column and thereby all of the fields in that column. px (pixel) is the constant used to date by Specify but it is not the only one that can be used. Also available are pt (point), in (inch), mm (millimeter), and cm (centimeter).

In the code constants look like the example below. Commas demarcate the end of a column so 105px is one column 2px is the next, etc.

<columnDef>105px,2px,85px,5px,95px,2px,200px,5px,106px,2px,200px,0px,15px,p:g</columnDef>

To change a column’s width, increase or decrease the number in that column. For example, the effect of changing 85px to 155px is shown below.

2. Resizers

Resizers are essentially the exact opposite of the constants. Resizers are not a definitive size, they adapt to the size of the widest field in a column and changes in text size and font, whereas constants will not adapt unless the code is changed. For example, the images below show a form set in Arial 12 font and a form set in Veranda 14. Note that the field and label columns have adapted to the wider size. Constants would not adapt, the code would have to be altered to accommodate the change. However, this also means that the width cannot be controlled as it can in constants, which allows fields to be lined up throughout the form and subviews.

Resizers set the column and all fields in the column to be as wide as the preferred size for the widest field in that column. All fields in the column will expand to that width, regardless of their own default width. In other words, if a column has a filed that requires 80px and another field that requires 120px, the column will expand to 120px and the first field will expand to that size as well.

There are two resizer options primarily used in Specify; p and g. P is the preferred width for a cell. Each cell has a preferred width depending on the cell type. G is a growth command. It is used with other symbols (p or a constant) to instruct the column to grow to fill the form. When multiple growth commands are used in a column layout, they will work together to fill the space. In the code, resizers look like the example below. Note that a p can be used on its own but the g is attached to another symbol with a colon, for example p:g or 2px:g.

<columnDef os="exp">p,p:g,p,p:g,p,p,p,p,p,p,p,p,p,p:g</columnDef>

Resizers and constants can be intermingled such as the example below.

<columnDef os="exp">p,2px,125px,5px:g,p,2px,p,5px:g,p,2px,p,0px,p,p:g</columnDef>

3. Bounders

Bounders are a mix of constants and resizers. Bounders set the boundaries of a column depending on what is desired. There is a minimum and maximum bounder. They are not used together, meaning you can either set the minimum or the maximum for the column. The column will either not go smaller than the options it is given or it will not go wider, depending on which bounder is used.

In the code, a bounder looks like the example below.

105px,2px,max(p;130px),5px,60px,2px,100px,5px,90px,2px,136px,5px,165px,0px,15px,p:g

p,2px,min(p;150px),5px:g,p,2px,100px,5px:g,p,2px,100px,5px:g,p,2px,100px:g

To use a bounder, type in min or max, then type in the parentheses. In the parentheses, type in a resizer (g will not work, for more examples than p see “The JGoodies Forms Framework”) and a constant size. The order they are in does not matter. The two values should be separated by a semi-colon. The table will use whichever of the two options it is given fit the bounder. In the max example above, the table will make the column the larger of 130px or the preferred width for the column (p). In the min example, the column will be the smaller of 150px or the preferred width for the column (p).

Troubleshooting

1. If you receive an error message such as the one below, the code is missing a separator or the separator used is not correct. Constants and p’s should be separated by commas, g’s should be separated from the value before it with a colon and the value after it with a comma, and bounders should have a semi-colon between the values in the parentheses and have a comma after the parentheses. For example, the code may look like 105pxp instead of 105px,p, or p105px instead of p,105px.

To resolve the situation, examine the code and make sure the appropriate separator is used in all cases.

F. Column span

Fields and labels can be set to span more than just one column they usually take. There may be cases where you would like a field to span several columns, such as a Remarks field which you may want to span the entire form. Expanding a field to cover more columns than normal will displace all of the fields that follow it in that row, but it will only affect that row. Subsequent rows will not be affected by the expansion.

1. To make a field span more than just one column, add in the phrase colspan=”X” where X is the number of columns you want the field to span. An example of what a field set to span 3 columns would look like is below.

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

<cell type="field" id="name" uitype="text" cols="16" name="name" colspan="5"/>

2. The column span will begin where the field would normally begin. If the first field in a row is set to span 5 columns, using the spacing example from section c, the field would begin at Field A and end with Field B.
3. Normal field spacing will restart where the expanded field ends. In other words, the column after the expanded field ends will be a space, followed by a Label, space, Field. In the example above, with a column span of 5, the row would continue with the space following Field B and the second field in the row would use the spaces for Label C, as seen below.

If the expanded field ends at an awkward place the subsequent fields in that row will look strange or may be rendered unusable. For example, if the column span were 4 instead of 5, the spacing would be appropriated as it is seen below, which would result in exorbitantly long spaces and the label and field for B to be too small to be seen or used.

Troubleshooting

1. If the fields or labels do not appear after changing column size or column span, as demonstrated in the image below, the columns or the column span is off.

To resolve the situation, there are three alternatives, add a blank field (directions on adding a blank field are given in the section Blank Fields in the Fields section), change the column span, or change the column sizes.

1. Probably the easiest solution is to adjust the column span but it will only affect the row in which the field with the colspan being altered is located. To adjust the column span, change the “colspan=” number until the columns appear correct.

2. You can also change the column widths to allow for the fields and labels to be legible and useable. Any changes to the column spacing will affect all of the rows. If there is an issue with the spacing in only one row you may want to use a blank field or adjust column spacing.

3. If a scroll bar appears at the bottom of a subview, as demonstrated in the image below, the subview the spacing in the form layout for the subview is longer than the spacing length allowed for in the table it is on.

To resolve the situation, you can take one of two routes. Make the table the subview is on larger or make the subview smaller.

1. To make the subview smaller, decrease the size of labels, fields, or spaces until the scroll bar disappears.

2. To make the table wider, increase the size of labels, fields, or spaces until the scroll bar disappears.

3. If you get an error message such as the one below (bear in mind the specifics of the message such as the numbers and names will vary depending on the situation) the form layout in one or more of the rows require more columns due to the number of fields in the row than is accounted for in the column layout.

To resolve the situation, there are two alternatives, add more columns or move fields to a different row.

1. to add more columns, add more spaces in the column layout. Bear in mind that the column size will still have to be adjusted to accommodate the new labels and fields.
2. To move fields to a different row, see the section on Moving Fields below. You may have to create a new row to accommodate the fields, see the section below on rows.

G. Rows

1. Just as the fields are set according to a column system, they also have rows. The beginning of a row is indicated by a <row> and the ending by a </row>. The fields between the two caps are the fields that will be in a row and the order they will be in. A row may consist of one field, several fields, a subview, or a separator.
2. Fields are automatically set to be 1 row unless forced to be larger. Only certain fields types can be more than 1 row. Textarea (can be as many rows as desired) and textareabrief (must be only 2 rows) can be more than 1 row.
3. Grids and subviews can also be set to be a certain number of rows. Grids are automatically set to be at least 5 rows, unless forced to be larger or smaller. Subviews are automatically set to be the length required by the number of rows of fields in the subview.

If a subview can alternate between a form and a grid, the smallest the grid can be is the length the form requires for the fields on it. For example, the form version of the Preparations subview on the Collection Object form consists of two rows of fields. Therefore, the grid version the Preparations subview cannot be smaller than 2 rows, but it can be as long as desired. However, whatever length it is set to for the grid, is the length it will be set to for the form as well, so if Preparations is set for 10 rows, the subview will take up that amount of space regardless of whether it is in form or grid mode.

4. To force a field to be a certain number of rows, add in the phrase rows=”X” where X is the number of rows you want the field to be. An example of what a field set to 2 rows looks like is below.

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

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

The process is the same for a grid or a subview. On the table the grid or subview appears, find the line of code for the grid or subview and add in the rows phrase. An example of is below.

<cell type="subview" viewname="Preparation" id="8" name="preparations" rows="3" colspan="12"/>

Troubleshooting

1. If a field is not growing despite the instruction to be larger, the field type may not be able to be longer. Not all field types were designed to be more than 1 row. Only the fields that were designed to be able to exceed 1 row can do so.
2. If a subview is not shrinking, it may have reached the minimum it can be with the fields it has on it. The subviews will not be shorter than the number of rows on the form.

Fields

An important note to consider before making changes to fields, subviews (subforms) may be shared by multiple tables, making a change to one may affect other tables. For example, Shipments is used by Loan, Loan w/o Preps, Gift, Exchange Out, and Borrow. Alterations made to the fields in the Shipments subview that are intended for one table will change Shipments in all tables that use it, unless many more steps are taken (See Creating New Subviews below).

Important – It is important to note that subviews are their own table in the code and in the Schema Configuration. Thus, if you want to edit a field or fields in a subview, you must find the subview table in the views file. For example, in the image below, Address of Record and Shipments are both subviews on the Exchange Out form. All three of them; Exchange Out, Address of Record, and Shipments are individual tables in the code. For more information on subviews or editing subviews, see the Subviews section below.

1. Ordering Fields

The order of the fields on a table can be changed easily.

The code for a field usually consists of two lines. The first line is the label for the field and the second line is the field itself. Make sure you delete both lines of code or the table the field was on will throw error messages at you the next time you try to open it. Checkboxes are an exception to the two line code, they only consist of one line. The lines are always consecutive and have the same id number. For example, for the Status field, the first line has the label for field “2”. The second line has the id “2”.

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

<cell type="field" id="2" name="status" uitype="combobox" picklist="AccessionStatus"/>

Fields are listed in the order you see them in the screen from left to right then top to bottom. The fields are separated by rows from left to right. The rows are listed from top to bottom. For example, the code for the Exchange Out table (shown below) lists the fields as shown in the code below.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

<row>

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

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

</rows>

To move a field, highlight both the label line and the field line then drag and drop it to the desired position, then save the change. For example, if you would like to switch the Exchange Date and Cataloged By fields, highlight the lines highlighted below and drag and drop them to below the Cataloged By field line, as demonstrated below.

<row>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

Note – The spacing for the fields does not follow the field when the fields are reordered. You will have to change the column layout if you change the order. For example, in the example above, if the Exchange Date and Cataloged By fields are switched without editing the column spacing, the Cataloged By field would be cut in half, as shown below.

2. Deleting Fields

Deleting fields is a relatively easy process once you locate the field you want to delete (See Table Location above).

Important – Not all fields can be removed. Some fields are mandatory for the table to function. The mandatory fields are noted by bolded labels. If these fields are removed, error messages will appear when the table is opened or when Specify is opened, either the field or the entire table will not appear, and the table will not interact with other tables correctly.

Fields may be made required or not required through the Schema Localizer, which will also make the field labels bold. However, this is different than being mandatory. A field cannot be made to be not mandatory.

1. Once you have identified the correct table, identify the correct field. The field labels should be almost identical to their name. The name is listed in the code for the field as name=””. For example, the code for the Status field in the Repository Agreement Table is name=”status”.

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

<cell type="field" id="2" name="status" uitype="combobox" picklist="AccessionStatus"/>

2. Highlight the entire code for the field and delete. Remember, the code for each field usually consists of two lines. You must delete both lines.

Note – If the deleted field is at the end of a row, it will be replaced by a blank space. But, if it is in the middle or beginning of a row, the fields to the right of the deleted field move left to replace it (Figure X).

If the field to the right requires more space than the deleted field, the field may get cut off, as can be seen in figure X. To remedy the issue, you can either edit the column layout to give the field more space (See column span section above for instructions)

or, you can insert a blank field where the deleted field (directions on inserting a blank field are given below).

Troubleshooting

1. If you receive an error message such as the ones below when you open the table, the second line of code was deleted but not the first.

2. If the field still appears but the label is gone (as in the image below), the first line of code was deleted but not the second.

3. If the field is partially cut off, not enough space was allotted for it in the layout. The table layout needs to be edited to allow more space for the field (See column span section above for instrucitons).

4. Adding New Fields

The first step in adding a new field is to learn what fields can be added. Field labels can be changed in the localizer (See Localizer below) or in the code. You must select a field from the available fields list to add to the table.

Available Fields

Before learning how to add new fields, it is important to realize there is a set list of fields that can be added to each form. The easiest way to identify the available fields is to look in the Schema Configuration.

To see the fields available for Address of Record, you must select the Address of Record table.

The fields cannot be transferred from table to table. For example, the fields available in the Address of Record table cannot be placed on the Exchange Out table except in a subview.

Adding Fields

1. Once you have the name of the field to be added, decide where on the form you would like it to be. To see how fields are ordered see the Field Ordering section above.

2. Most fields consist of two parts the label and the field itself. The two parts are added in separate lines. The fields must be entered under the correct row and each line must be enclosed between a <, which starts the line, and a /> which ends the line.

3. The label line precedes the line for the field, so first add in the label line. There are two parts of the label line, the cell type, label, and what the cell is labeling, an id number.

4. Add the `<, then type cell type=”label”

5. Next, type labelfor=”X”/>` The X

6. The X should be replaced by a unique id number for the field. Each field should have a unique field number associated with it, within each table. For example, Accession Number in the Accession table may have the id 1. No other field in the Accession table can have id 1. However, the agent table in the Accession Agent subview can have id 1 because it is a separate table in the code. The id is assigned in the field line but the label line uses it to assign the label, so although the number is unique, both lines will share it.

7. The resulting line should look similar to:

<cell type=”label” labelfor=”1”/>

Note – If you do not want a label do not insert the first line. The field will work the same as if it had a label even when one is not attached. However, it may be confusing for data entry and interpretation if no label is attached, so exclude with caution.

4. The next line is the field line. There are multiple parts of the field line. The number of parts depends on the field.

5. Type `<cell type=”field”

6. Next, add the unique id number, which will look like id=”X”, again X should be replaced by the same number referenced in the label line.

7. Then add the field name. The field name should have been obtained from the Available Fields list (as mentioned above). The section will look like; name=”permitNumber”

Important – The name must be copied exactly from the Available fields list. If the titles are off by a letter, space, or a capital, the field will not work correctly. For example, Permit Number will not appear on the Permit table if “permit number” “PermitNumber” or “permitnumber” is typed into the code. It must be “permitNumber”, as seen in the Available Fields list in order to work.

4. Next, add the ui type. The ui type is the type of field the added field will be. Most will be text fields, but there may also be textarea, textarea brief, formattedtext, etc. (See UI Types section below for more information). The section will look like; uitype=”text”
5. If the field will be longer than one space (See ColumnSpan) or cover more than one row (See Row Number), these parameters will be entered here. Columnspan attribute will look like colspan=”X” where X is the desired number of columns for the field. Row attribute will look like rows=”X” where X is the desired number of rows for the field.
6. If the field is formatted, such as a date field, the format type is added next. Type uifieldformatter=”X”, where X is the type of format. This will look like; uifieldformatter=”Date”. (The only formatted field type you should use is for date fields.)
7. The resulting line will look like one of the following, or some combination thereof;

<cell type=”field” id=”1” name=”permitNumber” uitype=”text”/>

<cell type=”field” id=”1” name=”permitNumber” uitype=”text” colspan=”2”/>

<cell type=”field” id=”1” name=”permitNumber” uitype=”text” colspan=”2” rows=”2”/>

<cell type=”field” id=”5” name=”issuedDate” uitype=”formattedtext” uifieldformatter=”Date”/>

Troubleshooting

1. If you receive a message such as the one below, a duplicate id number was used. To resolve the issue, assign a new, unused number to one of the fields with the duplicated number. Remember to change id for both the field line and the label line, otherwise the label will not appear for the field.

2. If you receive a message such as the one below, the < at the beginning of the field line was not inserted. The error message will identify which field line is missing the opening symbol by giving you the id number. It also identifies the Table (Permit in this case) and the file the table is in (Common Views). To fix the issue, insert the < before cell type of the deficient field line.

3. If you receive a message such as the one below, a line closer was not inserted or not inserted correctly.

The line could be missing the /, the >`, or both. The end of the line will look like the end of one of the following lines;

<cell type=”label” labelfor=”1”>

`<cell type=”field” id=”1” name=”permitNumber”/

`<cell type=”field” id=”1” name=”permitNumber”

The error message identifies the line number that is missing the ending symbol. To fix the issue, you must insert the missing symbol in that line.

If your computer does not use a code editing program that numbers lines (such as Notepad 2), the line number will not appear in the error message. You will have to check the end and beginning of each line in the table to see which one is missing a cap.

4. If your form looks like the one below when you open it, there are two potential causes.

1. The line opener was not inserted in the label line for the field missing the label. The label line for the problem field will look similar to line a in the following lines. To resolve the issue, insert the `< at the beginning of the line so it will look like line b in the following lines.

2. cell type=”label” labelfor=”1”/>`

3. < cell type=”label” labelfor=”1”/>

4. The field name was entered incorrectly. To resolve the situation, double check the name entered for the missing field. Check for spaces (there should be no spaces in the name), capitalization, spelling, etc. The name must appear exactly as it is in the Schema Configuration.

Blank Fields

Blank fields can be inserted in places where a gap spanning several columns is desired, demonstrated in the image below.

When inserting a blank field, only the label line is entered. The blank field is in reality a blank label that is usually made to span several columns.

To insert a blank field enter the label line as usual but instead of assigning an id number, leave it blank. The resulting line will look like the line below.

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

You may need to make the field span several columns to preserve the field layout as it was before the deletion. It will usually be “3” but may change if the deleted field spanned more than one column.

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

4. Uitype

5. Text

A text field is a field in which text or numbers can be entered. Text fields are only one row and there is a limit on the numbers of characters that can be entered. The number of characters that are allowed is preset related to the field with which the text is associated.

In the code, this ui type looks like: uitype=”text”.

2. Text Area

Textarea is a large field in which data is entered. It can be as large or small as desired, depending on what it is set to be in the code. Each textarea field can be set to be different sizes.

In the code, this ui type looks like: uitype=”textarea”.

3. Text Area Brief

Textarea brief is similar to textarea, with the distinction that Textareabrief is limited to 2 rows and gives the option to open a separate window to display all of the data entered into the field. This field offers the advantage that as much information can be entered as desired but it will only take up 2 rows.

In the code, this ui type looks like: uitype=”textareabrief”.

Important - Textareabrief must be set to be 2 rows. It appears to work if it is not but creates significant issues behind the scenes if it is not.

4. Formatted text

Formatted text gives the field a predesigned format associated with the field. This can only be used for certain fields such as date fields and Accession, Gift, Loan and Catalog Number fields.

In the code, this ui type looks like: uitype=”text”.

5. Combo Box

Combo Box is a pick list field. It offers the user a predetermined set of options for the field. The options can be set by the administrator or anyone with administrative permissions. There are only a certain number of pick lists and the field must use one of the pick lists offered (though the pick list items can be altered). A pick list is assigned to a combo box via the Schema Configuration in Specify. Directions to edit a pick list are above in the Assign a Pick List section.

In the code, this ui type looks like: uitype=”combobox”.

6. Query Combo Box

The Query Combo Box allows the user to search for records on a linked table. The user can add a previously entered record, create a new record for the linked table, or edit a preexisting one. For example, the user who is creating a new Exchange Out record, in the Cataloged By field can add an agent by searching for a previously created agent (the record can also be edited if desired), creating a new agent record. The use of this field is limited. This style can only be used with fields that link to a different table, such as agent, permit, or collection object.

In the code, this ui type looks like: uitype=”querycbx”.

7. Check Box

Check boxes can be used for fields in which the information conveyed is a yes/no or present/not present. Check boxes are different from other fields in that the check box and the label are considered one unit. Instead of taking up three columns with label, space, field, it takes one, usually very long column. Like any other field, it can be set to span more than one column.

In the code, this ui type looks like: uitype=”checkbox”.

8. Spinner

Spinners are number fields which allow the user to add or subtract numbers (0 – a number determined in the code) by clicking an up or down arrow adjacent to the field or by typing a number. To set the maximum number, add initialize=”max=X” where X is the maximum number allowed.

In the code, this ui type looks like: uitype=”spinner”

Subviews

Subviews (sometimes referred to as subforms) are tables that are placed on other tables. Subviews are their own table in the code and in the Schema Configuration. Independent tables are identified by a line break in the form with a down-turned triangle at the left side followed by a bold blue label and a line extending the length of the table. For example, in the image below, Exchange Out, Address of Record, and Shipments are all independent tables in the form code. The first table on the form is the base table. In this case, Address of Record and Shipments are subviews on the Exchange Out form.

In many respects, a subview is treated like a field. Ordering, deleting, or adding subviews follow much the same procedure as ordering, deleting, or adding a field. Subviews that can be added to a table are listed in the Schema Configuration with the fields that can be added. A subview appears similarly in the code to a field except there is no label line. However, a subview also has a definition in the code, which defines the fields and column layout for the subview. A subview will therefore have a view and viewdef (both described in more detail above in the Locating the Correct Table Section), which appear identical to a normal table’s view and viewdef.

Ordering subviews

The order of subviews on a table can be changed easily. Subviews can be moved between other subviews or placed between rows of fields.

Subviews and fields are listed in the table in the order you see them in the screen from top to bottom. The subview is usually in its own row, though this may not always be the case. To move a subview, you will need to move the row caps as well. For example, the field layout code for the image above of the Exchange Out table is shown below (with the exception that in the code a cell is always on one line, it does not wrap onto the next line as it does below due to space issues).

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent"/>

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent"/>

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

</rows>

If you wanted to move the Address of Record subview to come before the Remarks field, you would need to move the highlighted portion in the code above to be above the <row> right before the remarks row. The resulting code and form would look like the code and image below. Make sure you do not place the code within the <row> </row> set or the subview will disappear.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

</rows>

Troubleshooting

1. If you got an error message such as the one below, there is an uncapped row. In other words, there is a <row> that is not followed by a </row>.

In the code below, an example of this is demonstrated. The code lines for the moved subview are highlighted below. The <row> for the subview code was not moved with the other two lines and remains separated without an end cap.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

</row>

<row>

</rows>

This means that all three lines of the subview code were not moved together. The code will look similar to the code below, though the particulars of your case may be slightly different depending on the direction the lines were being moved, the number of lines moved, and their placement.

To resolve the situation, reexamine the code and find the code you just moved. If it was the last change made, you should be able to use the Undo function in the Edit dropdown menu at the top of the window to undo the change.

If it was not the last move, you may have to examine the code to identify the moved subview and either:

1. Return the moved lines to their original location and move all three of lines together to the desired location.

2. Find the line(s) that were not moved and place them in the correct order with the rest of the moved lines.

3. If the subview that was moved disappears on the form, the subview code lines were placed within another row. This created a row within a row, as demonstrated in the code below. The corresponding row sets are identified with blue and yellow highlighting below. Specify will eliminate the row within the row and keep the main row, which is always the outer row caps, identified in the code below by yellow highlight. In the example below, the Shipments subview, enclosed in the blue row (the inner row) will not appear. But, the Address of Record subview would appear because it is not enclosed in the inner row. It is external to the inner row but still enclosed by the outer (yellow) row.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

</rows>

To resolve the situation, move the subview code lines to the correct location. Be careful to move all three lines and not any other lines or other problems will be created.

3. If another element or more than one element on the form disappears (i.e. another subview, a field, a row of fields), all three lines of subview code were not moved together and they were placed within another row, as demonstrated in the code below. The element(s) that disappear depends on what lines were moved and where they were moved. A row within a row was created by the move and anything within the inner row was eliminated by Specify. In the example below, both the Address of Record and Shipments subviews would disappear because both are enclosed by the row within a row. See the issue 2 above for more information on rows within rows.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

</row>

</rows>

To resolve the situation, recombine the three subview code lines and move all three, and only those three, to the correct location. Moving more than the three lines will create more issues.

Separating Line

A line extending a desired distance, such as the entire width of the form, can be inserted to separate different parts of the form, in the example below, it is used to mark where a subview ends and the form returns to the normal table.

To insert a break line:

5. Create a row (add <row> on one line).
6. On the next line, insert <cell type="separator" label="X" colspan="XX"/>.
7. Add </row> on the next line to end the insertion.

The break can have a label or not. To add a label, insert the desired label where the X is in the line above. For no label, delete the X and don’t put anything in its place. The colspan value will change depending on the columns on the table and the desired length. The resulting line may look like the highlighted line in the code below. The form will look like the image below.

<rows>

<row>

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

<cell type="field" id="1" name="exchangeDate" uitype="formattedtext" uifieldformatter="Date" default="Today"/>

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

<cell type="field" id="2" name="agentCatalogedBy" uitype="querycbx" initialize="name=Agent" />

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

<cell type="field" id="3" name="agentSentTo" uitype="querycbx" initialize="name=Agent" />

</row>

<row>

<cell type="subview" id="6" name="addressOfRecord" viewname="AddressOfRecord" colspan="13"/>

</row>

<row>

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

</row>

<row>

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

<cell type="field" id="4" name="descriptionOfMaterial" uitype="text" colspan="10"/>

</row>

<row>

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

<cell type="field" id="5" name="remarks" uitype="textareabrief" rows="2" colspan="10"/>

</row>

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

</rows>

Troubleshooting

1. If you receive an error message such as the one below, the first line of the separator code (<row>) was not added. If the text editor you are using numbers the rows, the message will tell you the number of the line corresponding to the issue.

To resolve the situation, create a line above the separator code and add <row> to the line.

2. If you receive an error message such as the one below, the last line of the separator code (</row>) was not added. If the text editor you are using numbers the rows, the message will tell you the number of the line corresponding to the issue.

To resolve the situation, create a line below the separator code and add </row> to the line.

3. If the separator does not show up at all, despite all three lines being added, the code may have been placed in another row, creating a row within a row. To see more on rows within rows, see the Troubleshooting section of the Ordering Fields section above.

To resolve the situation, move all three lines, and only the separator code lines, to the appropriate place.

4. If you receive an error message such as the one below, the colspan number (colspan=”X”) was set too high.

To resolve the situation, decrease the colspan number to the appropriate length.

5. If the line does not extend the desired distance, the colspan number is too small for the desired width. To resolve the situation, increase the colspan number.

Adding new subviews

Important – you cannot add or create a subview that is not listed in the available fields list in the Schema Configuration. Fields that can be made into subviews are identified by their type. The field must be a Many-To-One or One-To-Many type to be turned into a subview. The type is given in the Schema Configuration when the field is highlighted, as demonstrated in the image below.

To add a new subview:

1. Create a row by typing <row>.
2. On the next line, insert `<cell type=“subview”
3. Next, identify the subview’s field name. This will be listed in the Schema Configuration. It is the name of the field allowed by the table on which you will be placing the subview. It must match the name on the list exactly or the table will not accept it and will throw error messages.
4. Once the field name is identified, add the phrase name-=”X”, where X is the field name just identified. Note that this name is almost never capitalized, so be careful not to do so if appropriate. An incorrect letter case will cause the table to not recognize the field.
5. This is followed by the subview’s table code. This is usually close to the name in the field list in the Schema Configuration. To find the name, you will need to look through the views section of the code and find the correct table and copy its code name. Not all potential subviews will have a view or viewdef, in these cases, you will need to ask for further assistance to add them.

Remember – a subview is a table that is placed on another table, so the subview will also have a view and viewdef like any other table.

6. Once the code name is identified, add the phrase viewname=”X”, where X is the table code name you just identified. Note that this name is almost always capitalized, so make sure to capitalize it if appropriate. An incorrect letter case will cause Specify to not recognize the table.
7. Next, add the number of columns the subview is intended to span. Most subviews span the entire form, but they are not required to do so. Add the phrase, colspan=”X”/> where X is the number of columns the subview is to span and the /> ends the line.
8. On the next line, end the row by typing </row>.

The resulting addition should look like the following lines.

<row>

<cell type="subview" id="8" name="shipments" viewname="Shipment" colspan="13"/>

</row>

Troubleshooting

1. If a scroll bar appears at the bottom of a subview, as demonstrated in the image below, the subview the spacing in the form layout for the subview is longer than the spacing length for table it is on.

To resolve the situation, you can take one of two routes. Make the table the subview is on larger or make the subview smaller.

3. To make the subview smaller, decrease the size of labels, fields, or spaces until the scroll bar disappears.

4. To make the table wider, increase the size of labels, fields, or spaces until the scroll bar disappears.

5. If the subview does not extend the full distance of the form as desired, as demonstrated in the image below, increase the colspan number in the code.

3. If the table does not show up at all, as demonstrated in the image below, the table code name is incorrect.

To resolve the situation, double check the table code name (viewname=”X”). Make sure the letter cases are correct and that there are no superfluous spaces. You may want to copy the name in the `<view name=”X”… from the table’s views description.

4. If you get error messages such as the ones below, the field name is incorrect.

To resolve the situation, double check the field name entered (name=”X”). The error messages will say what name is at issue, for example in the example above “Shipments” is the issue. Unfortunately, it will not tell you the correct name. Make sure the letter cases are correct and that there are no superfluous spaces. Make sure you got the name from the list of Fields not the Caption next to the list. The Caption can be set to be whatever the user wants and does not necessarily reflect the actual name.

To Import Edited Forms:

1. In Specify, go to System in the menu at the top and select Resource Import/Export… from the drop down menu.

You will receive a warning that any changes you make will require you to exit Specify.

Make sure there are no changes you need to save, and click Continue if you do not. If you have changes to be saved, click Cancel, save the changes and repeat this step.

2. If you have more than one user, you will be asked if you want to alter the forms for you or another user. Choose whichever is appropriate for what you want to do. If you want to import the forms to the Collection or Discipline levels, you can do it as you or another user. If you want to import to the User or User Type levels, you must choose either that user or a user from that type.

3. In the window that appears, select the level you want to import to from the drop down menu at the top of the window. The level to which you want to import depends on who you want to view the forms.

• If you want only one particular user to see these forms, choose User.
• If you just want the users of a certain group (i.e. managers, limited access users, guests, etc.) to see the forms, choose User Type.
• If you want all of the users of a collection to see the forms, choose Collection.
• If you want all users of all collections in a particular discipline to see the forms, choose Discipline.
• DO NOT import to the Institution or System levels unless you are specifically recommended to do so.

4. Click the Import button towards the bottom of the screen.

5. In the navigation window that appears, navigate to the forms XML file. Select the file and click Open.

6. Specify will exit.

7. You can check to see if the form was imported by selecting the level you imported to from the dropdown menu in Resource Import/Export. If (database) appears next to the views file, the form was imported.

[Heryk]

Hello, This part of the above tutorial seems incomplete? See image below…

[Specify]

Hi @Heryk,

Discourse (the platform that the Speciforum runs on) supports both Markdown and HTML formatting. It interpreted the <columnDef> as HTML and hid it from the post.

@Specify

<columnDef> corresponds to the Small Font Format (ideal for Windows)

<columnDef os=lnx> corresponds to the Medium Font Format (ideal for Linux)

<columnDef os=mac> corresponds to Large Font Format (ideal for Mac)

<columnDef os=exp> corresponds to Elastic Layout

It has been resolved! Thank you for mentioning it!