QBench Worksheet Markup Language

QBench Worksheet Markup Language Documentation

Overview

In each QBench assay configuration, you can optionally create a worksheet configuration. These configurations are designed to transpose paper forms or documents to an electronic format. 

The configuration is created using QBench Worksheet Markup Language (QWML). The overall layout of the worksheet can be designed using any text editor. This can be done directly in the text editor included on the QBench assay detail page, or it can be created in an external text editor, then copied and pasted into the QBench editor. Specialized input tags are created using QWML, and placed throughout the worksheet to determine where inputs will be rendered when tests are assigned and data is filled in. 

The layout design is very flexible and completely up to the user, as QWML tags can be inserted in any location in the layout.

Creating QWML tags

QWML supports several input options, as detailed below: 

• input: a single line text input.
• textarea: a multi-line text input, typically used for paragraph style input.
• checkbox: a checkbox input that can be toggled on and off.
• select:  an input that allows the user to select one value from a list.
• calculation: a read-only input that has its value evaluated using a user-defined mathematical expression that can reference other input values or other QBench object fields.
• condition: a read-only input that has its value evaluated using a user-defined boolean expression that can reference other input values or other QBench object fields
• static: a read-only field that displays the value of a field from another data type (sample, order, etc).
• foreach:  a method to dynamically create other input options per associated Sample or Test on a Batch (this tag is only supported for worksheets on a Batch).

Each input tag begins with two underscores and an opening parenthesis, and ends with a closing parenthesis followed by another two underscores. At a minimum, you must include the the input type you want to render and a distinct name for the input, separated by a comma inside the opening and closing parentheses. You can see some examples of this format below: 

The following would render a text input:

__(input,input_1)__

The following would render a paragraph style input: 

__(textarea,textarea_1)__

 The following would render a checkbox: 

__(checkbox,checkbox)__

Required Values

Input, textarea, and select tags support the ability to make them required, meaning they cannot be left blank. You can specify a required tag as shown in the example below:

__(input,input_1,required)__ 

Incremented Values

Input tags support the ability to use a key binding to increment the value by a certain amount. By adding the additional tag attribute “increment_by=X”, pressing “Alt + Up/Down Arrow” will increment/decrement the value by X, respectively. This keybinding will default to incrementing by 1 if the tag is missing. For example, 

__(input,input_1,increment_by=3)__ # Increments/decrements by 3
__(input,input_2)__ # Increments by 1

Default Values 

Input, textarea, and select tags support default values. You can include the default value inside the tag following the tag name as shown in the example below:

 __(input,input_1,default_value="Not detected")__

Please note that the value following the equals sign should be wrapped in double quotes. 

Default Numeric Values

Input, textarea, and select tags support default numeric values. You can include the default numeric value inside the tag following the tag name as shown in the example below:

__(input,input_1,default_numeric_value=2)__
__(calculation, calculation_1, input_1 * 2)__
__(condition, condition_1, input_1 > 1, true_value=”Pass”,
 false_value=”Fail”)__

Please note that the value following the equals sign should NOT  be wrapped in double quotes. By specifying a default numeric value, calculations and conditions are able to be evaluated utilizing this numeric value. The input, textarea, and select will not display the default numeric value in the field but will utilize the number for calculations and conditions. 

Select Options

When creating a select tag, you must also specify the options you would like to have available to choose from. These are listed similar to the default value, but the list of options must be wrapped in brackets, and every option should be wrapped in single quotes. You can see an example of this below:

 __(select,dropdown_1,options="['Option 1','Option 2','Option 3']")__

Calculations 

When creating a calculation tag, you must include the tag type, name, and also a mathematical expression, which can reference worksheet values as well as QBench object values. Worksheet values can be referenced using their tag names, and QBench object values must be wrapped in brackets and preceded by a dollar sign. You can see a detailed example below:

You have a field defined for sample called "weight". You also have an input configured as follows:

__(input,input_1)__ 

The following calculation tag would multiply sample weight by input_1:

__(calculation,calculation_1,(${sample.weight} * input_1))__ 

Calculations can also reference other calculations. Consider that we also have the following input:

__(input,input_2)__ 

The following calculation tag would multiply calculation_1 by input_2:

__(calculation,calculation_2,(calculation_1 * input_2))__ 

Please note that if text values are entered for any values being calculated against, the calculation input will display an error.

Conditions

