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 assesment 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 seperately 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 supercede.
Seperately 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.
+
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 overriden)
-
+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:
-
+
- integer
- numeric
- exponential - stored in the db as a +varchar; of form 9.999e99
- varchar
- text
- date
- boolean (char(1) 't' 'f' in +Oracle)
- timestamp (should work for all coarser +granularities like date etc)
- 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 priviledges.). +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. +
- as_item_type_id
- 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). +
+- as_item_type_id
-
+
- 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.
+
+
+- answer_id
-
+
- 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. +
+- cr::name - Identifier
-
+
-
+
+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 overriden 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
+additonal 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 heigth..) 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.
+
-
+
- horizontal - all answerboxes are in one continuous
+line.
+ - vertical - all answerboxes are in one column +
+
+ - horizontal - all answerboxes are in one continuous
+line.
- 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:
+
-
+
- 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" +
+
+
- 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).
+
-
+
- horizontal - all Choices are in one line
- 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" +
+
+
- 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).
+
- checkbox (as_item_display_cb) - multiple-choice multiple-option
+
-
+
- choice_orientation (see above)
- choice_label_orientation
+ - allow_multiple_p - Is it allow 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 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 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" +
+
+
-
+allow_multiple_p - Is
+it allow to select multiple values ?
- 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 +