Index: openacs-4/packages/assessment/www/doc/as_items.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/as_items.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/assessment/www/doc/as_items.adp 9 Jun 2016 13:03:12 -0000 1.1.2.4
+++ openacs-4/packages/assessment/www/doc/as_items.adp 4 Jul 2016 11:33:12 -0000 1.1.2.5
@@ -16,17 +16,18 @@
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).
+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 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
@@ -43,9 +44,9 @@
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.
+"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
@@ -61,78 +62,80 @@
-
-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_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
+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:
+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
+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!)
+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
+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
+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
+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
+
- 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
+
Short
+Answer
(as_item_type_sa):
- as_item_type_id
- cr::name - Identifier
- increasing_p: Increasing will give (number of correct
@@ -143,25 +146,25 @@
-- Short Answer
-Answers
+
- 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 ...
+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
+answers
- NOTE: These answers are reusable, that's why we have a
relationship.
-- Multiple Choice
-Item
+
- Multiple
+Choice Item
(as_item_type_mc)
- cr::name - Identifier
@@ -178,25 +181,28 @@
-
-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:
+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
+
- 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
@@ -235,7 +241,8 @@
(as_item_image_choices):
-
@@ -390,58 +407,61 @@
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"
+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
+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"
+- 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".
+-- 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
+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"
+- 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"
@@ -453,25 +473,26 @@
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...
+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:
+Messages (as_messages)
+abstracts out help messages (and other types of messages) for use
+in this package. Attributes include: