                        Setting up a custom History

It is often useful to supply participants with a History of their decisions and their results,
that spans all of the rounds of a session.   dSurvey provides a few means for implementing a History.

For an easy to specify, but not particularly fancy format, you can use
  *  the <history> special tagname in SPEC files and in a module
<history> is described in the SPEC file and dynamic-extensions documentation files.

While convenient, <history> is not particularly powerful.

What follows describes one way of creating a custom History -- using specially defined modules, and using
<update> and <popup> in your SPEC file.

Contents:

I       The Outline
I.1        The basic steps
I.2        A note on coding rows of the history.
I.3        A note on prior variables:
I.4        A note on recovering after browser reload:
II      The Details
II.1       Spec file entries.
II.1.a       Initializing the history
II.1.b       Recording prior variables
II.1,c       Write to the history 
II.2       Module entries
II.2.d       Displaying the History.
II.2.e       The overall template for the History
II.2.f       Specify one round
II.3     Alternative

                        ===================== 

I)  The Outline

The following outlines how to create a "custom history", where each row (or set of rows) in this
history contains information on one round of the session.

Note that this outline uses special tagnames (<update> and <popup>) that are more completely described
in the SPEC guide.

I.1) The basic steps

  a) Initialize an internal module that will contain the history.
  b) At the beginning of a new round, save prior parameters, possibly including results provided in a CAP file.
  c) Every round (say, also at the beginning of a new round), add to the "history"

and

  d) Specify a <button> that, when clicked, displays the history  in a new window
  e) Specify a module that contains the  "history page" -- the history will be
     placed in this history page.
  f) Specify a module that specifies one round of the "history". Step c uses this module

I.2) A note on coding rows of the history.

   Basically, you will have to write modules that display "prior round variables".  
   You will probably use dSurvey's special tagnames, such as  <show>, with "dotted" variable names.

   For example:
       <show var="cost." />  means "show the cost of the prior round"
       <show var="cost.10" />  means "show the cost of the round 10"
       <show var="cost.irnd" />  means "show the cost of the irnd round, where irnd can be a <repeat> variable

I.3) A note on prior variables:

   Suppose you implement step b by specifying  
        <params priors="save" ...>
   or
        <params priors="both" ...>
   at the beginning of all rounds. 

   This will save all the variables currently defined, BEFORE a CAP file is read.
      In other words, if this <params> is at the start of round n, the n-1'th round's variables
      will be saved "en masse".  

   These will be saved to the "prior variables internal database". 

   Assuming this is done at the beginning of every round, that means that at the beginning
   of round n, the variables of all rounds (from 1 to n-1) will cumulatively be stored in this "prior
   variables internal database".

   However, variables specified in a CAP file will be read AFTER this "en masse" savings.
   Thus, in order to save the "results of the prior" round, the CAP file must explicitily
   reference prior round variables. 

      Prior round variables can be explicitily created by the using a
         varname.iround=a_value
      syntax (where iround is a number between 1 and n-1, or a variable whose value is between 1 and n-1). 

   Fortunately, "results" variables added to the CAP file automatically use this explicit syntax --
   see II.1.b for further details.
   
   
I.4) A note on recovering after browser reload:

   If the participant is forced to reload his browser, the "prior round variables internal database" 
   will be lost.  This can be dealt with by "recovering" a server-side history file.

   To do this:
        a) In the first section of your instrument, specify a:
               <exec>
                 <recoverPrior toModule="amodule" modules="modlsit" />
                  ...
               </exec>
           Actually, you might want to embed the <recoverPrior> within an <if>, 
           such as:
               <if value="nowRound.g gt 1">
                  <recoverPrior toModule="amodule" modules="modlsit" />
               </if>
         
        b) Be sure to use 
                <uploadData type="history">varlist </uploadData>
          where the varlist should refer to variables that will be used to create the History --
          and can general, results, and other control panel variables.

         This <uploadData> should be called before participants are told to go to the next round
         (say, after results have been computed)..
    
     Caution: rebuilding a history can be time consuming -- you might want to us an <if>
              and a <confirm> to ask the participant if he wants to bother.

                        ===================== 

II) The Details

