--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/app/soc/models/quiz.py	Wed Oct 15 17:10:27 2008 +0000
@@ -0,0 +1,104 @@
+#!/usr/bin/python2.5
+#
+# Copyright 2008 the Melange authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""This module contains the Quiz Model."""
+
+__authors__ = [
+  '"Todd Larsen" <tlarsen@google.com>',
+]
+
+import reflistprop
+
+from google.appengine.ext import db
+
+from django.utils.translation import ugettext_lazy
+
+import soc.models.answer
+import soc.models.document
+import soc.models.question
+
+
+class Quiz(soc.models.document.Document):
+  """Model of a Quiz, a collection of Questions to be asked.
+  
+  (named Quiz because Questionnaire was too much to type...)
+  
+  A Quiz collects a set of Questions to which Answers are given in the
+  form of a separate Model called a Response.
+
+  Quizzes can even be used as templates for comments and scoring
+  annotations to various Works, such as Documents and Proposals.  A
+  separate Review Model is derived from Quiz for these purposes.
+
+  The specific way that the properties and relations inherited from
+  Document, and also indirectly from Work, are used with a Quiz are
+  described below.
+
+    work.title:  the title of the Quiz
+
+    work.abstract:  summary displayed as a snippet in Quiz list views
+
+    work.authors:  the Authors of the Work referred to by this relation
+      are the authors of the Quiz (but not necessarily the individual
+      Questions themselves, see the Question Model)
+
+    work.reviews:  even Quizzes can be "reviewed" (possibly commented
+      on during creation or annotated once put into use).
+
+    work.partial_path/work.link_name: used to scope and uniquely identify
+      a Quiz in the same way these properties are used with Documents, etc.
+
+    document.content:  the "preface" of the Quiz, displayed before any
+      of the Questions, usually containing instructions for the Quiz
+
+  In addition to any explicit ReferenceProperties in the Quiz Model and
+  those inherited as described above, a Quiz entity participates in these
+  relationships:
+
+    responses)  a 1:many relationship where each Quiz can produce all of
+      its many Response entities that indicate they contain specific
+      Answers to each of the Questions contained in that Quiz. This relation
+      is implemented as the 'responses' back-reference Query of the Response
+      Model 'quiz' reference.
+      
+    solutions)  a 1:many relationship where some (or none, or all) of the
+      Questions in the Quiz have "solutions" or "correct Answers".  The
+      'solutions' back-reference Query of the Answer Model 'quiz' reference
+      is used to point these "correct Answers" at the Quiz to which they
+      apply.  One example of a Quiz having a "correct Answer" is a GSoC
+      mentor survey that has a "pass" Question that gates if the student
+      gets paid.  The desired Answer for this Question would be
+      associated with the Quiz via the 'quiz' property and some controller
+      logic could check if a survey "passed" by querying for these
+      "solution" Answers and seeing if the survey Response had the "right"
+      Answers (to the one Question that matters in this case...).
+  """
+  
+  #: a many:many relationship (many:many because a given Question can be
+  #: reused in more than one Quiz, and each Quiz is made up of one or more
+  #: Questions) between Question entities and, when combined, the Quiz they
+  #: form.
+  #:
+  #: A ReferenceListProperty is used instead of a special many:many
+  #; relation Model for a number of reasons:
+  #:   1) the Questions in a Quiz need to be ordered
+  #:   2) Quizzes will have relatively few Questions, so the performance
+  #:      ReferenceListProperty is not a major concern
+  #:   3) querying a Question for all of the Quizzes that contain it is
+  #:      a rare occurrence, so the expense of a ListProperty query is
+  #:      not a real concern
+  questions = reflistprop.ReferenceListProperty(
+    soc.models.question.Question, default=None)