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, Separator, Radio, Select, MultiSelect, Text, TextArea, Hidden, File, Button, BeginIter, Cache  }

• 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, Label, and Separator

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

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.

e.g.

    BeginIter forbid{k} "a Forbid constraint"
    
      Select others "Noun Position Class {i} Lexical Rule Type {j} forbids" "Lexical Rule Type {j} forbids the following: " ""
      fillcache c=nouns
      fillregex p=noun-pc[0-9]+(_lrt[0-9]+)?_name
      . noun "Any noun" "any noun"
    
    EndIter forbid

where the syntax of BeginIter is as follows:

•  BeginIter VariableName{counterVariable} "HTML" show_hide:bool iter_min:int 

The above matrixdef definitions create HTML with appropriate javascript functions to generate an iterable select option. This can be viewed live by looking at the forbid constraints on lexical rules on the Morphology page.

These options are defined as follows:

• VariableName Name of the iterable

• CounterVariable Variable to be defined and used in the iterable and objects associated with it: for instance, in naming lexical rule instances, there is a counter for the position class (i), lexical rule type (j), and the lexical rule instance (k).

• "HTML" HTML value to show the user, akin to the "friendly name"

• show_hide Boolean value represented as 0 or 1, where 1 adds the show_hide option to the iterable, allowing the iterable to be collapsed using an arrow. 0 does not include this functionality for this iterable.

• iter_min Integer count for minimum/default number of iterables. For instance, a choices file is deemed acceptable if one noun and two verbs are defined. This is prompted to the user by setting the iter_min of the "noun" iterable to 1 and the iter_min of the "verb" iterable to 2.

Forthcoming syntax allows iterables to be toggled given a choice on a different subpage. For instance, Incorporated Stem Lexical Rules are only available on nouns in the Morphology page if the "Some nouns in this language take adjectives as incorporated affixes:" checkbox is checked. The name of this Check option is "adj_incorp", and so to create an iterable that is skipped if "adj_incorp" is checked, the following syntax is used:

•  BeginIter VariableName{counterVariable} "HTML" show_hide:bool iter_min:int "VariableNameToSwitchOn" 

e.g.

•  BeginIter is-lrt{j} "an Incorporated Stem Lexical Rule Type" 1 0 "adj_incorp" 

Using this syntax, if the choice named "adj_incorp" has a value, the iterable will appear, else, it will not.

Note that if an iterable is activated by some choice, filled out, and then the choice that it switches on is deactivated, the iterable and its data will be lost. This is intended behavior.

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"<<BR>>
    . choice-variable "Choice Friendly-Name" "Choice HTML-before" "Choice HTML-after/Choice Text"<<BR>>
    . choice-variable "Choice Friendly-Name" "Choice HTML-before" "Choice HTML-after/Choice Text" disabled_flag_x<<BR>>
    . etc...

A sample radio button definition appears below:

    Radio neg-infl-type "Negative inflection type" "On: " ""<<BR>>
    . aux "Auxiliaries only" "" "auxiliaries only "<<BR>>
    . main "Main verbs only" "" "main verbs only "<<BR>>
    . aux-main "Main or auxiliary verbs" "" "any finite verb (main or auxiliary)<br>" x<<BR>>

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: <<BR>>
    <input type="radio" name="neg-infl-type" value="aux" id="choiceID1"><label for="choiceID1">auxiliaries only </label><<BR>>
    <input type="radio" name="neg-infl-type" value="main" id="choiceID2"><label for="choiceID2">main verbs only </label><<BR>>
    <input type="radio" name="neg-infl-type" value="aux-main" id="choiceID3"><label for="choiceID3">any finite verb (main or auxiliary) <br></label><<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