% \iffalse
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Eq2DB.sty package,             2001-9-01             %%
%% Copyright (C) 2001  D. P. Story                      %%
%%   dpstory@uakron.edu                                 %%
%%                                                      %%
%% This program can redistributed and/or modified under %%
%% the terms of the LaTeX Project Public License        %%
%% Distributed from CTAN archives in directory          %%
%% macros/latex/base/lppl.txt; either version 1 of the  %%
%% License, or (at your option) any later version.      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{eq2db}
%<package> [2003/12/06 v1.5 Save Exerquiz results to a Database, Email, or text file (dps)]
%<*driver>
\documentclass{ltxdoc}
\usepackage[dviwindo,colorlinks,hyperindex]{hyperref}
\makeatletter
\renewcommand{\paragraph}{\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\makeatother
\pdfstringdefDisableCommands{\let\\\textbackslash}%
\EnableCrossrefs \CodelineIndex
\begin{document}
  \GetFileInfo{eq2db.sty}
  \title{The \texttt{eq2db} Package}
  \author{D. P. Story\\
    Email: \texttt{dpstory@uakron.edu}}
  \date{processed \today}
  \maketitle
  \tableofcontents
  \let\Email\texttt
  \DocInput{eq2db.dtx}
  \PrintIndex
\end{document}
%</driver>
% \fi
%    \section{Introduction}
% This package is meant to be used with the \textsf{exerquiz} package, one
% of the components of the \textbf{{Acro\TeX} eDucation Bundle}.
% This package is used to customize \textsf{exerquiz} to save
% results of the \texttt{quiz} environment to a database.
%
% Currently, there are two options, \texttt{eqRecord} and \texttt{custom}.
% The first option is a simple \textsf{ASP} script that takes takes some
% \textsf{exerquiz} data and saves it to a database. The \texttt{custom}
% option is a hook for other developers to use this package and its macros.
%    \section{Package Options}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    \begin{macrocode}
\let\eq@optioncode = \@empty
%    \end{macrocode}
%    \begin{macro}{eqRecord}
% An option to store exerquiz data in a database, see \hyperref[eqrecord]{eqRecord}.
%    \begin{macrocode}
\DeclareOption{eqRecord}{\def\eq@optioncode{\input{eqrecord.def}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{eqEmail}
% An option to email exerquiz data to an instructor, see \hyperref[eqemail]{eqEmail}.
%    \begin{macrocode}
\DeclareOption{eqEmail}{\def\eq@optioncode{\input{eqemail.def}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{eqText}
% Save exerquiz data to a tab-delimited text field, see \hyperref[eqtext]{eqText}.
%    \begin{macrocode}
\DeclareOption{eqText}{\def\eq@optioncode{\input{eqtext.def}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{eqText}
%    \begin{macrocode}
% Private option for TAOAS
\DeclareOption{taoas}{\def\eq@optioncode{\input{taoas.def}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{custom}
% A option so developers can create their own custom set up for their own script.
%    \begin{macrocode}
\DeclareOption{custom}{\def\eq@optioncode{\input{eq2dbcus.def}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{tagged}
% The exerquiz quiz results are put into a quasi-XML format.
%    \begin{macrocode}
\DeclareOption{tagged}{\let\eqdb@tagged=y}
\let\eqdb@tagged=n
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
%    \begin{macrocode}
\RequirePackage{exerquiz}
%    \end{macrocode}
%    \section{Main Code}
% This code creates a way of hiding text fields. These fields are typically
% used to hold data that is sent to server-side script on submission.
%
%\medskip\noindent
% This is a token list to hold the list of hidden fields to be inserted into
% the document. We also provide a command for initializing the token list.
%    \begin{macrocode}
\newtoks\addtohidden \addtohidden={}
%    \end{macrocode}
%\medskip\noindent
% The macro \cs{eq@addHiddenTextFields} will be used to hold the accumulated
% hidden fields as we add another hidden field to the token list.
%    \begin{macrocode}
\def\eq@addHiddenTextFields{}
%    \end{macrocode}
%    \begin{macro}{\addHiddenTextField}
% This macro adds a new hidden text field to the token list
% \cs{addtohidden}. The command takes three parameters,
% the first of which is optional. The command
% \cs{hiddenTextField} actually creates the text field.
%\paragraph*{Parameters:}
%\begin{verbatim}
%[#1] = parameter to modify the parameters of the text field
% #2  = field name of the field being constructed
% #3  = default value of the field
%\end{verbatim}
%    \begin{macrocode}
\renewcommand\addHiddenTextField[3][]{%
    \addtohidden=\expandafter{\eq@addHiddenTextFields
        \llap{\hiddenTextField[#1]{#2}{#3}}}%
    \edef\eq@addHiddenTextFields{\the\addtohidden}%
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\hiddenTextField}
%
% This command actually creates a hidden text field \texttt{10bp} wide
% and \texttt{10bp} high. It is used by \cs{addHiddenTextField}, but can
% be used be the macro author as well. The command takes three parameters,
% the first of which is optional.
%\paragraph*{Parameters:}
%\begin{verbatim}
%[#1] = parameter to modify the parameters of the text field
% #2  = field name of the field being constructed
% #3  = default value of the field
%\end{verbatim}
%    \begin{macrocode}
\newcommand\hiddenTextField[3][]{\textField
    [\DV{#3}\V{#3}\F2#1]{#2}{10bp}{10bp}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\populateHiddenField}
% Command for populating the value of a (hidden) text field at run time. This is executed
% by the `End Quiz' button.
%\paragraph*{Parameters:}
%\begin{verbatim}
% #1 = field name of the field
% #2  = field value. Strings need to be enclosed in double quotes
%\end{verbatim}
%    \begin{macrocode}
\newtoks\populatehiddenfields \populatehiddenfields={}
\def\eq@populateHiddenFields{}
\def\eq@initializepopulate{\gdef\eq@populateHiddenFields{}%
    \global\populatehiddenfields={}}
\renewcommand\populateHiddenField[2]{%
    \populatehiddenfields=\expandafter{\eq@populateHiddenFields
        this.getField("#1").value = #2;\jsR\jsT\jsT}%
    \edef\eq@populateHiddenFields{\the\populatehiddenfields}%
}
\def\eq@clearHiddenFields{\global\let\eq@populateHiddenFields=\@empty
    \global\let\eq@addHiddenTextFields=\@empty
}
%    \end{macrocode}
%    \end{macro}
% These hidden fields are created under the `End Quiz' button or link, and are populated
% when the user clicks on `End Quiz'. The following flag, set to \texttt{n} will be set
% to \texttt{y} when the fields are created, in this way, we can avoid creating them
% more than once.
%    \begin{macrocode}
\let\basicFieldsSet=n
%    \end{macrocode}
% Now input the chosen option.
%    \begin{macrocode}
%\input{\eq@optioncode}
\eq@optioncode
% \section{Tagged Responses}
% An option for this package is \texttt{tagged}, when the document
% author takes this option, the quiz responses are sent out in an
% XML-like encoding.
%
% The JavaScript function \texttt{gatherTaggedQuizData} builds up a
% "tagged" response string, which contains various pieces of
% information about the quiz results.
%    \begin{macrocode}
\ifx\eqdb@tagged y%
\begin{insDLJS}[gatherTaggedQuizData]{eqtagged}{Eq2db: Gather Tagged Data}
function gatherTaggedQuizData(currQuiz,filename,nQuestions) {
    var isGrouped = false;
    var cResponses = "<results id=\""+currQuiz+"\" file=\""+filename+"\" n=\""+nQuestions+"\">";
    var eqCredit;
    for ( var i=1; i <= nQuestions; i++)
    {
        if (typeof RightWrong[i] == "undefined") RightWrong[i] = 0;
        if (typeof Responses[i] == "undefined") { Responses[i] = ""; eqCredit=0; }
        if ( ProbDist[i] == undefined )  ProbDist[i] = 0;
        if (typeof ProbType[i] == "undefined") ProbType[i] = "na";
        else
            eqCredit = (typeof ProbValue[i] == "number") ? 0 : ( ProbValue[i][0]==0 )? ProbValue[i][2] : ProbDist[i];
        isGrouped = ( (typeof ProbValue[i] == "object") &&  (ProbValue[i][0]==1) ) ? true : false;
        if (isGrouped ) {
            var f = this.getField("grpobj."+currQuiz+"."+i);
            var l = f.getArray().length;
            RightWrong[i].length = l+1;
            Responses[i].length = l+1;
        }
        cResponses += "<question n=\"" + i + "\" type=\""
            + aPointType[i][1]+"\"";
        cResponses += " ptype=\""+ProbType[i]+"\"";
        if (isGrouped) {
            cResponses += " points=\""+ProbValue[i][2] + "\"";
            cResponses += " credit=\""+eqCredit + "\"";
            var xmlResp="";
            for ( var j = 1; j < RightWrong[i].length; j++) {
                if ( RightWrong[i][j] == undefined ) RightWrong[i][j] = 0;
                xmlResp += ( Responses[i][j] == undefined ) ? "<grpvalue></grpvalue>" : "<grpvalue>"+Responses[i][j]+"</grpvalue>";
            }
            cResponses += " correct=\"["+RightWrong[i].slice(1)+"]\">";
            cResponses += "<value>"+xmlResp+"</value>";
        } else {
            cResponses += " points=\""+aPointType[i][0] + "\"";
            cResponses += " credit=\""+eqCredit + "\"";
            cResponses += " correct=\""+RightWrong[i]+"\">";
            cResponses += "<value>"+Responses[i]+"</value>";
        }
        cResponses += "</question>";
    }
    cResponses += "</results>";
    return cResponses;
}
\end{insDLJS}
\fi
%</package>
%    \end{macrocode}
% \section{eqRecord}\label{eqrecord}
% Save quiz results to a database. The \texttt{eqRecord} option is meant to
% be used with the ASP code \textsf{eqRecord.asp}.
%
% The form the macro \cs{eqSubmit} is
%\begin{verbatim}
%\eqSubmit{http://..../eqRecord.asp\#FDF}{database_name}{table_name}
%\end{verbatim}
% The first parameter is the URL to the \textsf{eqRecord.asp} script. The second is the
% DNS of the database. The third parameter is the name of the table into which the
% quiz data is to be stored.
% For example,
%\begin{verbatim}
%\eqSubmit{http://localhost/scripts/eqRecord.asp\#FDF}{eqQuiz}{Math101}
%\end{verbatim}
% As with \textsf{eqRecord}, the first parameter of the \texttt{quiz} environment is
% the name of the quiz begin taken.
%\begin{verbatim}
%\begin{quiz}*{Quiz1}
%...
%\end{quiz}
%\end{verbatim}
%    \begin{macrocode}
%<*eqrecord>
%    \end{macrocode}
%    \begin{macro}{\eq@insertHiddenFields}
% Create and add the hidden text fields for this option. The macro
% \cs{eq@insertHiddenFields} is defined in \textsf{exerquiz} as
% empty. Now we redefine it for the purpose of inserting hidden text
% fields.
%    \begin{macrocode}
\def\eq@insertHiddenFields{%
    \ifx\basicFieldsSet n
        \addHiddenTextField{dbName}{}%
        \addHiddenTextField{dbTable}{}%
        \addHiddenTextField{quizName}{}%
        \global\let\basicFieldsSet=y
    \fi
    \addHiddenTextField{\curr@quiz.numQuestions}{\thequestionno}%
    \addHiddenTextField{\curr@quiz.numCorrect}{}%
    \addHiddenTextField{\curr@quiz.Responses}{}%
    \eq@addHiddenTextFields
    \eq@clearHiddenFields
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\eq@URL}
% The JavaScript of the `End Quiz' button has a command \cs{eq@submitURL}, which has
% an empty definition for quizzes that are not to be submitted.  We define this
% macro appropriately. We populate each of the hidden fields and submit.
%    \begin{macrocode}
\def\eq@submitURL{%
    this.getField("dbName").value = "\db@Name";\jsR\jsT\jsT
    this.getField("dbTable").value = "\db@Table";\jsR\jsT\jsT
    this.getField("quizName").value = "\curr@quiz";\jsR\jsT\jsT
    this.getField("\curr@quiz.numCorrect").value = Score;\jsR\jsT\jsT
    var aPointType = new Array(\aPointType);\jsR\jsT\jsT
\ifx\eqdb@tagged y%
    var cResponses = gatherTaggedQuizData("\currQuiz","\jobname.pdf",\thequestionno);\jsR\jsT\jsT
\else
    var cResponses = Responses.toString().substr(1);\jsR\jsT\jsT
\fi
    this.getField("\curr@quiz.Responses").value = cResponses;\jsR\jsT\jsT
    \eq@populateHiddenFields
    var aSubmitFields = new Array("\curr@quiz", "IdInfo",
        "dbName", "dbTable", "quizName");\jsR\jsT\jsT
    \priorSubmitQuiz
    this.submitForm(\eq@CGI, true, false, aSubmitFields);\jsR\jsT\jsT
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
%</eqrecord>
%    \end{macrocode}
% \section{eqEmail}\label{eqemail}
%    \begin{macrocode}
%<*eqemail>
%    \end{macrocode}
% Report results via e-mail. The \texttt{eqEmail} option is meant to
% be used with the ASP code \textsf{eqEmail.asp}. When the user
% submits his/her quiz, \textsf{eqEmail} builds an e-mail message
% the body of which are the quiz results, and sends it to the
% instructor.
%
% The form the macro \cs{eqSubmit} is\vskip6pt
%\begin{verbatim}
%\eqSubmit{http://..../eqEmail.asp\#FDF}{instr@someedu.edu}{course}
%\end{verbatim}
% The first parameter is the URL to the \textsf{eqEmail.asp} script. The second is the
% e-mail address to which the quiz results is to be sent. The third parameter is the
% course name.
% For example,
%\begin{verbatim}
%\eqSubmit{http://localhost/scripts/eqEmail.asp\#FDF}{dpstory@uakron.edu}{Math101}
%\end{verbatim}
% As with \textsf{eqRecord}, the first parameter of the \texttt{quiz} environment is
% the name of the quiz begin taken.
%\begin{verbatim}
%\begin{quiz}*{Quiz1}
%...
%\end{quiz}
%\end{verbatim}
%    \begin{macro}{\eq@insertHiddenFields}
% Create and add the hidden text fields for this option. The macro
% \cs{eq@insertHiddenFields} is defined in \textsf{exerquiz} as
% empty. Now we redefine it for the purpose of inserting hidden text
% fields.
%    \begin{macrocode}
\def\eq@insertHiddenFields{%
    \ifx\basicFieldsSet n%
        \addHiddenTextField{mailTo}{}%
        \addHiddenTextField{courseName}{}%
        \addHiddenTextField{quizName}{}%
        \global\let\basicFieldsSet=y%
    \fi
    \addHiddenTextField{\curr@quiz.numQuestions}{\thequestionno}%
    \addHiddenTextField{\curr@quiz.numCorrect}{}%
    \addHiddenTextField{\curr@quiz.Responses}{}%
    \eq@addHiddenTextFields
    \eq@clearHiddenFields
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\eq@submitURL}
% The JavaScript of the `End Quiz' button has a command \cs{eq@submitURL}, which has
% an empty definition for quizzes that are not to be submitted.  We define this
% macro appropriately. We populate each of the hidden fields and submit.
%    \begin{macrocode}
\def\eq@submitURL{%
    this.getField("mailTo").value = "\db@Name";\jsR\jsT\jsT
    this.getField("courseName").value = "\db@Table";\jsR\jsT\jsT
    this.getField("quizName").value = "\curr@quiz";\jsR\jsT\jsT
    this.getField("\curr@quiz.numCorrect").value = Score;\jsR\jsT\jsT
    var aPointType = new Array(\aPointType);\jsR\jsT\jsT
\ifx\eqdb@tagged y%
    var cResponses = gatherTaggedQuizData("\currQuiz","\jobname.pdf",\thequestionno);\jsR\jsT\jsT
\else
    var cResponses = Responses.toString().substr(1);\jsR\jsT\jsT
\fi
    this.getField("\curr@quiz.Responses").value = cResponses;\jsR\jsT\jsT
    \eq@populateHiddenFields
    var aSubmitFields = new Array("\curr@quiz", "IdInfo",
        "mailTo", "courseName", "quizName");\jsR\jsT\jsT
    \priorSubmitQuiz
    this.submitForm(\eq@CGI, true, false, aSubmitFields);\jsR\jsT\jsT
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
%</eqemail>
%    \end{macrocode}
% \section{eqText}\label{eqtext}
%    \begin{macrocode}
%<*eqtext>
%    \end{macrocode}
% Record the quiz results in a text tab delimited text file.
%
% The form the macro \cs{eqSubmit} is\vskip6pt
%\begin{verbatim}
%\eqSubmit{http://..../eqText.asp\#FDF}{<path to text file>}{<course name>}
%\end{verbatim}
% The first parameter is the URL to the \textsf{eqText.asp} script. The second is the
% path on the server to where the text file is located. The third parameter is the
% course name.
% For example,
%\begin{verbatim}
%\eqSubmit{http://localhost/scripts/eqText.asp\#FDF}{c:/Inetpub/DB/qResults.txt}{Math101}
%\end{verbatim}
% As with \textsf{eqRecord}, the first parameter of the \texttt{quiz} environment is
% the name of the quiz begin taken.
%\begin{verbatim}
%\begin{quiz}*{Quiz1}
%...
%\end{quiz}
%\end{verbatim}
%    \begin{macro}{\eq@insertHiddenFields}
% Create and add the hidden text fields for this option. The macro
% \cs{eq@insertHiddenFields} is defined in \textsf{exerquiz} as
% empty. Now we redefine it for the purpose of inserting hidden text
% fields.
%    \begin{macrocode}
\def\eq@insertHiddenFields{%
    \ifx\basicFieldsSet n%
        \addHiddenTextField{pathToTxtFile}{}%
        \addHiddenTextField{courseName}{}%
        \addHiddenTextField{quizName}{}%
        \global\let\basicFieldsSet=y%
    \fi
    \addHiddenTextField{\curr@quiz.numQuestions}{\thequestionno}%
    \addHiddenTextField{\curr@quiz.numCorrect}{}%
    \addHiddenTextField{\curr@quiz.Responses}{}%
    \eq@addHiddenTextFields
    \eq@clearHiddenFields
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\eq@submitURL}
% The JavaScript of the `End Quiz' button has a command \cs{eq@submitURL}, which has
% an empty definition for quizzes that are not to be submitted.  We define this
% macro appropriately. We populate each of the hidden fields and submit.
%    \begin{macrocode}
\def\eq@submitURL{%
    this.getField("pathToTxtFile").value = "\db@Name";\jsR\jsT\jsT
    this.getField("courseName").value = "\db@Table";\jsR\jsT\jsT
    this.getField("quizName").value = "\curr@quiz";\jsR\jsT\jsT
    this.getField("\curr@quiz.numCorrect").value = Score;\jsR\jsT\jsT
    var aPointType = new Array(\aPointType);\jsR\jsT\jsT
\ifx\eqdb@tagged y%
    var cResponses = gatherTaggedQuizData("\currQuiz","\jobname.pdf",\thequestionno);\jsR\jsT\jsT
\else
    var cResponses = Responses.toString().substr(1);\jsR\jsT\jsT
\fi
    this.getField("\curr@quiz.Responses").value = cResponses;\jsR\jsT\jsT
    \eq@populateHiddenFields
    var aSubmitFields = new Array("\curr@quiz", "IdInfo",
        "pathToTxtFile", "courseName", "quizName");\jsR\jsT\jsT
    \priorSubmitQuiz
    this.submitForm(\eq@CGI, true, false, aSubmitFields);\jsR\jsT\jsT
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
%</eqtext>
%    \end{macrocode}
% \section{TAOAS}
%  TAOAS (The AcroTeX Online Assessment System) is an online quiz system under development.
% It is not publicly available.
%    \begin{macrocode}
%<*taoas>
%    \end{macrocode}
%    \begin{macro}{\eq@insertHiddenFields}
% Create and add the hidden text fields for this option. The macro
% \cs{eq@insertHiddenFields} is defined in \textsf{exerquiz} as
% empty. Now we redefine it for the purpose of inserting hidden text
% fields.
%    \begin{macrocode}
\def\eq@insertHiddenFields{%
    \ifx\basicFieldsSet n%
        \addHiddenTextField{dbName}{}%
        \addHiddenTextField{dbTable}{}%
        \addHiddenTextField{quizName}{}%
        \addHiddenTextField{UserValid}{false}%
        \addHiddenTextField{EMPLID}{}%
        \addHiddenTextField{randomID}{}%
        \addHiddenTextField{fileName}{\jobname}%
        \ifeq@noquizsolutions
            \addHiddenTextField{requestSolutions}{false}%
        \else
            \addHiddenTextField{requestSolutions}{true}%
        \fi
        \global\let\basicFieldsSet=y
    \fi
    \addHiddenTextField{\curr@quiz.numCorrect}{}%
    \addHiddenTextField{\curr@quiz.numQuestions}{\thequestionno}%
    \addHiddenTextField{\curr@quiz.ptScore}{}%
    \addHiddenTextField{\curr@quiz.nPointTotal}{\theeqpointvalue}
    \addHiddenTextField{\curr@quiz.Responses}{}%
    \eq@addHiddenTextFields
    \eq@clearHiddenFields
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\eq@submitURL}
% The JavaScript of the `End Quiz' button has a command \cs{eq@submitURL}, which has
% an empty definition for quizzes that are not to be submitted.  We define this
% macro appropriately. We populate each of the hidden fields and submit.
%    \begin{macrocode}
\def\eq@submitURL{%
    this.getField("dbName").value = dbName;\jsR\jsT\jsT
    this.getField("dbTable").value = "\db@Table";\jsR\jsT\jsT
    this.getField("quizName").value = "\curr@quiz";\jsR\jsT\jsT
    this.getField("\curr@quiz.numCorrect").value = Score;\jsR\jsT\jsT
    this.getField("\curr@quiz.ptScore").value = ptScore;\jsR\jsT\jsT
    var aPointType = new Array(\aPointType);\jsR\jsT\jsT
\ifx\eqdb@tagged y%
    var cResponses = gatherTaggedQuizData("\currQuiz","\jobname.pdf",\thequestionno);\jsR\jsT\jsT
\else
    var cResponses = Responses.toString().substr(1);\jsR\jsT\jsT
\fi
    this.getField("\curr@quiz.Responses").value = cResponses;\jsR\jsT\jsT
    \eq@populateHiddenFields
    var aSubmitFields = new Array("\curr@quiz", "IdInfo",
        "randomID", "dbName", "dbTable", "quizName", "fileName", "requestSolutions");\jsR\jsT\jsT
    \priorSubmitQuiz
    this.submitForm(submitURL, true, false, aSubmitFields);\jsR\jsT\jsT
}
%    \end{macrocode}
%    \end{macro}
%    \begin{macrocode}
%</taoas>
%    \end{macrocode}
\endinput