Creating Forms - KCL-BMEIS/xnat_form_maker GitHub Wiki

FormDetails Sheet

Open a template xlsx file. Select sheet FormDetails. Fill in the schema name at the top (in red). Schema names, datanames and subnames must conform to the XML Namespace Specification: No Spaces or underscores, dashes or any special characters can be used and names cannot start with numbers. In the example below, the schema name is wikidemo. This will be used to store tables in the XNAT database and the generated plugin will be named after this.

formdetails_formmaker_demo2

Figure 1: FormDetails Sheet

For each form, write the title, data name, description etc as example above. Data Names are the names as stored in the Postgresql database. These must conform to XML Namespace specification - and cannot contain spaces, special characters or start with numbers. You have to select whether this is subject or imaging session specific by typing image or subject in the Extension/Level column. Subforms can also be created which can be referenced from Subject/session forms. This can be useful when you have many large repeated sections in the main forms.

For each form, fill in corresponding sheet (form1, etc).

If you would like the menu item to only appear in certain projects, fill in B2 - Restrict to Project:. This is a wild card search for the project ID. If the project ID contains the text in cell B2, the menu Item Add Assessor for this form will only appear in the projects containing the text. In the example above, it will only appear in projects containing TEST in the project ID.

Filling in Form Sheets

The form sheets describe the questions - the form elements and whether they are dropdown menus, text boxes, date boxes etc. The form elements are in the same order as they are listed in the spreadsheet. Therefore sections in the XNAT form must be grouped together in the spreadsheet.

There is a limit of 500 questions per form. If you require more, consider using subforms, described at the end of the page.

An example is shown in Figure 2

Question title:

This is the text that appears for the question.

Data Name:

This is compulsory. It is the name of the element as stored in the database

Subname:

If two or more questions are linked (a subsection of the form) then a subname can be used. The questions share the same dataname but have different subnames. As these represent a section in a form, questions of the same dataname must be grouped together and in order.

If more than one question share a dataname, then all questions must have a subname. The only exception are some special types - ynuo - which have subnames built in.

These are also used for special types of elements, for example ynou, where a sub-question only appears if yes is selected. For example , Was test A completed?. If yes is selected, then questions appear regarding the test. Subnames must be present if using a special type.

Form Types:

Select whether this is either a : Form type: tickbox, textbox, textarea (larger text field), radio, dropdown, date, header, subheader, paragraph or one of the special form elements (ynuo, ynu etc). See the next section for in-depth details.

Data Types:

This is the type of data to be stored in the Postgresql database. The default is string for textboxes, bool for tickboxes, date for date and string for dropdown options. You do not need to enter this field unless you specify a non-default type - for example int in dropdown menus or float for textboxes.

Allowed data types are string, int, float, bool and date.

Length Restriction:

If the datatype is string, then it is wise to restrict the length of the string to prevent website issues. For example, entering 400 would mean the maximum length of the input is 400 characters.

For shorthand, if int is selected in Data Type, this will set the maximum value permitted.

Options:.

For dropdown menus and radio buttons, this provides the list of options. Use comma-seperated values (for example 'head,body,feet').

For shorthand, if the dropdown is a list of numbers a range can be used - for example 5-50 will list the numbers 5 to 50.

session_form_spreadhseet

Figure 2 - example of form CLICK ON IMAGE FOR LARGER VIEW

Hide: Data fields cannot be removed from a form once it is installed in an XNAT. However you can update the plugin and hide the field in the form, so the question will not be displayed. Mark this column with an 'x' or 'y'

Required:

Mark this column with an 'x' or 'y' to make this field required.

Datatypes and Form Elements in detail

The data types and form types permitted are:

  • string: textbox, textarea, dropdown
  • date,datetime,string: date, datetime, time
  • bool: tickbox
  • int: radio
  • special: yn, ny, ynu, ynuo, multipanel

In addition, to display text:

  • header, subheader, paragraph

The Datatypes column is optional. By default, everything is stored as strings in the XNAT database, including lists for dropdown menus. Although not an efficient method of storing data, for some pages in XNAT, only the int value would be displayed if storing as ints. If the dropdown list contains numbers, then this would cause significant confusion.

