Merge pull request #425 from edx/ahodges/RESpolls

Ahodges/RESpolls

en_us/data/source/front_matter/change_log.rst

@@ -15,6 +15,9 @@ July-September 2015
 
    * - Date
      - Change
+   * - 8 Jul 2015
+     - Added new events for :ref:`polls and surveys<Poll and Survey Events>` to
+       the :ref:`Tracking Logs` section.
    * - 1 Jul 2015
      - Added new events for :ref:`problem hints<problem>` to the
        :ref:`Tracking Logs` section.

en_us/data/source/internal_data_formats/event_list.rst

@@ -4,6 +4,16 @@
 Alphabetical Event List
 #######################
 
+
+:ref:`ABC` - :ref:`DEF` - :ref:`GHI` - :ref:`JKL` - :ref:`MNO` 
+- :ref:`PQR` - :ref:`ST` - :ref:`UVWXYZ`
+
+.. _ABC:
+
+*******
+A, B, C
+*******
+
 .. list-table::
    :widths: 40 40
    :header-rows: 1
@@ -28,6 +38,19 @@ Alphabetical Event List
      - :ref:`Instructor_Event_Types`
    * - ``child_render``
      - :ref:`AB_Event_Types`
+
+.. _DEF:
+
+*******
+D, E, F
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``delete-student-module-state``
      - :ref:`Instructor_Event_Types`
    * - ``dump-answer-dist-csv``
@@ -118,6 +141,19 @@ Alphabetical Event List
      - :ref:`video`, see ``hide_transcript``
    * - ``edx.video.transcript.shown``
      - :ref:`video`, see ``show_transcript``
+
+.. _GHI:
+
+*******
+G, H, I
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``get_anon_ids``
      - :ref:`Instructor_Event_Types`
    * - ``get_student_progress_page``
@@ -132,6 +168,19 @@ Alphabetical Event List
      - :ref:`video`
    * - ``instructor``
      - :ref:`Instructor_Event_Types`
+
+.. _JKL:
+
+*******
+J, K, L
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``list-beta-testers``
      - :ref:`Instructor_Event_Types`
    * - ``list-forum-admins``
@@ -148,6 +197,19 @@ Alphabetical Event List
      - :ref:`Instructor_Event_Types`
    * - ``load_video``
      - :ref:`video`
+
+.. _MNO:
+
+*******
+M, N, O
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``modify_access``
      - :ref:`Instructor_Event_Types`
    * - ``oe_feedback_response_selected``
@@ -176,6 +238,19 @@ Alphabetical Event List
      - :ref:`ora2`
    * - ``openassessment.upload_file``
      - :ref:`ora2`
+
+.. _PQR:
+
+*******
+P, Q, R
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``page_close``
      - :ref:`navigational`
    * - ``pause_video``
@@ -222,6 +297,19 @@ Alphabetical Event List
      - :ref:`Instructor_Event_Types`
    * - ``rubric_select``
      - :ref:`ora`
+
+.. _ST:
+
+*******
+S, T
+*******
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``save_problem_fail``
      - :ref:`problem`
    * - ``save_problem_success``
@@ -272,12 +360,33 @@ Alphabetical Event List
      - :ref:`pdf`
    * - ``textbook.pdf.zoom.menu.changed``
      - :ref:`pdf`
+
+.. _UVWXYZ:
+
+*********************
+U, V, W, X, Y, Z
+*********************
+
+.. list-table::
+   :widths: 40 40
+   :header-rows: 1
+
+   * - Event
+     - Description
    * - ``update_forum_role_membership``
      - :ref:`Instructor_Event_Types`
    * - ``video_hide_cc_menu``
      - :ref:`video`
    * - ``video_show_cc_menu``
      - :ref:`video`
+   * - ``xblock.poll.submitted``
+     - :ref:`Poll and Survey Events`
+   * - ``xblock.poll.view_results``
+     - :ref:`Poll and Survey Events`
+   * - ``xblock.survey.submitted``
+     - :ref:`Poll and Survey Events`
+   * - ``xblock.survey.view_results``
+     - :ref:`Poll and Survey Events`
 
 
 

en_us/data/source/internal_data_formats/tracking_logs.rst

