As_Items

Overview

The As_Item and Section catalogues are central parts of the assessment system. These repositories support reuse of Assessment components by storing of the various as_items (or questions if you like) and groups of as_items (e.g. Sections) that can be used in an assessment. You are able to add/edit/delete an as_item of a certain type to a certain scope. Furthermore it allows you to search and browse for questions for inclusion in your assessment as well as import and export multiple questions using various formats.

In this description here we will only discuss the design implications for as_items. Green colored tables have to be internationlized.

Each as_item consists of a specific as_item Type like "Multiple Choice Question" or "Free Text". Each as_item Type adds additional Attributes to the as_item, thereby making it pretty flexible. Additionally each as_item has a related display type storing information on how to display this as_item. This way we can create an adp-snippet which we can include to display a certain as_item (the snippet is stored de-normalized in the as_items table and update on every change to the as_item or the as_item_type).

How is this achieved concretely? Each as_item Type has it's own table with attributes useful for this as_item type. All tables (as_items, as_item_type_*, as_item_display_*) are controlled by the content repository. Each as_item is linked using acs-relationships to the specific items of the as_item_type_* and as_item_display_* tables. Each as_item can only be linked to one as_item_type instance and one as_item_display instance.

Categorization and internationalization will make it into OpenACS 5.2, therefore we are not dealing with it in Assessment separately but use the (to be) built in functionality of OpenACS 5.2

Additionally we have support functionality for an as_item. This includes the help functionality. To give Assessment authors flexibility in adapting as_item defaults, help messages, etc for use in different Assessments, we abstract out a number of attributes from as_items into mapping tables where "override" values for these attributes can optionally be set by authors. If they choose not to set overrides, then the values originally created in the as_item supersede.

Separately we will deal with Checks on as_items. These will allow us to make checks on the input (is the value given by the user actually a valid value??), branches (if we display this as_item, which responses have to have been given) and post-input checks (how many points does this answer give).

Here is the graphical schema for the as_item-related subsystems, including the as_item Display subsystem described here.

Data modell graphic

Core Function: as_items

as_items are the "questions" that constitute the atomic focus of the Assessment package. Each as_item is of a certain type, that can give the as_item additional attributes, making it really flexible. The following attributes are common to all as_item types.
- as_item_id
- cr::name - some phrase used in admin UIs
- cr::title - the primary "label" attached to an as_item's display
- cr::description - some descriptive text
- subtext - a secondary label, needed for many kinds of questions
- field_code - a short label for use in data output header rows, etc
- required_p - whether as_item must be answered (default value, can be overridden)
- data_type - This is the expected data_type of the answer. Previously "abstract_data_type" but omitting the superfluous "abstract" term; selected from the data types supported in the RDBMS:
  1. integer
  2. numeric
  3. exponential - stored in the db as a varchar; of form 9.999e99
  4. varchar
  5. text
  6. date
  7. boolean (char(1) 't' 'f' in Oracle)
  8. timestamp (should work for all coarser granularities like date etc)
  9. content_type -- a derived type: something in the CR (instead of a blob type since we use the CR for such things now)
- max_time_to_complete - optional max number of seconds to perform as_item
- adp_chunk - a denormalization to cache the generated "widget" for the as_item (NB: when any change is made to an as_item_choice related to an as_item, this will have to be updated!)
Permissions / Scope: as_items need a clearly defined scope, in which they can be reused. Instead of defining a special scope variable we will use the acs permission system to grant access rights to an as_item.
- Read: An assessment author (who is granted this permission) can reuse this as_item in one of his sections. (NB: Usually the original author has admin privileges.). This is a finer granulation than the previous "enabled_p" as it allows specific access to an item.
- Write: Author can reuse and change this as_item.
- Admin: Author can reuse, change and give permission on this as_item

As_item Types

as_item Types (as_item_type_*) define types of as_items like "Open Question", "Calculation" and others. The as_item type will also define in what format the answer should be stored. For each as_item type a cr_as_item_type will be generated. Each object of this type is linked to the primary object of the as_item (see above) using relationships. This has the benefit that we split the core attributes of an as_item from the type specific ones and the display ones (see down below). Using cr_as_item_type usage allows us to create and reuse standard as_items (e.g. for the likert scale), by linking different questions with the answer possibilities (and the same attributes) to one as_item_type object. If we have objects that are linked this way, we can generate the matrix for them easily. A functional list of all as_item types and their attributes can be found in the requirements section.

Open Question (as_item_type_oq):

as_item_type_id
cr::name - Identifier
default_value: The content of this field will be prefilled in the response of the user taking the survey
feedback_text: The person correcting the answers will see the contents of this box as correct answer for comparison with the user response.

Short Answer (as_item_type_sa):

as_item_type_id
cr::name - Identifier
increasing_p: Increasing will give (number of correct matches / number of total matches) *100% points. All or nothing will either give 100%, if all correct answers are given, or 0% else.
allow_negative_p: This will allow a negative percentage as well (as the total result).

Short Answer Answers (as_item_sa_answers):

