4 Nov 2008: Note on administrative programs -- on selecting a session.

The administrative pages in this directory share a common user interface.
In particular, they have a common means of asking the user (the administrator or participant) to select a
session to work with. This document describes this interface.

1) Introduction

In all cases, the first step is to call a startup function, using an onLoad event. That is,
as soon as the page loads, a function should be called.

This function will first  retrieve, using ajax calls (to the webserver) a list of current sessions.
This is followed by a call to the displaySessionsTable() function. 
displaySessionsTable() uses a number of elements to display various aspects of the interface.

In particular, elements with the following id attributes will be modified:
   sessionsTable, selectedSessionName,  selectedSessionDesc,  selectedSessionDetails, currentSessionName, saveButton


2) The startup

Let's start with a recommended, albeit basic, startup :
  function startup() {
      Get_File(getCurrentSessionsURL,'sessionList','retrieving list of sessions ','displaySessionsTable',0,1) ;
   }

Reiterating, this startup function will retrieve (from the server) a list of sessions, and then display each of the sessions (in a table)
as a "clickable" link. So, the typical sequence is:
  a) Browser loads the page
  b) After a short delay (while the browser communicates with the server) a list of sessions is displayed
  c) The user can
        Select a session
        View information on a selected session, 
        Switch his selection
       "submit" the selection -- do something with the session

These user actions can cause several changes to the display:
       a) In "descriptive"e elements, display the session's name, and a short description of the session
       b) In a "submit" element, display the session's name
          or
       c) and, depending on the i2 argument, a few other things. 

These display changes use several  "descriptive" and "submit" elements. Other than the calling the startup function,
specifying these elements are all you, the author of an administrative page, need to worry about.  

So if you are in a hurry, and don't need to take advantage of special tricks, you might be able to get away with skipping the next section.

2a) Using the Get_File function to display a list of sessions.

 Get_File is a generic dSurvey javascript function that will request a file (or other information from the server using "ajax" calls, 
 and then call another function when the server has sent its response.
 So, the following syntax is particular to this "display/chose a session" task. 

   Syntax:
        Get_File(getCurrentSessionsURL,'sessionList','retrieving list of sessions ','displaySessionsTable',i1,i2) ;
   where:
      getCurrentSessionsURL : a string used to request a list of sessions. 
      'sessionList'  : the "sessionList" variable is used to store an array of sessions. 
      'retrieving ... ' : a descriptive string. Optional
     'displaySessionsTable' : the name of the function to call. Required.
      i1          :  Set to 1 to display sessions. Set to  "11" to display  a list of suspended sessions (11 is used in unSuspendSession.htm)
      i2          :  Controls details of what is displayed when a session link is clicked:
                      0 : Add session name to the "submit" element.
                      1 :  On click of session, add several buttons that allow you to modify "session specific" parameter files.  This is used in modInput.htm
                      2 : Suppress suppress display of several descriptive elements. This is used in join.htm.

Now we are ready to discuss the various "descriptive" and "submit" elements.

3) The descriptive and submit elements.

displaySessionsTable(), and functions called by displaySessionsTable(), need to know where to display various things -- things like
the list of "clickable links".   These are elements, such as a TH, TBODY, TD, DIV, SPAN, or a TABLE. 
These are identified by an id attribute.

In particular, elements with the following id attributes will be modified:
   sessionsTable, selectedSessionName,  selectedSessionDesc,  selectedSessionDetails, currentSessionName, saveButton, and modifyButtons

The details:

  sessionsTable   
         Where to write the list of "clickable links" to sessions. 
         Each clickable link will be in its own table cell (in its own <td>).
         So pay attention to this example...
              Example:  <table id="sessionsTable" border="1" cellpadding="3"> <tbody> </tbody></table>

  saveButton   
         The "submit" element discussed above. 
         This should be a "clickable" element, such as a "button", that will call a function that does the actual
          work (say, that allows a participant to join a session).
          So, it should have 3 attributes:
              i) id="saveButton". This is REQUIRED!
             ii) value="Description: xxxx "
                      What is displayed.  If not specified, the currently selected session's name will be displayed.
                      If specified with a ": ", everything after the colon will be replaced with the session's name.
                      Note that this saveButton is modified WHENEVER a clickable-link is clicked (that is, when a session is selected)
            iii) onClick="something"
                      Where the "something" is whatever you want to do once the user wishes to do something with the selected session            
                Example:
                      <input type="button" style="margin-left:3%"  
                              id="saveButton" 
                              value="Click to join session: not speciifed" 
                              onClick="joinSession()" 
                       />

  selectedSessionName 
         Location to display a clickable-link of the  name of the currently selected session.
         When clicked, the contents of this session's descriptor file will be displayed in the selectedSessionDetails area 

  selectedSessionDesc   
         Location to display a description of the currently selected session.

         Example: 
             <table border="1" style="margin-left:10%"><tbody>
                 <tr><td colspan="2"> The currently selected session ... </td></tr>
                 <tr><Th><span id="selectedSessionName" > </span></th>
                <Td><span id="selectedSessionDesc" > </span> </td>
             </tr>
             </tbody></table>

  selectedSessionDetails  
       Location to display a table listing the parameter values specified in the session descriptor file.
       Each variable is displayed as a <tr> (a table row).  
       So pay attention to this example ...
       Example:
           <table  border="1" style="margin-left:20%"><tbody id="sessionDetails"> </tbody></table>

  currentSessionName 
       An element used to support "double click to submit".
       Double click to submit means that double clicking on the "clickable link to a session" will "submit" the session name.
       Its a shortcut for the clicking on the clickable link, and then moving the mouse to the "submit" button and clicking it.
       It can also be used as an additional place to display the name of the currently selected session.
    
       Example (note use of the display:none):
         <input style="display:none" readonly type="text" id="currentSessionName" value="0" >


  modifyButtons:
        Used when i2 = 1. In particular, by  modInput.htm.
        A table where buttons will be created. These buttons will display tables with values of parameter files, that can be edited.
        Example:
           <table bgcolor="#efeffe" align="center"><tbody id="modifyButtons"></tbody></table>


4) Some technical notes:

  a) See svyAdmins.js for the displaySessionsTable() function, and the function it calls.
  b) The storage of session desciptor files, and other files, is server dependent.

 
