Datasets forms
In order to transcribe items in a dataset, you must build a form for the dataset. Forms provide the framework for the structured transcription in DataScribe. When building forms for your datasets, take some time to look at your historical sources and think about how you want to organize your forms. With some sources, it might be worth creating multiple forms to capture distinct subsets of data on the same page.
You may find it useful to have a reference image or outline of the data you're collecting when you build the form.
To create a form, use the action menu in the upper right corner to select “edit dataset,” which will take you to the Edit page. The edit page has two tabs, a general tab where you can edit the information you entered when adding the dataset. The second tab is where you build the form for the dataset.
On the Form Builder tab, you will see a drawer on the right with options for building the form.
Above the drawer are three buttons: "Cancel," "Delete," and "Save and...". The Cancel button will cancel all changes and return you to the dataset view. Delete will delete the dataset. "Save and" acts as a dropdown with two options:
- Save and Return to dataset items will save your changes and return you to the browse view of the items in your dataset;
- Save and Continue editing dataset will save your changes and reload the page, keeping you on the Form Builder tab.
When you use a "Save and..." option, the page should reload with a green banner near the top of the page with the message that the dataset has been edited.
DataScribe has the following options on the form builder: Checkbox, Date, DateTime, Number, Radio, Select, Text, Textarea, and Time. Use the plus button to add a field of the desired kind to the form.
Every field type in the form has the same four initial options:
- Field name (required): will display for transcribers
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- A form can only have one primary field.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
Some fields allow you to use regular expressions (RegEx) to validate field entry. To learn how RegEx works, see this Programming Historian tutorial and RegEx 101. The module uses the RegEx library associated with Laminas.
In addition to these standard options, each field type has its own options.
This creates a checkbox for the form
Options are:
- Field name (required): the name of the field will display in the transcription form.
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Checked value: use this to set how this information exports. Defaults to 1.
- Unchecked value: set how this information exports. Defaults to 0.
- Checked by default: checkbox
- Checkbox label: set the label for the checkbox (separate from the field name)
The image below shows a checkbox in action from the transcriber's perspective. The field name is "Pastor's Residence" and the description is "check only if there is a residence...". The label for the checkbox is "Yes." The checked and unchecked values are not visible to the transcriber.
Create a date field (using the Gregorian calendar) which will be exported in ISO 8601 date format.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers when they are doing data entry.
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Minimum year: Set the earliest year which a transcriber can select from the dropdown. Enter a four digit year (YYYY)
- If left blank, this will default in the transcription view to 100 years before the present year. If you want to set a range longer than that, you must enter a minimum year.
- Maximum year: Set the latest year which a transcriber can select. Enter a four digit year (YYYY).
- If left blank, this will default to the present year, regardless of the minimum year.
- Default year: set a default year for entry.
- The year selection is a dropdown, so if you have a very long span of years, consider setting a default in the middle of the range.
- Default month (optional): select from a dropdown of months.
- Default day (optional): select from a dropdown of days.
In the example below, the field name is simply "Date". The yellow asterisk next to the field name indicates that this is the primary field for this form. The year and month dropdowns have already been selected to 1800 and August. Note that the month dropdown uses the full written name of the month - "August" - rather than a short form like "08" or "Aug". The number selection option is open, showing the dates in order starting with 01.
Create a field with both date and time entry options. As with the Date option, all dates are will be exported in ISO 8601 format using the Gregorian calendar. Transcribers select from a dropdown for the year, month, day, and hour, minute, and second.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers when they are doing data entry.
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Minimum year: enter the minimum year in four digit format (YYYY).
- If left blank, this will default in the transcription view to 100 years before the present year. If you want to set a range longer than that, you must enter a minimum year.
- Maximum year: set the latest year a transcriber can select. If left blank, this will default to the present year.
- Default year: set a default year for entry.
- Years appear as dropdowns; you can place this at the start or in the middle of your time span. Not required.
- Default month (optional): select from a dropdown of months.
- Default day (optional): select from a dropdown of days.
- Default hour: select from a dropdown, 1-23
- Default minute: select from a dropdown (00-59)
- Default second: select from a dropdown (00-59)
In the example below, the field name is "Start time" and the description explains that time should be entered to the hour and minute, with the second included only if known. The year, month, day, and hour inputs have been selected to display 1950 April 08, hour 19. Note that the hour dropdown is in 24-hour time, not an am/pm display.
This field only allows numeric data - users must enter numerals (1,2,3) not typed descriptions of numbers.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers when they are doing data entry.
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Minimum value: sets the minimum allowed value for this field.
- Maximum value: sets the maximum allowed value for this field.
- Stepping interval: sets the interval to which any entered data must adhere.
- Placeholder: example value to display when the field is empty.
- Regex pattern: set a regular expression pattern which the field input must match.
- Default value: set a default value for the field
- Number input label: changes the label of the field.
- Datalist: displays recommended options.
The image below shows a number input on the transcription form. The field name is "Pounds" and the description is "first of three columns on right". The number field will only allow entry of numerals ("1") not numbers written as words ("one"). Clicking on the up or down arrows on the right of the number field will step up or down in the interval defined in the settings for this block.
Create a set of radio buttons with options from which transcribers can select a single response.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers when they are doing data entry.
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Selection label: add a label for the radio button array.
- Options: enter the label text for the radio buttons.
- Each option must be on a new line in the text area.
- Default value: must match one of the options entered in the options field.
This image shows a radio block with entries in the options field to show that each option must be on a new line.
This image shows the transcriber's view of the above radio field. The field name is Transaction type, with a description of "Dr or Contra (Cr)". Each line in the options table appears as a separate radio button: "Debit (dr)" or "Contra (cr)" with the additional option of "No selection" set as active.
When there are more options than can fit on one line for the transcription view, the radio block will wrap buttons (see the Select example for more information).
Create a dropdown with options for transcribers to choose from, created by the form builder.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Selection label: Changes the label for the dropdown menu. If nothing is entered, the dropdown is labeled with "Select."
- Options: enter the text for each choice to appear in the dropdown.
- Each option must be on a new line in the text area.
- Default value: must match one of the above options.
In this example, the field name is Transaction type and the yellow asterisk next to the name indicates that it is a required field. The description is "Dr or Contra (cr)." There are two lines in the options field: Debit (dr) and Contra (cr).
This image shows the appearance of the select in a transcription form. The select label has not been changed, so the menu is just called "select". The dropdown menu is open and shows the default option "No selection" along with options to select Debit (dr) or Contra (cr).
Select and Radio have similar functions; the select dropdown will not allow transcribers to set more than one option using keyboard commands. The Select block may be preferable when there are a large number of options to list. In this example, the Radio and Select blocks have the same options. The Radio block has wrapped to show all eight radio buttons, while the Select block remains a basic dropdown regardless of the number of options.
If you are using Custom Vocab for you Omeka items, you can manually duplicate the options into a select dropdown for DataScribe. Copy and paste the the list from the Custom Vocab configuration into the options textarea for the select field.
Create a field for a single line of text.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- A form can only have one primary field.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Text input label: adds the display label for the text entry area.
- Minimum length: sets the minimum number of characters which a transcriber can enter.
- Maximum length: sets the maximum number of characters which a transcriber can enter.
- Placeholder: example value to display when the field is empty.
- Regex pattern: set a regular expression pattern which the field input must match.
- Default value: set a default value for the field
- Datalist: displays recommended options for entry. Each option must be on a new line.
This image shows that the text field has a single-line entry area. The description, input label, and placeholder have all been populated with text reflecting their purposes.
Create a field with space for multiple lines of text.
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Textarea label: changes the display label for the field.
- Rows: set the number of visible rows for text. If left blank, this defaults to three rows.
- Minimum length: sets the minimum number of characters which a transcriber can enter.
- Maximum length: sets the maximum number of characters which a transcriber can enter.
- Placeholder: example value to display when the field is empty.
- Regex pattern: set a regular expression pattern which the field input must match.
- Default value: set a default value for the field.
This image shows a textarea field with the default height of three rows. The description text is "description of this field's purpose" and the placeholder text is "This is some placeholder text".
Create a field which allows entry of time data (no date)
Options are:
- Field name (required): will display for transcribers
- Field description: will display for transcribers
- Field is primary: checkbox to set whether this is the primary field, ie the field by which the record is identified.
- Field is required: checkbox.
- Note that if a field is marked as required and is left blank by a transcriber, it will be marked as invalid.
- Default hour: select from a dropdown (1-23)
- Default minute: select from a dropdown (00-59)
- Default second: select from a dropdown (00-59)
This image shows a time block in the transcription view with the dropdowns set to 20:20:54, or 54 seconds past 8:20 pm.
At any time when you are building or editing a form, you can save your progress.
The "Save and..." button in the upper-left corner of the browser window opens to reveal two options:
- Save and Return to dataset items will save your changes and return you to the browse view of the items in your dataset.
- Save and Continue editing dataset will save your changes and reload the page, keeping you on the Form Builder tab. A green banner should appear near the top of the page with the message that the dataset has been edited.
As you are building your form, you can save and continue to edit.
Once you have saved your form, you can return to edit it at any time by going to the dataset page and clicking "edit dataset". From there you can select the Form Builder tab.
When you edit each field, you have access to all of the same options as when you added it. If a field is collapsed - showing up only as a gray bar - click the arrow on the right end of the bar to expand the field and edit it.
Once you have multiple field blocks in a form, you can change the order of the fields in two ways:
Drag and drop the fields by clicking and holding on the triple-bar icon on the far left of the field block, then dragging the block to the location you want it to appear.
Click the up and down arrows on each field in order to move it exactly one spot higher or lower in the field order. It will move above or below the field immediately adjacent.
In the image below, the A arrow points to the drag and drop icon and the B arrow points to the up and down arrows.
If your form will have more than 75 fields, you will need to increase the default setting for max_input_vars of the PHP on your server. You may need to ask a systems administrator to do this for you. If you are using Reclaim or other hosting companies which use CPanel, you may be able to do this yourself by following these instructions.