When creating a condition tag, you must include the tag type, name, and also a boolean expression, which can reference worksheet values as well as QBench object values. Worksheet values can be referenced using their tag names, and QBench object values must be wrapped in brackets and preceded by a dollar sign.

Valid boolean expressions: 

Expression	==	||	&&	( )
Explanation	Checks if value_1 is equal to value_2	Notation for “or”. Evaluates to true if either value is true	Notation for “and”  Evaluates to true if both values are true	Expressions in parentheses will evaluate first.
Example	value_1 == value_2	value_1 || value_2	value_1 && value_2	(value_1 && value_2) || (value_3 && value_4)

You can see detailed examples below:

You have a field defined for sample called "weight". The following condition tag would check if sample weight is less than 100

__(condition,condition_1,(${sample.weight} < 100))__ 

Conditions can also reference other conditions. Consider that we also have the following tags:

__(input,height)__
__(condition, condition_2, (height < 5.5))__ 

The following condition will return true if both condition_1 and condition_2 are true:

__(condition,condition_3,(condition_1 && condition_2), true_value=”Pass”, 
false_value=”Fail”)__ 

Please note that if any data is missing for the evaluated boolean expression, the condition value will be blank.

HTML Formatting

Most QWML tags provide support for the “html_style” attribute. This provides a way to apply inline CSS to the input box that gets generated. For example,

__(input,input_1,html_style=”color:red”)__

Static

When creating a static tag, you must include the tag type, followed by the QBench object type and field name separated by a period. Static tags do not require a name. You can see a detailed example below:

You have a field defined for sample called "weight". The following static tag would be replaced with the value entered for the sample weight when the worksheet is rendered:

__(static,sample.weight)__ 

Please note that if the field name does not exist for the object, the static tag will be blank when rendered.

Additional Key/Value Pairs

Every tag type supports adding additional key value pairs, entered using key=value format and separated by comma. You can see an example of this below: 

__(input,input_1,default_value="20",display_name="Input One",
units="mg/g")__ 

In this example display_name="Input One" and units="mg/g" function as additional key/value pairs. These values can be accessed in QBench reports and by other external/third party applications via the QBench API.

Creating a Worksheet Layout

When creating a worksheet layout, it is a good idea to clearly label your inputs so the user can easily identify the data they are looking to fill out. See a basic example of a worksheet layout below:

Please enter data found for the following compounds:

Compound #1: __(input,compound_1,display_name="Compound 1")__
Compound #2: __(input,compound_2,display_name="Compound 2")__
Compound #3: __(input,compound_3,display_name="Compound 3")__
Compound #4: __(input,compound_4,display_name="Compound 4")__
Compound #5: __(input,compound_5,display_name="Compound 5")__

You can make use of any text editing tools (tables, lists) to create a worksheet layout. When configuring a worksheet, you can preview your changes any time by clicking the Preview button next to Save button in the worksheet tab of the assay detail page. The inline text editor in QBench formats what is entered into HTML. This is what allows the worksheet layout to be rendered within the application.

Foreach

When creating a foreach tag, you must include the tag type, name, and also the data type being referenced in the loop (tests, samples or batches). If the foreach is in a table, you must also specify the direction in which you want the data to be copied (row, col). You will also need to end the foreach tag with an endfor tag after writing out all the data you want copied. The endfor tag must include the tag type and name used for the foreach tag. **All tables, rows and cells encompassed in a for loop cannot have any other tags within themselves. You must use in-line styling to format the cells in the table**

Basic example of using the foreach syntax.

__(foreach, foreach_samples, samples)__
__(static, sample.id)__
__(input, input_1)__
__(endfor, foreach_samples)__

Basic example of using the foreach syntax in a table for rows

Sample ID	Moisture
__(foreach, f_samples, samples, row)__
__(static, sample.id)__	__(input, moisture)__
__(endfor, f_samples)__

Basic example of using the foreach syntax in a table for columns

Input	__(foreach, table_t, tests, col)__	__(input, input_table_t)__	__(endfor, table_t)__
Label		Goodbye
Calculation		__(calculation, calc_table_t, input_table_t + 1)__

You can include anything in the middle, including other QWML tags

Jinja2 Support

QWML supports the use of basic Jinja2 statements. 

{% if test.results >= 42 %}
    __(input, input_1, default_value=”Greater than or equal to 42”)__
{% else %}
    __(input, input_1, default_value=”Less than 42”)__
{% endif %}
<span>{{ test.assay.category.name }}</span>
<span>{{ test.sample.weight }}</span>