The following details refer to the steps noted in the above outline.

Note:
   The following uses various names for modules, such as "historyBuild" and 
   "history_oneRound". These are arbitrary names -- you can use whatever names you
    chose (so long as you refer to them correctly).

   In addition, it is quite possible to create more than one History -- say a "short"
   and a "long" History. Just set up two sets of "modules" etc. by replicating the
   following steps with different names. If you do this, you do NOT need to replicate step b. 

II.1) Spec file entries.

  Steps a to c refer to SPEC file entries. These should be in the order specified. 
  What that actually means depends on how you structure your SPEC File!

  a) Initializing the history 

     In the first session specific section, include the following in an <exec>

        <update toModule="historyBuild"  noprocess="1" modules="history_oneRound"   /> 

     This will create a module with the name "historyBuild". In particular, it will use
     the contents of the history_oneRound module (which will be processed
     for special tagnames, etc).

     Why start with this?
        * At the beginning of the session: it provides a base to add rows to

     Alternatively, if a browser reload occurs, you can create this base by using:

         <recoverPrior toModule="historyBuild"  modules="history_oneRound"   />

     You can use an <if> (i.e.; <if value="nowRound.g eq 1"> ) to choose which of the
     above initializations to use.

     See below for details on the contents of this history_oneRound module.


  b) Recording prior variables

     In the section that starts a new round (after retrieving results for the most
     recently completed round), record to prior-variables the just completed round's variables.
     This is done by using:

             <params  prior="SAVE"  />                      

     In addition, the CAP file may explicitily set prior round variables.

     As noted above in I.3, <params> will record just-completed round's variables BEFORE reading CAP files.
     Thus, <params prior="save"> will NOT save any results determined in the control-panel
     (say, information on whether a participant was "accepted" in the just-completed prior round).

     This is why  this kind of information would be explicitily saved using the CAP file.
      
         For example, if round 17 just completed (and round 18 is about to begin), one could find
         the following in the round CAP file:
            <NOWROUND>18</NOWROUND>
            <TOTAL_EARN.17>1.83</TOTAL_EARN.17>
    
     To support this feature:

         when a <postCAP> includes results data, all of results variables saved to the
         CAP file WILL have a .roundNumber appended to their name. 
         Hence, the above syntax is automatically created.

     For example, assuming that TOTAL_EARN is the only results variable,
        <postCAP type="ROUND">
           <general> *.R nowRound.g </general>
        </postCAP>
     could create 
         <NOWROUND>18</NOWROUND>
         <TOTAL_EARN.17>1.83</TOTAL_EARN.17>


  c) Write to the history 

     After saving prior variables (step b), often in the same section & group as step b, specify:

           <update toModule="historyBuild" append="1" modules="history_oneRound"   />

     This will update the "historyBuild" internal module created in step a. 
     In particular, it will add the contents of the history_oneRound module  
     (which will be processed for special tagnames, etc).

      Note: specifying append="1"
          Specifying append="1" means:
             add new content to the current contents of  historyBuild.
          If you do NOT include an append="1", then the new content will overwrite the current contents
          of historyBuilt. Which means that historyBuild will only contain the most recent round's (round n-1)
          results!

     Why?  For sessions with many rounds, building a history can be time consuming.  

     Thus, if the complete history was re-created every time it is requested, the participant could end 
     up waiting an inordinately long time.

     By using this "on-the-fly add a round to history trick, this wait can be greatly reduced -- 
     since displaying a module (that contains pre-formed history) is much quicker than building
     one from scratch and then displaying it.

II.2) Module entries

