EvalCGI :: Overview :: Directories :: Forms :: Flags :: Security :: Utilities :: EvalSuite

Background

Evaluation forms are formatted using a simple markup language called ETX (short for "evaluation text"). ETX files are plain text and end with an ".etx" extension. You may use a word processor to format ETX files, but the final results must be converted to plain text before they can be used on the server. Think of these files as recipes. The evalCGI program will convert them into fully functional HTML forms on demand. ETX files have two parts, a header with information about the form followed by the form elements. The header and form elements are separated from each other by a blank line.

Sample ETX File

Here is a short sample file called "Hypothetical Student Evaluation Form." The takers are biochemistry faculty and the subjects are members of the class of 2006. This form will be 'named' (not anonymous) and faculty may evaluate each student up to three times. There are two scaled questions, one text entry area for comments, and one line of instructions.

Hypothetical Student Evaluation Form
biochemfac,class06,named number3

Please fill out this form at least once for each student.

?Student's level of participation in today's activity:
/Held Back/Average/Very Engaged

?Overall evaluation of student up to this point:
/Poor/Fair/Good/Very Good/Excellent

?Comments:
text

Form Header

The first few lines of an ETX file provide information about the form. The first line will become the title. Choose a title that clearly describes the form's purpose in five to ten words. The second line controls the form's behavior and has three parts separated by commas:

takers,subjects,flags

A form with no takers, subjects, or flags would have the word 'none' three times on the second line:

none,none,none

A taker is someone who may submit the form. Specifying 'none' for takers makes the form open; anyone can submit the form as many times as they like. A subject is a person or thing to be evaluated. Takers select subjects from a menu. If there are no subjects specify 'none'. The following table summarizes these options:

Takers and subjects are defined by access control list (ACL) files. For example, takers might refer to a list called "students" and subjects refer to a list called "faculty". ACL files are just lists of user ID codes, one per line. You can combine ACL files using '+' and '-' characters. You can also mix ACL files with single user IDs. The only rule is that all the '+' items must come before any '-' items. In these examples, class05 and class06 are ACL file names while students 1-3 are individual ID codes:

class05+class06-student1
student1+student2+student3

Think of flags as switches that change the behavior of your forms; they override the defaults built into the system. Use spaces to separate multiple flags. There are many flags for special situations. Here are a few of the more useful ones:

Examples of three typical control lines:

class06,biochemfac,none
biochemfac,class06+class05,named
class06-student1,none,number3 start030701 stop030704

Question Stems

In the example above you will notice that questions and answers are blocked together and set off by blank lines. The system will number questions in sequence automatically. Question stems are indicated by a leading '?' character followed by the text of the question on a single line:

?Your overall rating of this instructor:

You may make an individual question required by adding a second '?' to the beginning of the line:

??Your overall rating of this instructor:

Aggregate questions begin with a '?!' sequence. Data from these questions is recorded normally and additionally in global subject files that cross form and directory boundaries. This question type is more meaningful if you add categorical information between square brackets '[]'. Categorical information is useful but optional in other contexts. This example will aggregate a 'general' rating across multiple forms:

?![general]Your overall rating of this instructor:

Demographic questions begin with a '?@' sequence. Use this type for questions that do fit with scaled answers (eg, location, rotation, month, session, favorite color, etc.) Demographic questions always require an answer. Data from these questions are handled in a special way to allow sorting and filtering:

?@Where did you attend this class?

Answer Scales

The most common answer type uses radio buttons to present a scale of responses. For example:

The scale is specified on the line immediately after the question stem using '/' characters at the start of each item:

?Your overall rating of this instructor:
/Poor/Fair/Good/Very Good/Excellent

This answer type works well for scales with two to seven items. If a scale is not provided, the program provides a default five-point scale (strongly disagree, disagree, neutral, agree, strongly agree).

When the scale descriptors are short, the entire scale will fit on a single line. There is an alternative for long descriptors consisting of lines beginning with '%' characters:

?Overall you feel this instructor:
%Paid close attention to detail at all times.
%Missed a few details, but on the whole got it right most of the time.
%Was generally disorganized all the time.

Answer Menus

For longer lists of answers, a popup menu is more appropriate. For example:

Answer menus work well with the demographic question type (see above) but you can use them for extended scales (eg, the numbers 1 to 20). A popup menu is specified with '|' characters to delimit the answer choices:

?Select your favorite color:
|Red|Green|Blue|Yellow|Pink|Black|Purple|Brown|Lavender

Menu items may contain hundreds of choices. You can break up the list over several lines as long as each line begins with a '|' character and there are no blank lines in between.

Text Input

At times you will require typed input rather than scales or menus. Use the line, text, and essay keywords in place of a scale:

?Type in your comments:
text

The only difference between these three is the size of the text input area: 'line' gives a single line where carriage returns are not possible, 'text' gives a small scrolling area, and 'essay' a large scrolling area. The input text is handled in the same way in each case.

Text Formatting

A limited number of HTML formatting tags are supported (see table). Other HTML tags are ignored.

Special Characters

ETX files may contain character "entities" of the form &something; where "something" is the name or number of a special character. For example, the sequence &copy; becomes the copyright symbol ©. HTML reserves the characters '<', '>', and '&' and they will be transformed into the entities '&lt;', '&gt;', and '&amp;' unless they appear as part of a supported tag or special character definition.

Images

It is possible to include images as part of the question stem using special markup ({=...=}):

?{=picture.jpg=}Question with a picture.

The image files must be available in an "images/" directory at the same level as the form. EvalCGI is limited to one image per question at this time. (In contrast, XAM supports unlimited images per question.)

Comments

Any line preceded by double slashes (//) is a comment and will be ignored:

//This is a comment.

Other Elements

There are additional formatting options for headings (#) and horizontal rules (---):

#Section Heading
----------------

Finally, lines that do not begin with the special characters outlined above will pass through unaltered. This is useful when you wish to provide instructions or explanations on your form.

Version 5.0 :: February 28, 2004 :: http://evalsuite.medinfo.ufl.edu/docs/evalcgi/forms.html