@@ -399,7 +399,7 @@ This section lists the events that are typically initiated by learners. These
 events are generated by interactions with the learning management system (LMS)
 other than the  Instructor Dashboard.
 
-.. contents:: Section Contents 
+.. contents::  
   :local:
   :depth: 1
 
@@ -2174,8 +2174,8 @@ information about interactions with problems.
 
 These events were designed for the problem types implemented in the edX
 platform by the ``capa_module.py`` XBlock. Problem types that are implemented
-by other XBlocks, such as :ref:`open response assessments<ora2>`, are
-instrumented with different events.
+by other XBlocks, such as :ref:`open response assessments<ora2>` or :ref:`polls
+and surveys<Poll and Survey Events>`, are instrumented with different events.
 
 For more information about designing problems to include hints, feedback, or
 both, see `Adding Hints and Feedback to a Problem`_ in the *Building and
@@ -2338,7 +2338,7 @@ field.
      - Details
    * - ``answers``
      - dictionary
-     - The problem ID and the internal answer identifier in a name:value pair.
+     - The problem ID and the internal answer identifier in a name/value pair.
        For a component with multiple problems, lists every problem and
        answer.
    * - ``attempts``
@@ -2838,7 +2838,7 @@ delivered for the first time.
 
        * ``descendants``, when present, is a list that identifies each
          part of a library component that contains multiple parts (the
-         children of an xblock with children).
+         children of an XBlock with children).
 
        * ``original_usage_key`` and ``original_usage_version`` identify the
          component in the library. 
@@ -3335,9 +3335,9 @@ peer's response or submits a self-assessment of her own response.
        rubric's criteria.
 
        * ``criterion`` (object) contains ``points possible`` and ``name``
-         member fields
-       * ``option`` (string)
-       * ``feedback`` (string)
+         member fields.
+       * ``option`` (string).
+       * ``feedback`` (string).
 
        When the only criterion in the rubric is student feedback, ``points
        possible`` is 0 and the ``option`` field is not included.
@@ -3532,6 +3532,96 @@ the response.
      - The MIME type of the uploaded file. Reported by the student's browser.
 
 
+.. _Poll and Survey Events:
+
+===========================
+Poll and Survey Events
+===========================
+
+This section describes events emitted by the poll and survey XBlocks. 
+
+.. contents::  
+  :local:
+  :depth: 1
+
+**History**: Added 8 Jul 2015.
+
+``xblock.poll.submitted``
+************************************
+
+The server emits an ``xblock.poll.submitted`` event each time a user submits a
+response to a poll.
+
+**Event Source**: Server
+
+``event`` **Member Fields**:
+
+.. list-table::
+   :widths: 15 15 60
+   :header-rows: 1
+
+   * - Field
+     - Type
+     - Details
+   * - ``url_name``
+     - string
+     - The unique location identifier for the poll XBlock.
+   * - ``choice``
+     - string
+     - The unique internal identifier for the response that the user submitted.
+
+
+``xblock.poll.view_results``
+************************************
+
+The server emits an ``xblock.poll.view_results`` event when a tally of the
+responses to a poll is displayed to a user. For a poll that has the **Private
+Results** option set to False, the tally appears after a user submits a
+response.
+
+**Event Source**: Server
+
+``event`` **Member Fields**: None
+
+``xblock.survey.submitted``
+************************************
+
+The server emits an ``xblock.survey.submitted`` event each time a user submits
+responses to a survey.
+
+**Event Source**: Server
+
+``event`` **Member Fields**:
+
+.. list-table::
+   :widths: 15 15 60
+   :header-rows: 1
+
+   * - Field
+     - Type
+     - Details
+   * - ``url_name``
+     - string
+     - The unique location identifier for the survey XBlock.
+   * - ``choices``
+     - object
+     - Name/value pairs that identify each question in the survey and the
+       responses that the user selected, in the format 
+       ``"question_name": "'response_name"``.
+
+
+``xblock.survey.view_results``
+************************************
+
+The server emits an ``xblock.survey.view_results`` event when a matrix of
+survey response percentages is displayed to a user. For surveys that have the
+**Private Results** option set to False only, the matrix appears after a user
+submits survey responses.
+
+**Event Source**: Server
+
+``event`` **Member Fields**: None
+
 .. _content:
 
 ===========================