The following specifies the <button> event used to display the History, and the
modules you will need to specify what variables to display and how.

  d) Displaying the History.
     There are many ways of displaying a history. The following is one way.

     Include the following <button> (in the appropriate <group> or <group>s).

         <button  id="showHistoryButton" >
             <text>Click here to view your history</text>
             <popup modules="historyBase" target="historyWindow" retain="1">
                 <title>The history of your decisions</title>
             </popup>
             <update id="historyWindow.historyDetails" modules="historyBuild"  noProcess="1" />
         </button>

     When clicked, 
         i) a popup window (with a name of "historyWindow") will be created (if it hasn't been created already).
        ii) the historyBase will be used as the basic contents of this window
       iii) a <div> (or <span>) in historyBase with an id="historyDetails" will be appended to.
            In particular, the contents of historyBuild will be added to the contents of this <div>.

     Notes:
          * historyBuild is "built" by steps ii.1.c (above)
          * see step e, below, for details on the historyBase
          * you can specify style and other attributes in the <button>    
          * the noProcess="1" means "do not process historyBuild (for special tagnames) -- just add
            the contents as is to historyDetails"
          * the "retain=1" means "do NOT close this window when a new group is displayed"
          * the <title> is used as the title of the popup window, the <text> is used to
            specify the button's text. You can change them!
          * The contents of the popup are re-generated every time the button is clicked -- so
            the current contents of historyBuild are added to the historyDetails <div>
            of historyBase (any prior content of historyDetails is discarded).

    Technical summary:
            At the end of every round:
                 A summary of a round's results,  based on the html (and special tagnames) 
                 specified in the  history_oneRound moule, are added to the historyBuild internal module
            When the button is pushed, a popup is created and the historyBase module is used as content.
            The contents of historyBuild is then inserted into a specified location in this popup.

And, the modules used to specify the History ...

 e) The overall template for the History

      In the above, historyBase is the verall template within which the History is inserted.

      <module  id="historyBase" >

         Header information goes here. 
        
           <div id="historyDetails" />

        Footer information goes here

     </module>

  The key detail is you MUST specify a
           <div id="historyDetals" />
  The "header" and "footer" can be anything, and can include dSurvey's special tagnames.
  

 f) Specify one round

    Specify a history_oneRound: a module used to specify a round of information, for inclusion
    in the history.

    You can use the dSurvey special tagnames (such as <show>).
  
    Example:
  
      <module  id="history_oneRound" >
       <table>
         <tr>
            <td width="30%" >   <show var="prodCost_used." />  </td>
            <td width="5%"  >  </td>
            <td width="65" style="border-top: 1px solid black;" >   <show var="offers_used." />  </td>
         </tr>
      </module>

    Note the use of the "varname." notation -- this points to the "value of varname from the
    most recently completed round". 

    Fancier example: if each round can have several "tickets"

      <module  id="history_oneRound" >
       <table>
        <repeat value="itick=1,numtickets." >  
           <tr>
             <td width="30%" >   <show var="nowround." />  </td>
             <td width="30%" >   <show var="prodCost_used[itick]." />  </td>
             <td width="5%"  >  </td>
             <td width="65" >   <show var="offers_used[itick]." /> </td>
           </tr>
        </repeat> 
       </table>

      </module>

  Note that "numtickets." would be a variable that contains the number of "tickets",
  filled in by the participant in the most recently completed round, and "nowround."
  would be the round number of this most recently completed round.


II.3. Alternative: adding rows to a <table> 

  You can build a <table>, where each row (or rows) of the table contain information on a round's
  ticket(s).  To do this, you need to specify a <tbody> in a <table>, and append a module to it.

  For example, using the example specified above:

   <module  id="historyBase" >

   <table>
      <tbody id="historyDetails" >
       <tr>
          <th>The round </th><th>Cost</th><th>bid</th>
       </tr>

      <!-- <Tr> contianing the history will be inserted here -->

      </tbody>
    </table>
   </module>

  and ...

     <module  id="history_oneRound" >
         <tr>
            <td width="30%" >   <show var="prodCost_used." />  </td>
            <td width="5%"  >  </td>
            <td width="65" style="border-top: 1px solid black;" >   <show var="offers_used." />  </td>
         </tr>
     </module>


 or, if there are two tickets

   <module  id="history_oneRound" >
      <repeat do="itick=1,2" >
        <tr>
            <if value="itick eq 1">
                  <td  width="10%" rowspan="2">Round <show var="nowRound." /> </td>
            </if>
            <td width="30%" >   <show var="prodCost_used[itick]." />  </td>
            <td width="5%"  >  </td>
            <td width="55" style="border-top: 1px solid black;" >   <show var="offers_used[itick]." />  </td>
        </tr>
      <repeat>
   </module>



26 November 2010

