ORSEE3

This configuration option allows you add new data fields for participant profiles (i.e. create new columns in the ORSEE participants table, and configure the properties and behavior of those fields in the application. (IN version 2.3 of ORSEE, this functionality was located in the configuration file config/participant_form.php. It now has been extended and moved into the online configuration.)

You should read this section very carefully and make a full plan of your changes before starting implementing your changes. The involved operations (like creating new columns in the database table have the potential to break your system. Also, you should disable access to the public section (in Options/General settings) while working on the profile field setup, and maybe even consider disabling other administrator accounts during this time.

Creating a new field in the participant form involves three basic steps:

1. Create a new column in the participants table in the database.
2. Set up the properties of the respective field.
3. Put the field into the participant profile template, such that it will be shown in the profile.

Below we will describe the first two steps. The third step is described in section Participant profile template. Additionally, in Options/Items for profile fields you can add/edit/delete items for certain participant profile fields (e.g. field of studies, or professions), and in Options/Queries you configure which profile fields will be included as columns in various participant lists in the system.

The profile field main page Options/Participant profile fields shows a list of user-defined columns in the ORSEE participants table, whether they have been configured and enabled yet, and some other properties.

The button below the table allows you to create a new column in the ORSEE participants table. You are asked for a column name (which should only contain lowercase letters and underscore) and a column type. The column type can be

• varchar(250): This is the most versatile column type for number, shorter text, or any selection/multiple choice lists. It must be chosen for “select_lang” and “radioline_lang” lists to work properly. The limit to 250 characters has the advantage that the field is fully indexable under UTF-8, which implies that search for rows with a particular value in these columns will be very fast.
• mediumtext: If the field needs to store longer text (for example a textarea field like the internal notes field for participants, etc.), then this column type is appropriate.
• integer: If the field will only hold integer numbers and nothing else, then this type can be chosen. However, the performance differences to a varchar(250) field holding the same integer numbers should not be big, so for flexibility reasons varchar(250) is recommended also in this case.

After you click Create column, the function will create the new column in the ORSEE particiapnts table, and will also create a search index (that speeds up queries a lot) on this column. Please be patient. In particular when your database is very large, the operation to create a new column and a new index might take a moment. (In our test system with 8000 participant profiles but on a high-performance server it takes about 3-4 seconds.) After success, the column will be shown at the bottom of the list of participant profile fields (it is created as the last column of the table), and you can configure it.

When you click on the Configure/Edit link, a form will appear that let's you configure the display properties and behavior of this field. On the left side of the form, you enter the language symbol that represents the name of this column within the system, the form type of this profile field, and form-type specific settings. The options on the right side configure how the field is dealt with in the system, on the form, in searches, in terms of uniqueness of values, etc.

There is an (English-only) online help available for this form, the help texts will popup as tooltips when you move your mouse over the respective fields. So there is no reason to explain each field in detail here.

Whenever an option requires a language symbol (that is, an entry in the or_lang language table), this can be created in Options/Languages/Add symbol (your admin type will need the right to create a language symbol). You will need to use the same shortcut for the symbol as provided in the field.

Other fields may ask for regular expressions. The expressions need to be entered including a starting and a trailing slash (/). This allows you to add expression modifiers after the trailing slash. For a complete documentation of Perl Compatible Regular Expressions (PCRE) as used in PHP, see here: http://php.net/manual/en/pcre.pattern.php.

One special feature is that the system also allows to assign php code to an option. If the option value is preceded by func: then what follows is interpreted as a PHP expression and is evaluated in runtime before the value is assigned. For example, when you want the first value of a select_numbers list to be the year 10 years ago, then you can use func:(int) date(“Y”)-10 in Start number.

A click on the Save button will save the settings.

The Delete button on the bottom of the profile field configuration form allows you to drop the whole column and its index from the ORSEE participant table. Make sure that you removed the field from the participant profile template before deleting it here.

Please note that if you delete a profile field, the data in this field/column will be completely lost, without any chance of recovery. Simply keeping the column but disabling it might be the safer option, since you never know whether you might need it again, and keeping the unused column in the database table doesn't really affect performance.

Under Options/Participant profile form template you can change the profile form that is displayed to participants (profile_form_public ) and an admin-only section of it (profile_form_admin_part). The main difference between the templates profile_form_public and profile_form_admin_part is that in the latter you only enter participant profile fields that have been configured as admin-only in Options/Participant profile form, while in the former you can add all other participant profile fields.

The main page shows both forms in their current state (and the current draft of the templates in case they differ from the currently active version).

The participant profile form can be customized to the different sub-subjectpools defined in the system. The select list and Apply button above the template table allow you to display the profile form as they will be seen by the different sub-subject pools.

A click on the Edit button next to the respective public or admin template will take you to the template edit page. The page has three parts side by side.

• On the left side, you see the currently active template, how it is shown when persons access it in the system.
• In the middle, you have a text field were you can edit the current draft.
• On the right side, you will see how the current draft will be displayed on the system once it is enabled.

This setup allows you to safely edit and check the template before activating it. In fact, as soon as to change something in the textfield, you will not be able to activate the template or change the sub-subjectpool display until you have saved the current draft.

You are very flexible in designing the participant form. The template basically contains the HTML code that define the layout of the form. You are given a certain space on the webpage, and you can fill it however you like, using placeholders to indicate form elements that ORSEE will replace in runtime.

In the default template, there is a simple HTML table with one column, all fields are positioned below each other, with the text just above the respective form field.

There are four types of placeholders that can be used. Placeholders are always enclosed by #.

FORM FIELDS

#field_name#: If there is a participant form field defined in Options/Participant profile form that has field_name as its mysql_column_name, then this placeholder will be replaced with the HTML form item of that field. Remember that the admin-only fields are available in template profile_form_admin_part, and all other fields are available in template profile_form_public.

LANGUAGE SYMBOLS

lang[lang_symbol_name]: If a language symbol is defined in the ORSEE lang table (see Options/Languages) under the name lang_symbol_name, then this placeholder will be replaced by its value in the current language.

ERROR HIGHLIGHTING

#error_field_name#: If a compulsory or perl_regexp condition is not met for a participant form field named field_name after submitting, then #error_field_name# is replaced by a bgcolor=“orange” (or whatever color is defined in Options/Colors) when the form is returned with an error message. That is, using this as in <tr #error_email#> will highlight that table row in orange if the conditions for the email field were not met.

CONDITIONAL STATEMENTS

If a construct of the form { #some_condition# some content } is found, then first #some_condition# will be evaluated, and if this evaluation yields a non-empty non-false value, then some content is displayed (which is not displayed otherwise). The following conditions can be used as #some_condition#:

• #multiple_participant_languages_exist# evaluates to true if there are more than one ORSEE system languages available to participants.
• #is_admin# evaluates to true if the participant profile is shown in the admin section of ORSEE.
• #is_not_admin# evaluates to true if the participant profile is shown in the public section of ORSEE.
• #is_subjectpool_X# evaluates to true if the (self-selected) sub-subjectpool of the subject had the id number X. So, for example, #is_subjectpool_1# evaluates to true if this subject's subject pool is the “unspecified” default subject pool in ORSEE. The subject pool id numbers can be seen in Options/Sub-subjectpools. Note that ORSEE assumes consistency here. That is, if a form field is only defined for certain subpools in Options/Participant profile form, then it should also be only shown for those subpools in this participant form template using the #is_subjectpool_X# conditional statement above. If that construction does not match, then there might be some errors in evaluating the form. As a simple example, if Options/Participant profile form defines a compulsory form field for a subpool but that form field is not included in the form for this subpool, it will be evaluated as empty and may result in an error message when submitting the participant form.
• #is_part_create_form# Only available in the admin section, this evaluates to true when the form is displayed on a participant profile creation page (as opposed to a participant profile edit page), i.e. when you create a new participant.

Whenever you create a participant form field of type select_lang or radioline_lang in Options/Participant profile form, a new configuration option is added on the Options page under the heading Items for profile fields of type “select_lang”/“radioline_lang”. These links allow you to to add, edit, and delete fields in that select and radioline lists.

After you click on the profile field name in Options/Items for profile fields, you will see a list of all defined items in all installed languages (e.g. after clicking on Professionsyou will see the list of professions known to the system).

Use the 'Create new' button to add a new item to the list, and the 'Edit' buttons to change existing items on the list. On the edit page of an item, simply provide the item name in all installed languages. You can also drag a category name up and down in the list, and save the order by clicking Save order. The select field in the participant profile form will be populated in this order, provided that did not choose order alphabetically for this field in Options/Participant profile form.

Under this option, you can select the participant form fields that should be anonymized upon using the bulk anonymization feature, and to which values they should be set.