matrixdef_File_Syntax

matrixdef File Syntax

The file matrixdef defines the Matrix customization web interface, specifically the form fields that appear, their possible values, and the HTML surrounding and formatting them. It currently allows for sections, labels, check boxes, radio buttons, and text fields, and is broken up into sections, each of which corresponds to a different sub-page of our multi-page questionnaire.

The file consists of a series of form-field declarations, separated by blank lines. The syntax of a form-field definition in matrixdef is as follows:

Keyword Variable-Name "Friendly-Name" ["HTML-before" "HTML-after" [Width]]

• Keyword is one of { Section, Label, Check, Radio, Select, MultiSelect, Text, TextArea, Hidden, File, Button, BeginIter  }

• Variable is the name of the form field, consisting of alphanumeric characters, _, and -. Generally, variable names should consist of English words or abbreviations separated by -. Iterable choices are separated by _. Thus, variable names are described the the following regular expression: ([-a-zA-Z]+[0-9]+_)*[-a-zA-Z]+

• Friendly-Name is an English-language name for the form field that will appear in the main page of the questionnaire

• HTML-before is the HTML that will appear before the form field

• HTML-after is the HTML that will appear after the form field

• Width is the width, in characters, of a text field

The last three parts of a form field definition are irrelevant for keywords Section and Label, and the last, Width, is only relevant only the Text keyword. Irrelevant parts of a definition are ignored.

Section and Label

Section produces a heading in the HTML file. Label allows arbitrary HTML to be added to the page, such as notes or labels.

Check

Checkboxes are boolean (yes/no) choices for the user-linguist to choose.

Iterables

Iterables define a section of choices that can be entered multiple times by a user. A button which copies the definition of choices within the iterable allows the user to define more choices.

Iterables are enclosed by the BeginIter and EndIter keywords.

Radio Buttons

Radio buttons have additional syntax associated with them. Whereas the other form field definitions consist of single lines separated by blank lines, radio button definitions consist of multiple lines: the first defines the name of the radio button group and the subsequent lines define the radio buttons and the values associated with them.

• Radio variable "Friendly-Name" "HTML-before" "HTML-after"

• . choice-variable "Choice Friendly-Name" "Choice HTML-before" "Choice HTML-after/Choice Text"

• . choice-variable "Choice Friendly-Name" "Choice HTML-before" "Choice HTML-after/Choice Text" disabled_flag_x

• . etc...

A sample radio button definition appears below:

• Radio neg-infl-type "Negative inflection type" "On: " ""

• . aux "Auxiliaries only" "" "auxiliaries only "

• . main "Main verbs only" "" "main verbs only "

• . aux-main "Main or auxiliary verbs" "" "any finite verb (main or auxiliary)<br>" x

Notice that the radio button lines have a keyword of ".". This is a placeholder that keeps the number of parts in all definitions consistent. The definition above produces the following HTML:

• On:
  <input type="radio" name="neg-infl-type" value="aux"><label>auxiliaries only
  <input type="radio" name="neg-infl-type" value="main">main verbs only
  <input type="radio" name="neg-infl-type" value="aux-main">any finite verb (main or auxiliary)<br>

Select and Multiselect

Select (which creates drop-downs) may also have additional syntax. A 'select' line may be followed by one or more lines specifying the values in the drop-down. These values can be defined overtly as radio button values are defined above.

Multiselect creates drop-downs which allow for multiple choices to be checked. Otherwise, they are the same as Select.

An upcoming feature of Multiselect allows an option to be greyed out by putting an "x" flag after the option.

• Normal option:

  • . ap "AP" "APs"

  Greyed out option:

  • . pp "PP" "PPs" x

Alternatively, or in addition, Select and Multiselect lines may be followed by 'fill' statements that can take zero or more arguments, e.g., fillregex p=number[0-9]+_name n=1, where the arguments in this example are p=pattern and n=1. Possible arguments are defined in deffile.py.

Text and TextArea

Text inserts a small text input box, while TextArea inserts a larger one. As noted above, these also support the special Width keyword, to specify the maximum length of the input. There is also an OnChange flag that allows JavaScript to be associated with the OnChange event of the text field (that is, code that is executed when the text box changes).

Hidden

Add information to the HTML page hidden from the user, such as JavaScript.

File

Define a file.

Button

Define a button.

Fill commands

The possible fill commands are as follows:

• fillregex p=REGEXPATTERN (n=1)	Searches item on current page matching the regular expression REGEXPATTERN. If n=1 is given, only the variable name will be displayed, rather than "variable (friendly)" names
  fillnames c=CATEGORY	Fill with feature names from CATEGORY
  fillvalues p=PATTERN (l=1)	Fill with values from PATTERN. If l=1 is given, PATTERN is just a feature name. Otherwise it is a key specifying an element on the page
  fillverbpat	(No arguments) Fill with verb patterns (currently "intransitive" and "transitive")
  fillnumbers	(No arguments) Fill with the number features
  fillcache c=CACHENAME	Fill with items in the cache CACHENAME. The cache is created with a Cache command (see below)

Choice Caching

A questionnaire page does not have direct access to the choices file or other questionnaire subpages, so if you need values from other pages you can use a Cache command to store them in a Javascript array.

Cache CACHENAME REGEXPATTERN DISPLAYSUBKEY

The Javascript variable will be called CACHENAME, and will include any items matching REGEXPATTERN. This regular expression must match the beginning of the choice key, but is not required to match the end of the key. Thus, if you want to get non-terminal choices (e.g. noun1, but not noun1_name, noun1_feat1_name, etc), use a $ at the end of the pattern. DISPLAYSUBKEY, if provided, is used to get the choice value displayed in the questionnaire. For instance, if you want to cache all nouns, but want them to be displayed by their name, use the following:

Cache nouns noun[0-9]+$ name