answer_id
cr::name - Identifier
cr::title - Answer string that will be matched against the response
data_type - Integer vs. real number vs. text
case_sensitive_p - Shall the match be case sensitive
percent_score - Percentage a correct match gives
compare_by - How is the comparison done (equal, contains, regexp)
regexp_text: If the compare_by is a "regexp", this field contains the actual regexp.
allowed_answerbox_list - list with all answerbox ids (1 2 3 ... n) whose response will be tried to match against this answer. An empty field indicates the answer will be tried to match against all answers
NOTE: These answers are reusable, that's why we have a relationship.

Multiple Choice Item (as_item_type_mc)

cr::name - Identifier
increasing_p: Increasing will give (number of correct matches / number of total matches) *100% points. All or nothing will either give 100%, if all correct answers are given, or 0% else.
allow_negative_p: This will allow a negative percentage as well (as the total result).
num_correct_answers: How many correct options have to be displayed. Check if enough correct choices have been defined.
num_answers: How many options shall be displayed in total (correct and incorrect). Check if enough choices are available.

Multiple Choices (as_item_choices) contain additional information for all multiple choice as_item_types. Obvious examples are radiobutton and checkbox as_items, but pop-up_date, typed_date and image_map as_items also are constructed via as_item Choices. Each choice is a child to an as_item_type Object. Note the difference. A choice does not belong to an as_item, but to the instance of the as_item_type! This way we can reuse multiple choice answers easier. It is debatable if we should allow n:m relationships between choices and as_item_types (thereby allowing the same choice been reused). In my opinion this is not necessary, therefore we relate this using the parent_id (which will be treated as a relationship in cr_child_rels by the content repository internally). Following the Lars Skinny Table approach of conflating all the different potential data types into one table, we provide columns to hold values of the different types and another field to determine which of them is used. as_item Choices have these attributes:
- choice_id
- cr::parent_id (belonging to an as_item_type_mc object).
- cr::name - Identifier
- cr::title - what is displayed in the choice's "label"
- data_type - which of the value columns has the information this Choice conveys
- numeric_value - we can stuff both integers and real numbers here
- text_value
- boolean_value
- timestamp_value
- content_value - references an as_item in the CR -- for an image, audio file, or video file
- feedback_text - where optionally some preset feedback can be specified by the author
- selected_p - Is this choice selected by default (when the item is presented to the user)
- correct_answer_p - Is this choice the correct answer
- sort_order - In which order shall this choice appear with regards to the MC item. Note, this can be overridden by the display type.
- percent_score - Score given to the user if this choice is selected (in percent).
NB: In earlier versions (surveys/questionnaire), each Choice definition carried with it any range-checking or text-filtering criteria; these are now abstracted to the as_item-Checks and Inter-as_item Checks.
Image Map Multiple Choice Item (as_item_type_im):

cr::name - Identifier
cr::title - Title of the image map.
increasing_p: Increasing will give (number of correct matches / number of total matches) *100% points. All or nothing will either give 100%, if all correct answers are given, or 0% else.
allow_negative_p: This will allow a negative percentage as well (as the total result).
image_item_id - cr_revision_id of the image, references cr_revisions

Image Map Choices (as_item_image_choices):

choice_id
cr::parent_id (belonging to an as_item_type_im object).
cr::name - Identifier
cr::title - what is displayed in the choice's "label"
data_type - which of the value columns has the information this Choice conveys
numeric_value - we can stuff both integers and real numbers here
text_value
boolean_value
content_value - references an as_item in the CR -- for an image, audio file, or video file
feedback_text - where optionally some preset feedback can be specified by the author
selected_p - Is this choice selected by default (when the item is presented to the user)
correct_answer_p
percent_score
area_type - Type of the area that uses the coordinates_string
coordinates_string - String that defines the html area coordinates if this choice is used in an image_map question.

Item Display Types

Each item has an item_display_type object associated with it, that defines how to display the item. Each item_display_type has a couple of attributes, that can be passed to the formbuilder for the creation of the widget. Each widget has at least one item_display_type associated with it. In the long run I think this system has the potential to become a part of OpenACS itself (storing additional display information for each acs_object), but we are not there yet :). Obviously we are talking cr_item_types here as well.

Each item_display_type has a couple of attributes in common.

item_display_id
cr::name - name like "Select box, aligned right", stored in the name field of CR.
html_display_options - field to specify other stuff like textarea dimensions ("rows=10 cols=50" eg)

Depending on the presentation_types additional attributes (presentation_type attributes) come into play (are added as attributes to the CR item type) (mark: this is not feature complete. It really is up to the coder to decide what attributes each widget should have, down here are only *suggestions*). Additionally we're not mentioning all HTML possibilities associated with each type (e.g. a textarea has width and height..) as these can be parsed in via the html_display_options.

textbox (as_item_display_tb) - single-line typed entry
- abs_size - An abstraction of the real size value in "small","medium","large". Up to the developer how this translates.
- item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:
  
  beside_left - the "answers" are left of the "question"
  
  beside_right - the "answers" are right of the "question"
  
  below - the "answers" are below the "question"
  
  above - the "answers" are above the "question"