The exceptions are tickboxes, which are stored as bool, and date which is stored as date type in the database.

  • Dropdown Menus

For dropdown Menus, for example What is your age? or What is your favorite colour?, you must type dropdown in the Form Type column and write a comma-separated list of options in the options column.

Dropdown menus store lists as strings in the XNAT database. You may store the string options as ints in the database - a more efficient method, with the numbers referring tot he options in the edit forms/reports. To do this, choose int in the Datatype column.

For number-ranges (What is your age?), you can use shorthand for a range, for example 1-100 will create a list from 1 to 100, as shown in Figure 2. These will be stored as strings.

If you wish to store as int, it must be a range starting from 0 - for range 0 to n, choose int in the Datatype column and then set the value n in the Length Restriction column.

  • Textboxes

Length Restrictions: If using textboxes, it is good practice to set a limit to the size of the input to prevent possible attacks. For example, in Figure 2, What is your name? is restricted to 400 characters.

DataTypes: Textboxes can be stored as string, int or float. The default is String.

  • Textarea

This is a large textbox.

  • Date, Datetime, Time

These will create a date box, a time box or both allowing the user to select these.

  • Text types: Headers, Subheaders and Paragraphs

Inserting any of the texttypes into the Form Type column will create a header/subheader/paragraph type, displaying the text in the 'Question' column. Leave Dataname or Subname empty as this is not stored in the database, unless it is inside a panel - then you must include the dataname of the parent.

  • Special Form Types

Certain form types have been used repeatedly hence shorthand types have been built into the Form Maker. These are usually for creating panels containing optional questions. If a test was completed, then a panel may appear containing the results of the test, for example.

  • yn - Yes/No Toggle Panel. This opens a panel of questions if yes is selected. The questions in the panel must have the same Data Name but must have different Subnames. An example is shown in the Figures - Do you swim?. If yes is selected, then the sub question What is your favorite time? appears. They both have the same Data Name but different subnames. There is no limit on the number of sub-questions in a panel.

See Examples for an example of yn special type.

  • ny - As above, but opens panel if no is selected.

  • ynuo - This was developed for neuropsychological forms in response to the question Was the test completed?. ynuo is shorthand for Yes, No, Unable for Health Reasons, Unable for Other reason (please specify). If Unable for Other is selected, a dropdown menu will appear with a series of reasons that can selected. If sub-questions (same data name, but different subnames) exist, they will appear if yes is selected.

  • multipanel - this is a yn toggle panel, where different panels open depending on whether y or n is selected. In order to select which quesitons, under the Options column, write:

Y=[number of yes questions],N=[number of questions in No panel]

Then List the questions as before. The questions int he YES panel MUST be first, then list the questions for the No panel. All these questions must share the same dataname and have unique subnames.

session_form_edit

Figure 3: Subject Edit Form

session_form_report

Figure 4: Subject Report Form

Subforms

Subforms are forms that can be created that can be referred to in other forms. This is handy if you have large, repetitive subset of questions.

To create subforms, create forms as detailed above. In the Form Details sheet, put the form level as subform. Any subforms must come after any subject and session level forms.

subform_form_details_page_example

In the form referring to the subform, create an question and put subform under Form Type. Under the options column enter the subform name (from the Name column in the Form Details sheet.

In the following example, a yes/no question appears - 'test yn with subform'. If yes is selected, a subform appears. This is the questions contained in the Form3 - Test Subform

subform_form_example

Examples

Example of yn Special Type

This example of a yn special type will create a section in the form, with the title Neuropsychology Test. If the question Was the test completed? is Yes, then a panel of questions appear, in this case just one question is in the y panel - What was the score?.

example_yn_spreadsheet_form_maker

The header appears in bold - a subtitle - in the form. The questions will be stored in the database as np_completed and np_scores. What was the score? will only appear if Yes is selected. You can have more questions appear - there is no limit on the number of questions in the y panel.

wiki_form_maker_yn_demo

Example of Multipanel Special Type

mpexample

Using the above will result in:

mpform