1 #!/usr/bin/python2.5

     2 #

     3 # Copyright 2008 the Melange authors.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 #

     9 #   http://www.apache.org/licenses/LICENSE-2.0

    10 #

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """This module contains the Quiz Model."""

    18 

    19 __authors__ = [

    20   '"Todd Larsen" <tlarsen@google.com>',

    21 ]

    22 

    23 import reflistprop

    24 

    25 from google.appengine.ext import db

    26 

    27 from django.utils.translation import ugettext_lazy

    28 

    29 import soc.models.answer

    30 import soc.models.document

    31 import soc.models.question

    32 

    33 

    34 class Quiz(soc.models.document.Document):

    35   """Model of a Quiz, a collection of Questions to be asked.

    36   

    37   (named Quiz because Questionnaire was too much to type...)

    38   

    39   A Quiz collects a set of Questions to which Answers are given in the

    40   form of a separate Model called a Response.

    41 

    42   Quizzes can even be used as templates for comments and scoring

    43   annotations to various Works, such as Documents and Proposals.  A

    44   separate Review Model is derived from Quiz for these purposes.

    45 

    46   The specific way that the properties and relations inherited from

    47   Document, and also indirectly from Work, are used with a Quiz are

    48   described below.

    49 

    50     work.title:  the title of the Quiz

    51 

    52     work.abstract:  summary displayed as a snippet in Quiz list views

    53 

    54     work.authors:  the Authors of the Work referred to by this relation

    55       are the authors of the Quiz (but not necessarily the individual

    56       Questions themselves, see the Question Model)

    57 

    58     work.reviews:  even Quizzes can be "reviewed" (possibly commented

    59       on during creation or annotated once put into use).

    60 

    61     work.partial_path/work.link_name: used to scope and uniquely identify

    62       a Quiz in the same way these properties are used with Documents, etc.

    63 

    64     document.content:  the "preface" of the Quiz, displayed before any

    65       of the Questions, usually containing instructions for the Quiz

    66 

    67   In addition to any explicit ReferenceProperties in the Quiz Model and

    68   those inherited as described above, a Quiz entity participates in these

    69   relationships:

    70 

    71     responses)  a 1:many relationship where each Quiz can produce all of

    72       its many Response entities that indicate they contain specific

    73       Answers to each of the Questions contained in that Quiz. This relation

    74       is implemented as the 'responses' back-reference Query of the Response

    75       Model 'quiz' reference.

    76       

    77     solutions)  a 1:many relationship where some (or none, or all) of the

    78       Questions in the Quiz have "solutions" or "correct Answers".  The

    79       'solutions' back-reference Query of the Answer Model 'quiz' reference

    80       is used to point these "correct Answers" at the Quiz to which they

    81       apply.  One example of a Quiz having a "correct Answer" is a GSoC

    82       mentor survey that has a "pass" Question that gates if the student

    83       gets paid.  The desired Answer for this Question would be

    84       associated with the Quiz via the 'quiz' property and some controller

    85       logic could check if a survey "passed" by querying for these

    86       "solution" Answers and seeing if the survey Response had the "right"

    87       Answers (to the one Question that matters in this case...).

    88   """

    89   

    90   #: a many:many relationship (many:many because a given Question can be

    91   #: reused in more than one Quiz, and each Quiz is made up of one or more

    92   #: Questions) between Question entities and, when combined, the Quiz they

    93   #: form.

    94   #:

    95   #: A ReferenceListProperty is used instead of a special many:many

    96   #; relation Model for a number of reasons:

    97   #:   1) the Questions in a Quiz need to be ordered

    98   #:   2) Quizzes will have relatively few Questions, so the performance

    99   #:      ReferenceListProperty is not a major concern

   100   #:   3) querying a Question for all of the Quizzes that contain it is

   101   #:      a rare occurrence, so the expense of a ListProperty query is

   102   #:      not a real concern

   103   questions = reflistprop.ReferenceListProperty(

   104     soc.models.question.Question, default=None)