short_answer (as_item_display_sa) - Multiple textboxes in one item.

abs_size - An abstraction of the real size value in "small","medium","large". Up to the developer how this translates.
box_orientation - the pattern by which 2..n answer boxes are laid out when displayed. Note that this isn't a purely stylistic issue better left to the .adp templates or css; the patterns have semantic implications that the Assessment author appropriately should control here.
1. horizontal - all answerboxes are in one continuous line.
2. vertical - all answerboxes are in one column

text area (as_item_display_ta) - multiple-line typed entry
- abs_size - An abstraction of the real size value in "small","medium","large". Up to the developer how this translates.
- acs_widget - the type of "widget" displayed when the Item is output in html. There are many types we should support beyond the stock html types. We are talking ACS Templating widgets here.
- item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:
  1. beside_left - the "answers" are left of the "question"
  2. beside_right - the "answers" are right of the "question"
  3. below - the "answers" are below the "question"
  4. above - the "answers" are above the "question"
radiobutton (as_item_display_rb) - single-choice multiple-option
- choice_orientation - the pattern by which 2..n Item Choices are laid out when displayed. Note that this isn't a purely stylistic issue better left to the .adp templates or css; the patterns have semantic implications that the Assessment author appropriately should control here. Note also that Items with no Choices (eg a simple textbox Item) has no choice_orientation, but handles the location of that textbox relative to the Item label by the item_alignment option (discussed below).
  1. horizontal - all Choices are in one line
  2. vertical - all Choices are in one column
- choice_label_orientation - how shall the label be positioned in relation to the choice (top, left, right, buttom).
- sort_order_type: Numerical, alphabetic, randomized or by order of entry (sort_order field).
- item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:
  
  beside_left - the "answers" are left of the "question"
  
  beside_right - the "answers" are right of the "question"
  
  below - the "answers" are below the "question"
  
  above - the "answers" are above the "question"
checkbox (as_item_display_cb) - multiple-choice multiple-option
- choice_orientation (see above)
- choice_label_orientation
- allow_multiple_p - Is it allow one to select multiple values ?
- sort_order_type: Numerical, alphabetic, randomized or by order of entry (sort_order field).
- item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:
  
  beside_left - the "answers" are left of the "question"
  
  beside_right - the "answers" are right of the "question"
  
  below - the "answers" are below the "question"
  
  above - the "answers" are above the "question"
select (as_item_display_sb) - multiple-option displayed in "popup menu" (select box)

sort_order_type: Numerical, alphabetic, randomized or by order of entry (sort_order field).
allow_multiple_p - Is it allow one to select multiple values ?
item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:

beside_left - the "answers" are left of the "question"

beside_right - the "answers" are right of the "question"

below - the "answers" are below the "question"

above - the "answers" are above the "question"

image map (as_item_display_im) - Title with picture

allow_multiple_p - Is it allow one to select multiple values ?
item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:

beside_left - the "answers" are left of the "question"

beside_right - the "answers" are right of the "question"

below - the "answers" are below the "question"

above - the "answers" are above the "question"

multiple-choice-other (as_item_display_mco): Consider, for instance, a combo box that consists of a radiobutton plus a textbox -- used for instance when you need a check "other" and then fill in what that "other" datum is. In effect this is a single Item but it has two different forms: a radiobutton and a textbox. The answer will NOT be stored in the answer choice table. There is no item_type "multiple-choice-other".
- widget_choice - Type of the widget for the multiple choice part
- sort_order_type: Numerical, alphabetic, randomized or by order of entry (sort_order field).
- other_size: size of the other text field.
- other_label: label (instead of "other").
- item_answer_alignment - the orientation between the "question part" of the Item (the title/subtext) and the "answer part" -- the native Item widget (eg the textbox) or the 1..n choices. Alternatives accommodate L->R and R->L alphabets (or is this handled automagically be Internationalization?) and include:
  
  beside_left - the "answers" are left of the "question"
  
  beside_right - the "answers" are right of the "question"
  
  below - the "answers" are below the "question"
  
  above - the "answers" are above the "question"
pop-up_date - a widget with month-day-year select elements that resets the day element based on year and month (ie include Feb 29 during leap years -- via Javascript) and tests for valid dates

typed_date - similar to pop-up_date but month-day-year elements are textboxes for all-keyboard entry; needs no resetting scripts but does need date validity check

file_upload - present a File box (browse button, file_name textbox, and submit button together) so user can upload a file

Help System

The help system should allow a small "?" appear next to an object's title that has a help text identified with it. Help texts are to be displayed in the nice bar that Lars created for OpenACS in the header. Each object can have multiple help texts associated with it (which will be displayed in sort order with each hit to the "?".) and we can reuse the help text, making this an n:m relationship (using cr_rels). E.g. you might want to have a default help text for certain cr_as_item_types, that's why I was thinking about reuse...

Relationship attributes:

as_item_id
message_id - references as_messages
sort_order (in which order do the messages appear)

Messages (as_messages) abstracts out help messages (and other types of messages) for use in this package. Attributes include:

message_id
message