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.
+
+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.
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.
+Each item_display_type has a couple of +attributes in common.
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.
+
Relationship attributes:
+Messages (as_messages) abstracts +out help messages (and other types of messages) for use in this +package. Attributes include:
What to do to add new item types or item +display types:
At its core, the Assessment package defines a hierarchical +container model of a "survey", "questionnaire" or "form". This +approach not only follows the precedent of existing work; it also +makes excellent sense and no one has come up with a better +idea.
We choose the terms Assessment-Sections-Items-Choices over +Surveys-Sectdions-Questions-Choices partly to reduce naming clashes +during the transition from Survey/Questionnaire packages, but +mostly because these terms are more general and thus suit the +broader applicability intended for this package.
As is the custom in the OpenACS framework, all RDBMS tables in +the package will be prepended with "as_" to prevent further prefent +naming clashes. Judicious use of namespaces will also be made in +keeping with current OpenACS best practice.
Several of the Metadata entities have direct counterparts in the +Data-related partition of the data model. Some standards (notably +CDISC) rigorously name all metadata entities with a "_def" suffix +and all data entities with a "_data" suffix -- thus "as_item_def" +and "as_item_data" tables in our case. We think this is overkill +since there are far more metadata entities than data entities and +in only a few cases do distinctions between the two become +important. In those cases, we will add the "_data" suffix to data +entities to make this difference clear.
A final general point (that we revisit for specific entities +below): the Assessment package data model exercises the Content +Repository (CR) in the OpenACS framework heavily. In fact, this use +of the CR for most important entities represents one of the main +advances of this package compared to the earlier versions. The +decision to use the CR is partly driven by the universal need for +versioning and reuse within the functional requirements, and partly +by the fact that the CR has become "the Right Way" to build OpenACS +systems. Note that one implication of this is that we can't use a +couple column names in our derived tables because of naming clashes +with columns in cr_items and cr_revisions: title and description. +Furthermore we can handle versioning +and internationalization through the CR.
Here's a detailed summary view of the entities in the Assessment +package. Note that in addition to the partitioning of the entities +between Metadata Elements and Collected Data Elements, we identify +the various subsystems in the package that perform basic +functions.
+We discuss the following stuff in detail through the subsequent +pages, and we use a sort of "bird's eye view" of this global +graphic to keep the schema for each subsystem in perspective while +homing in on the relevent detail. Here's a brief introduction to +each of these sectionThe schema for the entities that actually collect, store and +retrieve Assesment data parallels the hierarchical structure of the +Metadata Data Model. In the +antecedent "complex survey" and "questionnaire" systems, this +schema was simple two-level structure:
This suffices for one-shot surveys but doesn't support the fine +granularity of user-action tracking, "save&resume" +capabilities, and other requirements identified for the enhanced +Assessment package. Consequently, we use a more extended +hierarchy:
To support user modification of submitted data (of which +"store&resume" is a special case), we base all these entities +in the CR. In fact, we use both cr_items and cr_revisions in our +schema, since for any given user's Assessment submission, there +indeed is a "final" or "live" version. In contrast, recall that for +any Assessment itself, different authors may be using different +versions of the Assessment. While this situation may be unusual, +the fact that it must be supported means that the semantics of +cr_items don't fit the Assessment itself. They do fit the +semantics of a given user's Assessment "session" however.
We distinguish here between "subjects" which are users whose +information is the primary source of the Assessment's responses, +and "users" which are real OpenACS users who can log into the +system. Subjects may be completing the Assessment themselves or may +have completed some paper form that is being transcribed by staff +people who are users. We thus account for both the "real" and one +or more "proxy" respondents via this mechanism. Note that subjects +may or may not be OpenACS users who can log into the system running +Assessment. Thus subject_id will be a foreign key to +persons not users. If the responding user is +completing the assessment for herself, the staff_id will be +identical to the subject_id. But if the user completing the +assessment is doing it by proxy for the "real" subject, then the +staff_id will be hers while the subject_id will belong to the +"real" subject.
We've simplified this subsection of Assessment considerably from +earlier versions, and here is how and why:
Because of this variability as well as the recognition that +Assessment should be primarily a data collection package, +we've decided to abstract all scoring-grading functions to one or +more additional packages. A grading package (evaluation) +is under development now by part of our group, but no documentation +is yet available about it. How such client packages will +interface with Assessment has not yet been worked out, but this is +a crucial issue to work through. Presumably something to do with +service contracts. Such a package will need to interact both +with Assessment metadata (to define what items are to be "scored" +and how they are to be scored -- and with Assessment collected data +(to do the actual calculations and mappings-to-grades.
+We previously used a separate table for this since probably most +assessments won't use this (at least, that is the opinion of most +of the educational folks here). However, since we're generating +separate revisions of each of these collected data types, we +decided it would be far simpler and more appropriate to include the +signed_data field directly in the as_item_data table. Note +that for complex applications, the need to "sign the entire form" +or "sign the section" could be performed by concatenating all the +items contained by the section or assessment and storing that in a +"signed_data" field in as_section_data or as_sessions. However, +this would presumably result in duplicate hashing of the data -- +once for the individual items and then collectively. Instead, we'll +only "sign" the data at the atomic, as_item level, and procedurally +sign all as_item_data at once if the assessment author requires +only a section-level or assessment-level signature.
+Here's the schema for this subsystem:
+
This section addresses the attributes the most important +entities have in the data-collection data model -- principally the +various design issues and choices we've made. We omit here literal +SQL snippets since that's what the web interface to CVS is for. +;-)
Note: please refer to the discussion +of Items here. That discussion +complements the discussion here, and the data model graphic +pertaining to the Item Display Types system is available there +also.
Each item_display_type has a couple of +attributes in common.
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..).
In addition, there are some potential presentation_types that +actually seem to be better modeled as a Section of separate +Items:
Here is a graphical overview of the subsystem in the Assessment
+package that organizes Items into Sections and whole
+Assessments:
+
The primary key assessment_id is a revision_id inherited from +cr_revisions. Note, the CR provides two main types of entities -- +cr_items and cr_revisions. The latter are where sequential versions +of the former go, while cr_items is where the "current" version of +an entity can be stored, where unchanging elements of an entity are +kept, or where data can be cached. This is particularly useful if +the system needs a single "live" version, but it isn't appropriate +in situations where all versions potentially are equally-important +siblings. In the case of the Assessment package, it seems likely +that in some applications, users would indeed want to designate a +single "live" version, while in many others, they +wouldn't.
Attributes of Assessments will include those previously included +in Surveys plus some others:
Permissions / Scope: Control of reuse previously was through a +shareable_p boolean. As with Items and Sections, we instead will +use the acs permission system:
Permissions / Scope: Control of reuse previously was through a +shareable_p boolean. As with Items and Assessments, we instead will +use the acs permission system:
This entity is directly analogous in purpose and design to +as_item_display_types.
The Assessment Package unites the work and needs of various +members of the OpenACS community for data collection functionality +within the OpenACS framework. We're using the term "Assessment" +instead of "Survey" or "Questionnaire" (or "Case Report Form" aka +CRF, the term used in clinical trials) because it is a term used by +IMS and because it connotes the more generic nature of the data +collection system we're focusing on.
There has been considerable recent interest in expanding the +capabilities of generic data collection packages within OpenACS. +Identified applications include:
Of note, there are large and well-funded vendors of clinical +trials data management systems. Phase Forward, +Outcome Sciences, and PHT Corporation among +others. A standards body called CDISC (Clinical Data +Interchange Standards Consortium) formed a few years ago and is +developing data models for clinical trials data derived from schema +contributed primarily by Phase Forward and PHT. These vendors +provide "electronic data capture" (EDC) services at considerable +cost -- a 18 month study of 2500 patients including about 500 data +elements costs nearly $500,000. There is clearly interest and +opportunity to craft systems that bring such costs "in house" for +organizations doing clinical research.
+Data collection services for other OpenACS packages. Most other +OpenACS packages invoke some form of data collection from users. +While developments such as ad_form and the templating system in +OpenACS 4.x ease the construction of data collection forms, it may +be possible to expose a focused data collection package via +acs_service_contract mechanisms to other packages. In particular, +incorporating Workflow and a new data collection package would be +key to creation of new vertical-application tools like dotWRK. Such +integration would also be immensely useful for a clinical trials +management toolkit.
Several OpenACS efforts form the context for any future work. +These include:
However, Surveys has some important limitations:
Still, this package adopts some naming conventions consistent +with the IMS spec and definitely represents the closest effort to a +"complex survey" done to date.
+Open questions are text input questions for free text. For +obvious reasons they cannot be auto corrected. The difference +between an "Open Question" and a "Short Answer" Item is that Open +Questions accept alphanumeric data from a user and only undergo +manual "grading" by an admin user through comparison with "correct" +values configured during Assessment authoring. Open Questions can +either be short (textbox) or long (text area) elements in the html +form. Here are several configuration options the authoring +environment will support (in addition to many others, such as +alignment/orientation, required/not required, etc etc):
Short Answer Items allow the user to give a short answer to an +answer box, which could be automatically corrected. The questioneer +can define what values are valid in each answer box and use various +compare functions to compare the output. The creation of a short +answer question will trigger entries into the as_item check tables. +In addition to supporting automated validation/grading, this item +type differs from "Open Questions" in that only textboxes are +supported -- meaning short answers, no text area essays.
Matching questions are useful for matching some items on the +left with pull down menues on the right hand side of a survey. The +number of the items is identical to the number of items on the +right hand side. This also appears to be a Section of Items; each +Item consists of a single "phrase" against which it is to be +associated with one of a set of potential choices (displayed via a +select widget; could be radiobutton though too). If there are +several such matchings (three phrases <-> three items in the +popup select) then this is a Section with three Items. The UI for +this needs to be in section-edit, not item-edit.
A file upload question will allow the respondent to upload a +file. No additional attributes but the usual for every +question.
+Multiple Choice questions allow the respondee to choose from +multiple alternatives with the possibility to answer more than one +at a time. This will also deal with True/False and Multiple +response items.
Rank questions ask for the answers to be ranked. This appears to +me to be a special case of the "matching question" in which the +select options are ordinal values, not arbitrary strings.
The idea here is a "question" consisting of a group of +questions. We include it here because to many users, this does +appear to be a "single" question.
However, it is actually more appropriately recognized to be a +"section" because it is a group of questions, a response to each of +which will need to be separately stored by the system. Further, +this is in fact a display option for the section that could +reasonably be used for any Item Type. For instance, there are +situations where an Assessment author may want to group a set of +selects, or radiobuttons, or small textboxes, etc.
+Same as the matrix table, but you have different choices that +are displayed in each column.
+Multiple Choice question with an additional short_text input +field. Usually used for the "Other" thing
+This type of question will not be supported. But we should make +sure we can take care of that type while importing the data from +WebCT. Therefore we have to know the values. At a later stage, we +will add more info on this.
The answer to this question will be stored in the database. The +concept here is to support bidirectional interchange of data +between Assessment package tables and other package tables. Thus, +while assembling an Assessment to send to a user, data may be +pulled from some other table (eg users) to populate the Assessment +form. And similarly, when the user submits the Assessment form, +response data will be stored not only in Assessment entities +(as_item_data eg) but also back in the other table (eg users). The +question has the following additional fields:
Through the OpenACS templating system, the UI look&feel will +be modifiable by specific sites, so we needn't address page layout +and graphical design issues here. Other than to mention that the +Assessment package will use these OpenACS standards:
Furthermore, the set of necessary pages for Assessment are not +all that dissimilar to the set required by any other OpenACS +package. We need to be able to create, edit and delete all the +constituent entities in the Package. The boundary between the pages +belonging specifically to Assessment and those belonging to +"calling" packages (eg dotLRN, clinical trials packages, financial +management packages, etc etc) will necessarily be somewhat +blurred.
Nevertheless, here is a proposed set of pages along with very +brief descriptions of what happens in each. This organization is +actually derived mostly from the existing Questionnaire module +which can be examined here +in the "Bay Area OpenACS Users Group (add yourself to the group and +have a look).
The UI for Assessment divides into a number of primary +functional areas, as diagrammed below. These include:
The current Survey package is a very capable piece of +engineering that provides stand-alone data collection functions. It +is subsite-aware and has been integrated to some extent with +portlets. It also is just being integrated into user registration +processes. These efforts point the path down which the Assessment +package intends to proceed to its logical conclusion.
Development efforts for Assessment thus involve two tracks:
The measure of success of the Assessment package is the ease +with which it can rapidly be deployed into some high-profile +implementations, notably dotLRN and a clinical trials management +system under development.
It is very important to note, that not all parameters and +features mentioned in this use case should be displayed to the user +at all times. Depending on the use case, a good guess with pre +determined parameters should be made for the user (e.g. no need to +let the user fill out correct answers to questions, if the question +is not used in a test). Some use cases like elections require +special parameters not necessary anywhere else (like counting +system).
It should also be able to show the results of a survey to a +group of users (e.g. a specific department evaluated). The results +should be able to be displayed in a way that give a department a +ranking compared with other departments.
[A Question improves the test in reliability if it +differentiates in the context of the test. This is happening if it +has discriminatory power. The Question has discriminatory power if +it is splitting good from bad students within the question in the +same way they passes the test as good and bad students. The +discriminatory power tells the professor if the question matches +the test. Example: A hard question with a high mean value should be +answered by good students more often right than by bad students. If +the questions is answered same often by good and bad students the +discriminatory power tells the professor that the question is more +to guess than to know]
There are several types of administrative users and end-users +for the Assessment package which drive the functional requirements. +Here is a brief synopsis of their responsibilities in this +package.
Has permissions to create, edit, delete and organize in +repositories Assessments, Sections and Items. This includes +defining Item formats, configuring data validation and data +integrity checks, configuring scoring mechanisms, defining +sequencing/navigation parameters, etc.
Editors could thus be teachers in schools, principal +investigators or biostatisticians in clinical trials, creative +designers in advertising firms -- or OpenACS developers +incorporating a bit of data collection machinery into another +package.
Has permissions to assign, schedule or otherwise map a given +Assessment or set of Assessments to a specific set of subjects, +students or other data entry personnel. These actions potentially +will involve interfacing with other Workflow management tools (e.g. +an "Enrollment" package that would handle creation of new Parties +(aka clinical trial subjects) in the database.
Schedulers could also be teachers, curriculum designers, site +coordinators in clinical trials, etc.
Has permissions to search, sort, review and download data +collected via Assessments.
Analysts could be teachers, principals, principal investigators, +biostatisticians, auditors, etc.
Has permissions to complete an Assessment providing her own +responses or information. This would be a Student, for instance, +completing a test in an educational setting, or a Patient +completing a health-related quality-of-life instrument to track her +health status. Subjects need appropriate UIs depending on Item +formats and technological prowess of the Subject -- kiosk +"one-question-at-a-time" formats, for example. May or may not get +immediate feedback about data submitted.
Subjects could be students, consumers, or patients.
Has permissions to create, edit and delete data for or about the +"real" Subject. Needs UIs to speed the actions of this trained +individual and support "save and resume" operations. Data entry +procedures used by Staff must capture the identity if both the +"real" subject and the Staff person entering the data -- for audit +trails and other data security and authentication functions. Data +entry staff need robust data validation and integrity checks with +optional, immediate data verification steps and electronic +signatures at final submission. (Many of the tight-sphinctered +requirements for FDA submissions center around mechanisms +encountered here: to prove exactly who created any datum, when, +whether it is a correct value, whether anyone has looked at it or +edited it and when, etc etc...)
Staff could be site coordinators in clinical trials, insurance +adjustors, accountants, tax preparation staff, etc.
Note also: need to support three-value logic regarding the +existence of any single Item datum: null value means the Item +hasn't been dealt with by responder; "unknown" value means that the +Item has been answered but the responder doesn't know value; actual +value (of proper type) means that the responder has found and +submitted a value.
+Note that there are at least three semantically distinct +concepts of scoring, each of which the Assessment package should +support and have varying levels of importance in different +contexts. Consider:
Along with Data Validation and Versioning, probably the most +vexing problem confronting the Assessment package is how to handle +conditional navigation through an Assessment guided by user input. +Simple branching has already been accomplished in the "complex +survey" package via hinge points defined by responses to single +items. But what if branching/skipping needs to depend on +combinations of user responses to multiple items? And how does this +relate to management of data validation steps? If +branching/skipping depends not merely on what combination of +"correct" or "in range" data the user submits, but also on +combinations of "incorrect" or "out of range" data, how the heck do +we do this?
One basic conceptual question is whether Data Validation is a +distinct process from Navigation Control or not. Initially we +thought it was and that there should be a datamodel and set of +procedures for checking user input, the output of which would pipe +to a separate navigation datamodel and set of procedures for +determining the user's next action. This separation is made (along +with quite a few other distinctions/complexities) in the IMS +"simple sequencing" model diagrammed below). But to jump the gun a +bit, we think that actually it makes sense to combine these two +processes into a common "post-submission user input processing" +step we'll refer to here as Sequencing. (Note: we reviewed several +alternatives in the archived prior discussions +here.
+So here is our current approach. We note that there are two scopes +over which Sequencing needs to be handled: +So how might we implement this in our datamodel? Consider the
+"sequencing" subsystem of the Assessment package:
+
The goal is to have a flexible, expressive grammar for these
+checks to support arbitrary types of checks, which will be input
+validation ("Is the user's number within bounds?"; "Is that a
+properly formatted phone number?"). One notion on check_sql.
+Instead of using comparators we store the whole SQL command that
+makes up this check with a predefined variable "value" that
+contains the response of the user to the item the item_check is
+related to. If we want to make sure the value is between 0 and 1 we
+store "0 < :value < 1" with the check. Once an item is
+submitted, the system looks up the related checks for this item and
+replaces in each of them ":value" with the actual response.
+
Item Checks thus will have these attributes:
This topic requires special mention because it is centrally +important to Assessment and one of the most radical departures from +the current packages (in which "surveys" or "questionnaires" are +all one-shot affairs that at best can be cloned but not readily +modified in a controlled fashion).
During its lifetime, an Assessment may undergo revisions in the +midst of data collection. These revisions may be minor (change of a +label on an Item or adddition of a new Choice to an Item) or major +(addition or deletion of an entire Section). Obviously in most +applications, such changes are undesirable and people want to avoid +them. But the reality is that such changes are inevitable and so +the Assessment package must accommodate them. Clinical trial +protocols change; teachers alter their exams from term to term. And +still, there is a crucial need to be able to assemble and interpret +data collected across all these changes.
Another type of "revision" occurs when a component (an Item +Choice, Item, Section, or the entire Assessment) needs to be +translated into another language. Even if the semantics of the +component are identical (and they should be or you need a better +translator ;-), the Assessment package needs to handle this +situation correctly: an admin user needs to be able to "assign" the +right language version to a set of subjects, and the returned user +data need to be assembled into trans-language data sets.
Note that two orthogonal constructs are in play here:
The Content Repository (CR) in OpenACS is designed to handle +these complex design issues, though it is still undergoing +refinements and how best to use it is also still being discovered. +So the ideas here are still somewhat exploratory.
For each of the package components that need to be versioned +(certainly the core components as_assessments, as_sections, +as_items, and as_item_choices; but also other components like +as_policies), we extend the basic CR entities cr_items and +cr_revisions. Thus we actually have, for instance, two tables for +Items:
This pattern of dual tables is used for all components that need +to behave this way. When an admin user creates a new Item, a new +row is inserted into the as_items and the as_items_revs table. Then +when the same admin user (or another admin user) changes something +about the Item, a new as_items_revs row is inserted.
Now here is where things become tricky, though.. Any time a +component is changed, there is a simultaneous implicit change to +the entire hierarchy. Data collected after this change will be +collected with a semantically different instrument. Whether the +difference is large or small is immaterial; it is different, and +Assessment must handle this. And the CR doesn't do this for us +automagically.
So what the package must do is version both the individual +entities and also all the relationships over which we join when +we're assembling the entire Assessment (whether to send out to a +requesting user, to stuff the database when the form comes back, or +to pull collected data into a report).
This doesn't involve merely creating triggers to insert new +mapping table rows that point to the new components. We also need +to insert new revisions for all components higher up the hierarchy +than the component we've just revised. Thus:
Another key issue, discussed in this +thread, involves the semantics of versioning. How big of a +modification in some Assessment package entity needs to happen +before that entity is now a "new item" instead of a "new version of +an existing item"? If a typo in a single Item Choice is corrected, +one can reasonably assume that is merely a new version. But if an +Item of multiple choice options is given a new choice, is this Item +now a new one?
One possible way this could be defined would derive from the +hierarchy model in the CR: cr_items -- but not cr_revisions -- can +contain other entities; the parent_id column is only in cr_items. +Thus if we want to add a fifth as_item_choice to an as_item (while +preserving the state of the as_item that only had four +as_item_choices), we need to insert a new as_item and not merely a +new as_item_rev for the existing as_item.
A final point concerns the mapping tables. The OpenACS framework
+provides a variety of special-purpose mapping tables that are all
+proper acs_objects (member_rels, composition_rels, acs_rels, and
+the CR's own cr_rels). These provide additional control over
+permissioning but fundamentally are mapping tables. In the long run
+the benefit of using them is the ability of OpenACS 6, to auto
+construct code based on cr_item_types and relationships.
+
Within each subsystem of the Assessment package, the following +entities will inherit from the CR. We list them here now, and once +we've confirmed this selection, we'll move the information out to +each of the subsystems' pages.
Design: Rocael Hernandez (roc\@viaro.net) and +Vivian Hernandez (vivian\@viaro.net)
Table of Contents
+It was necessary to add several tables to support the trigger +and action execution.
Table of Contents
+Here are some statements to create triggers to branch between +sections or execute actions:
+To create an assessment is necessary to have create permissions +over the assessment instance. This permission can be inherit or can +be granted by a site wide administrator. This permissions can be +managed by the site wide administrator following the Permissions +link in the assessment admin page.
To create triggers is necessary to have admin permissions over +an assessment. The admin permission is inherit to the user that +creates an assessment and also can be granted by the assessment +administrator. This permissions can be managed folloging the +Permission link that appears in the list of assessments.
Both links will lead the user to a page where the necesary +permissions can be set.
Also the user can search for another user to manage his +permissions:
After clicking OK, the user will appear in the list an the +permissions can be set properly.
To be able to administrate actions the user must have site wide +admin privileges. To admin actions the user must follow the link +"Action Administration" in the assessment admin page.
Register User: create a new user account in the system.
Event Registration: register the user to an event.
Add to Community: register the user to dotlrn and also to a +dotlrn class/community.
Actions can be also created, following the link "Add new +action":
The action is formed mainlly by four things:
Name: the desire name that gives an idea of what the action +do.
Description: short explaination of what the action do, and how +its done.
Tcl code: the code that its executed to performe the action.
Parameter: this are the variables needed in the tcl code, that +depends of the user.
After the action is created, a link to add the parameters is +shown.
When the link is followed, then a form to create the parameter +is shown, there are two types of parameters:
Name: this will take the value from a response given by the user +to an item of the assessment.
Query: for this type of parameter, the field query is used, and +the parameter will take the value or values that the query +returns.
To delete an action the link "delete" in the action +administration page must be followed:
Before deleting an action, a confirm message will be displayed, +the action will not be deleted if there is some reference to this +action (i.e. a trigger that wil execute this action).
After the assessment is created, the triggers can be defined for +questions with multiple choice responses.
There are two type of triggers:
Branch: This trigger will make that the secuence of sections in +the assessment change, depending on the answer that a user gives to +the question related to the trigger when the assessment is being +responded.
Action: This trigger will execute the action related, also +depending on the answer that the user gives to the question related +to the trigger, when the assessment is being responded.
The link to create a trigger appears in the action bar of the +items with multiple choice responses of the assessment.
To define a Branch Trigger, the field "Type" in the form must be +checked as branch. Is necessary that at least one section is +created after the one that is being evaluated.
The condition field shows the question and its possible answers, +this means that if a user that respond the assessment choose that +response the trigger will be activated, and the section secuence +will change.
After the trigger is defined as branch, the section that will be +displayed next must be chosen:
To define an Action Trigger, the field "Type" in the form must +be checked as "Action".
The condition field shows the question and its possible anwers, +it means that when the user is responding the assessment, if this +answer is given for this question, the action will be executed.
After the trigger is created, the action related must be chosen, +also the time when the action will be executed, and the message +shown to the user when the action is executed.
The actions can be executed in three different times:
Immediately: it means that the action will be executed after the +user finish to respond the current section.
At the end of this Assessment: it means that the action will be +executed when the user finish to respond all the sections of the +assessment.
Manually:this means that the action will be executed by an +administrator (i.e. in case that the request needs approval).
After select the action related to the trigger, the parameters +for the action must be set, the select boxes display the options +depending on the type of the parameter.
Query: display the values returned by the query defined for the +parameter.
Name: the options displayed depends on the time of +execution:
Immediately: display all the questions defined in previuos +sections.
At the end of the assessment and Manually: display all the +questions defined in the assessment.
The trigger administration page can be reached from two +different links, the link "Administer Triggers" in the action bar +of each section, or from the link that show the number of triggers +related to an item.
If the trigger administration page is reached from thi link of +the section, all the triggers related to the items of the section +will be display, this allowst to manage the order of the execution +of the actions when they are executed immediately or at the end or +the assessment. When the arrorws that appear beside each trigger is +clicked, then the order of execution will change.
If the trigger administration page is reached through the link +that show the number of triggers of each item, then the row will +not be shown. Through this interface, the trigger can be edited, +deleted or can be managed its notifications.
When a trigger is deleted, a confirm message will be display +showing all the information related to it.
The link "Notify User" leads to a page a user can request +notifications when this trigger is executed. It also allowst to +search and register another users to the notifications.
The request Administration page can be reached following the +link in the action bar for a site wide administrator or following +the link show in the list of assessments that belong to a user.
The Request Administration interface shows all the requests +(action triggers executions) that has been approved, approved with +errors and the ones that are waiting to be executed (i.e. Manually +executed triggers).
This interface will display those requests related to the +assessments that the user owns, if the user is site wide +administrator, all the requests related to all the assessments will +be display.
An administrator can select requests that want to approve and +click in the button "Approve", and also can send mail to several +users that requested the action. Through this interface the +notifications can also be managed.
To be able to select an assessment that will be related to the +registration process is necessary that the user has site wide admin +privileges, because the interface can only be reached through the +Main Site Administration Page. This link only will appear if the +Assessment Package is installed and mounted.
If the Assessment Package is installed and mounted, the link can +be follow and will lead to a page that shows all the assessment +that can be responded for anonymous users created in all of the +diferent instances of the assessment package that could exist. If +the option "None" is selected, it means that the registration +process will be the same as always has been, if any other option is +selected, the assessment will be diplayed when a user creates a new +account.
Viaro Networks (www.viaro.net)
Rocael Hernandez -- roc\@viaro.net
Design
+Vivian Aguilar -- vivian\@viaro.net
Desing and Development
+Anny Flores -- annyflores\@viaro.net
Development and Documentation
+Table of Contents
+On the other hand the need for dotLRN has +risen to provide an assessment solutions that allows (automated) +tests as well with the possibility to score the test results and +store them in an easy retrievable way.
Last but not least a new demand has risen +for the possibility to give and store ratings on objects within the +system as part of a knowledge management solution.
The documents on these page will provide a +solution that is flexible to meet ababove needs but still be +focused enought to apply for special clients demands.
Each assessment consists of various +sections, that allow for the split up of the assessment (so it will +be displayed to the respondee on multiple pages) and give the +possibility for branching depending on previous answers of the +respondee. Questions are always added into the question database +first, then added to a specific section and thus made available to +the assessment. A detailed description of the Sections can be found +here.
The backend for the test processing, that +enables the automatic tests is described in a seperate document as it will be parsed while +the respondee answers the test, not manually. In addition this +document describes how the grades are calculated (automatically or +manually) for each question. The result is beeing stored in the +grading package.
In addition to the possiblity to enter +scores/rates, the grading package allows for automatic aggregation +of scores. This holds especially true for tests and classes. A test +result will depend on the result of all the answers (aggregated). A +class result will depend on the result of all the tests a respondee +did in addition to any manual grades the professor can come up +with. Providing a clean UI for this is going to be the +challange.
Furthermore the grading package offers to +transfer scores (which are stored as integer values) into a grade +(e.g. the american A-F scheme, or the German 1-6). This is where it +gets the name from I'd say ;). Grading schemes are flexible and can +be created on the fly. This allows us to support any grading scheme +across the world's universities. In addition in the area of +Knowledge Management, grades could be transfered into incentive +points, that can be reused to reward employees for good work done +(where they got good ratings for).
Last but not least, maybe embeded with the +workflow system, is the possibility to execute actions based on the +grade. An example would be the adding of the student to the +advanced class if his grade or score reaches a certain level. +Alternatively this looks like a good thing for the curriculum +module to achieve.
Additionally you can use the assessment +system to collect user information. When signing up to a site the +user could be asked to fill out an assessment where part of the +questions will be stored in the acs_users table, some other +questions in other tables and the rest in the accessment package. +This way a quick view can be given about the user (aggregating user +information in a flexible way). Best explanation would be to treat +the /pvt/home page as a collection of assessment data and the +"change basic information" as one assessment among many.
With a little bit of tweaking and the +possiblity to add instant gratification, aka aggregated result +display, it could include the poll package and make it +redundant.
Last but not least with the ability to +display questions in a multi dimensional way to the user, the +assessment system is usefull for quality assurance (how important +is this feature / how good do you think we implemented it). And as +you might have guessed, for anything the current survey module has +been used for as well (e.g. plain and simple surveys).
The grading system on it's own would be +usefull for the OpenACS community as it would allow the handing out +of "zorkmints" along with any benefits the collection of mints +gives to the users. As mentioned earlier, this is also very +important in a Knowledge Management environment, where you want to +give rated feedback to users.
+ + + Index: openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/assessment/www/doc/user_interface/item_creation.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 @@ -0,0 +1,303 @@ + ++
+
The question catalogue is a central part +of the assessment system. It deals with the storing of the various +questions that can be used in a survey. You are able to +add/edit/delete a question 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. This concept is new to survey 0.1d +and changes the design of the survey module considerably. No +mockups available.
+Spec:
+All questions have some common ground.
Both levels involve stringing together +multiple binary comparisons (eg 0 < input < 3 means checks +that 0 < input and input < 3), so we need to express a +grammar consisting of
By Database questions, do you mean free text input (via +textboxes or textareas) questions for which there is a "correct" +answer that needs to be stored during question creation? Then when +the teacher is reviewing the student's response, she can inspect +the student's response against the stored answer and determine what +degree of correctness to assign the response?
-- Stan +Kaufman on November 09, 2003 06:29 PM (view +details)
+ Index: openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/assessment/www/doc/user_interface/section_creation.adp 20 Aug 2015 17:39:09 -0000 1.1.2.1 @@ -0,0 +1,111 @@ + +The OpenACS calendar package is a web-based calendar package. In +its current form it provides a UI for storing events that have a +time or that last a day, and it offers a list view, a day, week, +and month view.
The project plan for calendar can be found at http://openacs.org/projects/openacs/packages/calendar/. +The maintainer of this package is Dirk Gomez +
Calendar uses a lot of custom permissions. Most of them are +unused and will be removed eventually. It will then use a Unix-like +set of read, write, create, admin permissions.
A calendar has a name and an owner and belongs to a package, it +also is an acs_object. This goes into the table calendars. A +calendar is created via the usual constructor - a "new" function" - +and destroyed via the usual destructor - a "delete" function.
The calendar package currently uses its own little category +system: calendar item types can be created per package, they are +stored in the table cal_item_types
The table cal_party_prefs allows storing customization +information per calendar and per user. It is completely unused and +I couldn't find any traces of it ever having been used. A similar +table will be used in a future version of calendar to store user +options though.
I am planning to use acs-automated-tests for subsequent releases +of calendar, I am collecting the test +cases in this document.
Calendar objects have been designed to allow them to be tied to +particular ACS parties where each party member can see events +associated with that particular party. Events from the various +parties of which one is a member can also be shown on a party +member's personal calendar.
This package could be used for any application where event +tracking is important. This would include many business, +educational, club, and other community scenarios.
A user's calendar is the aggregate of the party-specific +events which are associated with parties of which the user is a +member and which have been specified by this user as desirable for +calendar inclusion. Users will have the option to suppress the +inclusion of all party-specific events for a particular party of +which they wish to remain a member but the party-specific events of +which they do not wish to have appear on their calendars. Since in +our system, groups are parties and parties can have calendars, this +account of a user's calendar generalizes to cover a party's +calendar.
The Calendar Package is built on top of the ACS Event service +package and performs the following three high-level functions:
+Calendar Views covers those aspects of the application +which pertain to the display of calendar events for a particular +span of time.
+Navigation covers those aspects of the application which +pertain to ways in which the end-user can change the timespan +currently being displayed.
+Groups and Parties can have a collective calendar that +stands apart from the private individual calendar. This would be +useful to display calendar events for the public, for whom there is +no individual calendar. For example, ArsDigita can display a +schedule of upcoming bootcamps, lectures and other approved events +on a calendar on arsdigita.com. A common visitor does not have to +be registered with the site to be able to obtain this event +information through their personal calendar. To allow this +functionality, the calendars for groups and parties would need to +support all the event managment and calendar views had by +individual calendars, and in addition, the role of calendar +administrator must be assigned to handle event managment.
+Administrators for a group and party wide calendar are +given create, read, and write permissions on each individual item +on the calendar. He or she also has the privilege to change the +permissions for each of these items and also individual's ability +to interact with these items. For example, the side-wide +administrator, Joe Admin, who also has the role of the calendar +administrator realizes that the date on which one of the ACS +bootcamps is scheduled to take place this month is incorrect. He +has the permission to change it. He also can grant Jane Bootcamp +write permission on that particular event, so that Jane can make +changes on her own.
10.0 User Interface
+10.0.10 The calendar page should indicate whether or not +private, public or party-specific events are to be displayed.
+10.0.20 The calendar should support navigation to view +different dates in a simple manner.
+10.0.30 Links to different calendar functions should be +clear and obvious.
+10.0.40 Each calendar item should be displayed with its +subject and time span as the basic information.
10.10 Views
+10.10.0 Different views should be easily selectable.
+10.10.0 Different views should also be indicated in a +clear and noticeable location
10.10.10 List View
+10.10.10.10 The calendar should support a view showing +selected items in a tabular list format.
+10.10.10.20 Columns should include date, time, and other +relevant information.
+10.10.10.30 The columns should be sortable.
+10.10.10.40 There should be at least two lists of items. +One list should consist of items whose dates occur within a +user-specified number of days of the currently viewed date. One +list should consist of items that have been added within a +user-specified number of days of the current date.
10.10.20 Day View
+10.10.20.10 The calendar should support a view showing +all the events for a particular day.
+10.10.20.20 This view should show the events arranged +chronologically with a time guide along one side.
+10.10.20.30 The range of the time guide should be +user-specifiable.
+10.10.20.40 The user should have the option of +compressing the time guide so that only those time intervals upon +which fall selected calendar events are shown.
+10.10.20.50 Overlapping events should be displayed in an +easy to understand fashion.
+10.10.20.60 There should be a simple mechanism for adding +events which start at a particular hour.
+10.10.20.70 The day view should support events that don't +have a specified start and end time, and the time guide should +include a slot for these items.
10.10.30 Week View
+10.10.30.10 The calendar should support a view showing +all the events for a particular week.
+10.10.30.20 The events for a particular day should be +grouped together.
+10.10.30.30 There should be a simple mechanism for adding +an event for a particular day.
+10.10.30.40 The currently selected day should be +highlighted or otherwise clearly indicated to the user.
+10.10.30.50 There should some way to move to the next and +previous week from this particular view.
10.10.40 Month View
+10.10.40.10 The calendar should support a view showing +all the items for a particular month.
+10.10.40.20 The events for a particular day should be +grouped together.
+10.10.40.30 There should be a simple mechanism for adding +an event for a particular day.
+10.10.40.40 The currently selected day should be +indicated.
+10.10.40.50 The application should display only some of +the events per day on the month calendar as oppose to every +item.
+10.10.40.60 There should some way to move to the next and +previous week from this particular view.
+10.10.40.70 For each day, there should be a link to the +day view for that day.
10.10.50 Year View
+10.10.50.10 As a navigational mechanism, the calendar +should support a view that shows all months and days in a +particular year but not necessarily with any information on items +for the days displayed.
+10.10.50.20 For each month, there should be a link to the +month view of that month.
+10.10.50.30 For each day, there should be a link to the +day view of that day.
10.20 Navigation
10.20.10 Navigation Widget
+10.20.10.10 The calendar should provide a widget for +collecting together related navigation links. This should be +similar to the widget provided by Yahoo Calendar and Excite Planner.
+10.20.10.20 Navigation to a different date should +maintain the same view.
+10.20.10.30 In the list, day, and week views, the widget +should display a mini calendar of the days of the current month. +Each day should be a link except for the currently viewed day which +should not be a link and should be highlighted in some manner.
+10.20.10.40 In the month view, the widget should contain +a list of the months of the year. Each month should be a link +except for the month containing the currently viewed day which +should not be a link and should be highlighted in some manner.
+10.20.10.50 In the year view, the widget should contain a +short list of years before and after the current year. Each year +should be a link except for the year containing the currently +viewed day which should not be a link and should be highlighted in +some manner.
+10.20.10.60 The widget should contain some mechanism for +entering an arbitrary date using a clearly defined format, such as +that employed by Yahoo Calendar.
+10.20.10.70 The widget should clearly display today's +date along with some mechanism for navigating to that date.
+10.20.10.80 In the list, day, and week views there should +be a mechanism for jumping forwards or backwards by a whole month +at a time.
+10.20.10.90 In the month and year views, there should be +a mechanism for jumping forwards or backwards by a year at a +time.
10.20.20 View Specific Navigation
+10.20.20.10 Each view except for 'list' should have some +easy mechanism for jumping forward or backward by the interval +being viewed.
+10.20.20.20 Selecting a day in week, month, or year view +should take you to the day view for the that day.
+10.20.20.30 Selecting a month in year view should take +you to the month view for that month.
10.30 Adding Events
+10.30.10 Adding an event should involve entering +information for the event in a form and then submitting that form. +Form should include title, start date and time, or an explicit +indication that the event does not have a start time. Default +values should already be entered with the correct time zone offset +in place. Non-required fields should include end time or duration, +type information, a description, to which party the event belongs, +and an indicator as to whether or not this event recurs.
+10.30.20 There should be a simple, clearly labeled link +for adding an event. The date should default to the currently +viewed date and the present time.
+10.30.30 The time guide in the day view should have links +from each hour and from the slot for items with no start time.
+10.30.40 Selecting the 'no start time' link should bring +up the form with the date defaulting to the currently viewed date +and the 'no start time' indicator set.
+10.30.50 Selecting a link from a specific hour should +bring up the form with the date defaulting to the currently viewed +date, the start time to the hour selected, and the end time to one +hour later.
+10.30.60 The week view should have a link for each day +for adding an item.
+10.30.70 The month view should have a link for each day +for adding an item.
+10.30.80 As in the Yahoo style calendar, there should be +a 'quick add' box on the side of their calendar that allows user to +add events quickly without having to click through on different +days and different views.
10.40 Viewing Events
+10.40.10 Selecting an event's title from any view should +display details for that event, including links to edit, add +attachment, and delete.
10.50 Editing Events
+10.50.10 While viewing an event, select 'Edit'. You +should get a form allowing you to edit the title, date, times, +types, and description for the event. Non-recurring items should +have a "Repeat?" field but not an "Update?" field. [need to +clarify what this means] +
10.60 Adding Recurring Events
+10.60.10 If the recurring events indicator is selected in +the form for adding an item, then after submitting that form, a +second form should be presented which summarizes the date and time +of the item and provides fields to set how the item recurs.
+10.60.20 The form should include fields to enter the type +of interval, the number of intervals between recurrences, and any +specific information for the selected type of interval.
10.70 Editing Recurring Events
+10.70.10 Selecting Edit when viewing a repeating item +should add a field at the bottom of the form to specify whether any +changes should be applied to only the current instance being edited +or to all instances of this recurring item.
10.80 Adding Attachments to Events
+10.80.10 When viewing an item, there should be a link to +add an attachment to that item. Selecting that link should bring up +a form to add attachments of various types.
+10.80.20 The form should include a field for the title of +the attachment.
+10.80.30 One type of admissible attachment supported +should be an uploaded file. This type should be handled in the +standard ACS manner.
+10.80.40 One type of admissible attachment should be a +URL.
+10.80.50 One type of admissible attachment should be a +block of text. The form should provide a text box for entering the +text and a way to indicate if the text is plaintext or HTML.
+10.80.60 After adding an attachment of any sort, the +calendar should return to the view of the item which should have a +list of attachments including the attachment just added.
+10.80.70 For each attachment listed, there should be +displayed -- when permissions admit -- the title of the attachment, +a link to the content of the attachment, a link to manage the +attachment, and a link to edit it.
+10.80.80 For a file attachment, the content link should +return the content of the file.
+10.80.90 For a URL attachment, the content link should +navigate to the URL.
+10.80.100 For a text attachment, the content link should +display the entered text.
+10.80.110 The manage link links to the management page of +the corresponding file in the file-storage system. [file-storage +or CR?] +
+10.80.120 The edit link allows direct editing of the +content of the attachment.
10.90 Inviting other groups to view Events
+10.90.10 The application should have a link that lets the +owner of the event to invite other groups, individual or parties to +add this event to their personal calendars.
10.100 Deleting events
+10.100.10 When viewing an item, there should be a link to +delete that item.
+10.100.20 Selecting the delete link should bring up a +confirmation dialog.
+10.100.30 If the item is not recurring, then the choice +button will simply be labeled 'OK'.
+10.100.40 If the item is recurring, then in addition to +the choice buttons, there should be a selection to indicate either +the current instance only or all occurrences.
+10.100.50 Selecting 'Cancel' should return to the item +view.
+10.100.60 Selecting 'OK' should delete the item in +question.
+10.100.70 If the item was recurring and 'all occurrences' +had been selected, then all other occurrences of the item should be +deleted as well.
+10.100.80 Selecting OK should return to the view where +the item was originally selected.
+20.10 The calendar should display a list of calendars to +which the user has access. At a minimum, this will include the +user's personal calendar and a public events calendar. If the user +belongs to parties that have party-specific events associated with +them, there should be additional links to these party-specific +events as well as the calendar of the party to which the user +belongs.
+20.30 On the personal calendar, there should also be a +toggle for each such party that controls whether or not events from +that party appear on the personal calendar.
+20.40 On a user's calendar, party-specific events should +indicate to which party they are specific.
+20.50 The link for adding an event should clearly +indicate whether a party-specific item or a personal item will be +created.
+30.10 If the user has write permission to any parties, +when he chooses to add an event, the choice of which party to +associate with that event is given.
+30.20 There should also be a page where permissions of +read, write, approve, and delete can be given to different +parties
+30.30 There should be a link to the admin page for the +group.
+30.40 There should be a way to delete the calendar. This +route should involve passing the user through a confirmation +dialog.
40.10 Calendar User Privilege Administration
+40.10.10 Cal Admin must have access to pages where +permissions can be set for different parties
+40.10.20 Cal Admin can also add new user +party/groups/person to the entire calendar
+40.10.30 Cal Admin can also add new user +party/groups/person to indivdual calendar items
40.20 Calendar Items Administration
+40.20.10 Provides the funcationality to delete, add, edit +any item on the calendar
+40.20.20 Provides the funcatinality to allow Calendar +Administrator to change the permissions on each calendar item.
+40.20.20 Provides the funcatinality to allow Calendar
+Administrator to change the default permissions of the entire
+calendar
+
50.10 Calendar Events Manipulation
+50.10.10 Provide a function to add a new item to a +calendar. This function should support specifying all the values +that can be specified in the 'add item' form. It should allow +creating either a user or a party-specific item. Iit should support +specifying a mapping between the new item and an arbitrary object +in the database.
50.20 Calendar Views
+50.20.10 Provide a function to generate the HTML for the +list view.
+50.20.20 Provide a function to generate the HTML for the +day view.
+50.20.30 Provide a function to generate the HTML for the +week view.
+50.20.40 Provide a function to generate the HTML for the +month view.
+50.20.50 Provide a function to generate the HTML for the +year view.
+50.20.60 Provide a function to generate the HTML for the +calendar navigation.
+50.20.70 Provide a function to generate the HTML for the +complete calendar.
Document Revision # | Action Taken, Notes | When? | By Whom? | +
---|---|---|---|
0.1 | Creation | 2000/10/25 | W. Scott Meeks | +
0.2 | Emendation | 2000/11/10 | Gary Jin | +
0.3 | Edit for Content and Consistency | 2000/11/10 | Joshua Finkler | +
0.4 | Additional revisions and included cX-Mozilla-Status: +0009eview | 2000/11/30 | Gary Jin | +
0.5 | Further Revisions | 2000/12/02 | Joshua Finkler | +
0.6 | Revisions of User Cases and Scenario sections and applied +corrections. | 2000/12/04 | Gary Jin | +
0.7 | Further Revisions | 2000/12/06 | Joshua Finkler and Gary Jin | +
In addition to mapping an entire tree to an object, admins have
+the option of mapping only a subtree of an existing tree. To do
+that, they have to click on a "Map subtree" link, after which they
+will see a list of tree nodes.
+The mapped subtree will consist of all subcategories of the
+category the user selected - the category itself will not be
+included. Note that the mapped subtree will not be a new tree.
+Therefore this option should be used only if an admin plans to use
+the subtree 'as is' and has no intention of making changes to
+it.
An alternative solution is available for admins who want to
+create a tree by copying one of the existing trees and subsequently
+playing around with it (moving/adding/deleting categories). To
+accomplish that, they would have to create a new tree, go to the
+admin page for this tree and click on a "Copy existing tree" link.
+They will see a list of available trees to copy. Clicking on the
+"Copy this one" link will result in creating copies of the
+categories from the source trees and placing them in the new
+tree.
+This operation can be performed several times, each time the copied
+categories will be placed as toplevel categories of the tree.
As far as unmapping is concerned, this operation doesn't delete +the mapping between categories and objects.
Permissions
The creator of the category tree is granted the
+category_tree_read, category_tree_write and
+category_tree_grant_permissions privileges.
+
The operations one can perform on categories are:
ad (d) You cannot delete a category that has children. Also, you
+cannot delete a category that has objects mapped to it (do we want
+it or not?)
+ad (e) The effect of phasing out a category is that users no longer
+will be able to associate objects with it, but existing
+associations will still be visible
+Deletions and phasing it/out can be performed as bulk
+operations.
+ad (f) sort key is used to order children of the same parent
+category, that is the elements of the tree are sorted first by
+parent, then by the sort key.
This table actually stores the information whether the tree is +side-wide or not.
+create table category_trees ( + tree_id integer primary key + constraint cat_trees_tree_id_fk + references acs_objects on delete cascade, + site_wide_p char(1) default 't' + constraint cat_trees_site_wide_p_ck + check (site_wide_p in ('t','f')) +); +
Here the tree's name and description is stored in different +translations.
+create table category_tree_translations ( + tree_id integer + constraint cat_tree_trans_tree_id_fk + references category_trees on delete cascade, + locale varchar2(5) not null + constraint cat_tree_trans_locale_fk + references ad_locales, + name varchar2(50) not null, + description varchar2(1000), + primary key (tree_id, locale) +); +
This table stores the tree hierarchy by holding the information +about the parent category. The tree is ordered by a nested index +(left_ind, right_ind). Sorting is thus accomplished by means of a +nested set. You can read a +description of how nested sets work. This also describes how +to write queries that sort correctly when using categories.
+create table categories ( + category_id integer primary key + constraint cat_category_id_fk + references acs_objects on delete cascade, + tree_id integer + constraint cat_tree_id_fk + references category_trees on delete cascade, + parent_id integer + constraint cat_parent_id_fk + references categories, + deprecated_p char(1) default 'f' + constraint cat_deprecated_p_ck + check (deprecated_p in ('t','f')), + left_ind integer, + right_ind integer +); +
Here the actual categories are stored together with different +translations.
+create table category_translations ( + category_id integer + constraint cat_trans_category_id_fk + references categories on delete cascade, + locale varchar2(5) not null + constraint cat_trans_locale_fk + references ad_locales, + name varchar2(200), + description varchar2(4000), + primary key (category_id, locale) +); +
This table contains mapping between categories and objects
+create table category_object_map ( + category_id integer + constraint cat_object_map_category_id_fk + references categories on delete cascade, + object_id integer + constraint cat_object_map_object_id_fk + references acs_objects on delete cascade, + primary key (object_id, category_id) +) organization index; +
This is the table for the relation of trees and objects. +subtree_category_id comes to play in situations when you map a +subtree of an existing tree to an object.
+create table category_tree_map ( + tree_id integer + constraint cat_tree_map_tree_id_fk + references category_trees on delete cascade, + object_id integer + constraint cat_tree_map_object_id_fk + references acs_objects on delete cascade, + subtree_category_id integer default null + constraint cat_tree_map_subtree_id_fk + references categories, + primary key (object_id, tree_id) +) organization index; +
Known Limitations
Integration with other packages
Here are the changes needed to be made to integrate with other +packages.
+index.adp
+Provide an admin-link to
+/categories/cadmin/one-object?object_id=\@package_id\@ to let admins
+map trees to the package instance.
+form-page.tcl
+Use this in ad_form to display all mapped category trees and
+selected categories (if editing an object):
+ {category_ids:integer(category),multiple,optional {label "Categories"} + {html {size 4}} {value {$object_id $package_id}}} ++Alternatively, you can include the following in your adp: +
+ <include src="/packages/categories/www/include/widget" object_id=\@object_id\@ package_id=\@package_id\@> ++In the processing part of ad_form use: +
+category::map_object -remove_old -object_id $object_id $category_ids +
Table of Contents
++acs_objects.name(object_id) ++which essential means that for every object to be displayed (and +since the mentioned pages are in no means scalable and therefore +are likely to display a huge amount of objects) this pl/sql proc +will have to figure out which package-specific pl/sql proc to call +which itself will do at least one query to get the object-name. +
Obviously, this is highly undesirable since it is not scalable +at all. Therefore, a new way had to be found to get the name of an +object:
+------------------- +-- NAMED OBJECTS -- +------------------- + +create table acs_named_objects ( + object_id integer not null + constraint acs_named_objs_pk primary key + constraint acs_named_objs_object_id_fk + references acs_objects(object_id) on delete cascade, + object_name varchar2(200), + package_id integer + constraint acs_named_objs_package_id_fk + references apm_packages(package_id) on delete cascade +); + +create index acs_named_objs_name_ix on acs_named_objects (substr(upper(object_name),1,1)); +create index acs_named_objs_package_ix on acs_named_objects(package_id); + +begin + acs_object_type.create_type ( + supertype => 'acs_object', + object_type => 'acs_named_object', + pretty_name => 'Named Object', + pretty_plural => 'Named Objects', + table_name => 'acs_named_objects', + id_column => 'object_id' + ); +end; +/ +show errors ++This means that every displayable object-type should no longer be +derived from acs_objects, but from acs_named_objects and that by +using triggers or extending the appropriate pl/sql procs, every +displayable object (certainly not acs_rels or something the like) +should have an evtry in that extension of the acs_objects table. +
In that way, when having to display a list of objects, one can +simply join the acs_named_objects table to get the names and +package_ids in an easy and - more importantly - fast and scalable +way.
The only shortcomming of this solution is the disregard of +internationalization, but in cases where there objects in more than +one language, it should be the triggers / pl/sql procs task to make +sure that acs_named_objects contains names in the default language +if possible.
First, we need to know that package_id of the package +responsible for the object. This information is currently +impossible to get since we would need to go up the context +hierarchy until we finally get hold of an apm_package object. But +lets assume we get this information by using the new +acs_named_objects table, then we would need to figure out the url +to that package instance. This can be done, but again by calling a +highly unefficient pl/sql proc. But even then we would need the +local url to the page being able to display a certain object. Since +a package may have more than one type of objects (i.e. file +folders, files, file versions), we can not simply store additional +package information about which page to call to display an +object.
The solution to this kind of problem is by not resolving the url +at all during display-time, but doing so at the time the user +actually wants to see an object. The links would simply direct to +/o/$object_id, which is a global virtual-url-handling page that +will figure out the package instance url (by using +acs_named_objects and the pl/sql proc) and then relying upon a +Service Contract to get the local url - that means every package +holding displayable objects should implement this interface for its +objects:
+declare + v_id integer; +begin + v_id := acs_sc_contract.new( + contract_name => 'AcsObject', + contract_desc => 'Acs Object Id Handler' + ); + v_id := acs_sc_msg_type.new( + msg_type_name => 'AcsObject.PageUrl.InputType', + msg_type_spec => 'object_id:integer' + ); + v_id := acs_sc_msg_type.new( + msg_type_name => 'AcsObject.PageUrl.OutputType', + msg_type_spec => 'page_url:string' + ); + v_id := acs_sc_operation.new( + contract_name => 'AcsObject', + operation_name => 'PageUrl', + operation_desc => 'Returns the package specific url to a page +that displays an object', + operation_iscachable_p => 'f', + operation_nargs => 1, + operation_inputtype => 'AcsObject.PageUrl.InputType', + operation_outputtype => 'AcsObject.PageUrl.OutputType' + ); + + v_id := acs_sc_impl.new ( + 'AcsObject', + 'apm_package_idhandler', + 'acs-kernel' + ); + v_id := acs_sc_impl.new_alias ( + 'AcsObject', + 'apm_package_idhandler', + 'PageUrl', + 'apm_pageurl', + 'TCL' + ); + acs_sc_binding.new ( + contract_name => 'AcsObject', + impl_name => 'apm_package_idhandler' + ); + + v_id := acs_sc_impl.new ( + 'AcsObject', + 'user_idhandler', + 'acs-kernel' + ); + v_id := acs_sc_impl.new_alias ( + 'AcsObject', + 'user_idhandler', + 'PageUrl', + 'acs_user::pageurl', + 'TCL' + ); + acs_sc_binding.new ( + contract_name => 'AcsObject', + impl_name => 'user_idhandler' + ); +end; ++The appropriate tcl-procs look like the following: +
+ad_proc -public apm_pageurl { object_id } { + Service Contract Proc to resolve a url for a package_id +} { + return +} + +namespace eval acs_user { + ad_proc -public pageurl { object_id } { + Service Contract Proc to resolve a url for a user_id + } { + return "shared/community-member?user_id=$object_id" + } +} ++Note that the name of the implementation has to be the object-type +followed by _idhandler. +
Automated Testing provides a framework for executing tests of +all varieties and for storing and viewing the results.
+Req # | Status in 5.0 | Priority for 5.1 (A=required, +B=optional) | Description | +
---|---|---|---|
1 | Done | Done | Store trees of category labels | +
1.1 | ? | A | Category is package-aware. (Data in one package is not visible +from another package. There is a permission-based way to accomplish +this, but it is not obvious in the UI.) | +
2 | Done | Done | There is a GUI for administrators to manage category trees +(create, delete, move leaves, edit leaves). | +
3 | Done | Done | An OpenACS Object can be associated with zero, one, or more +categories. | +
3.1 | partial | A | There is a GUI to control which categories are associated with +an object. | +
3.1.1 | Done | Done | A package administrator can choose which category trees apply +to a package or parent object. The list of category trees which +apply to an object or its parent is called the enabled tree list. | +
3.1.2 | Done | Done | There is a facility to control object/category association. +(via /categories/www/form-page.tcl.) | +
3.1.3 | Done | The enabled trees for an +object can be added as fields in form builder. (Current ad_form +implementation supports single select and multiple select; all +enabled trees or none. /categories/www/widget is a deprecated +solution.) | +|
3.1.4 | B | A GUI for linking any category (even one not in the +enabled trees) to an +object. | +|
3.2 | partial | A | A GUI to see an object's categories. | +
3.2.1 | A | All of the categories which an object belongs to can be +displayed via an includelet on an object view page. (/categories/www/widget) | +|
4 | A | List-builder can sort and filter by category. (Implemented; not +documented. single-select only.) | +|
5 | partial | A | Show all objects in a category. The current implementation is +deprecated - see TIP #44: Service Contract to resolve the url from an +object_id and TIP #43: Adding object_name to acs_objects + | +