\RequirePackage[use=usebw]{spdef} \documentclass{article} \usepackage[fleqn]{amsmath} \usepackage{graphicx,longtable,array} %\usepackage[dvipsone,designvi,tight]{web} % dvipsone, dvips, pdftex, dvipdfm \usepackage[designv,latextoc,forcolorpaper,centertitlepage]{web} \usepackage[nodljs,execJS]{exerquiz} %,preview \usepackage[altbullet]{lucidbry} \usepackage{pifont} \usepackage{fancyvrb} %\usepackage{calc} \usepackage[active]{srcltx} %\setlongtables \def\AEBBook{\textsl{{Acro\!\TeX} eDucation System Tools: {\LaTeX} for interactive PDF documents}} \hyphenation{Java-Script} \def\AcroT{Acro\!\TeX}\def\cAcroT{{\textcolor{blue}{\AcroT}}} \def\AcroEB{\AcroT{} eDucation Bundle}\def\cAcroEB{\textcolor{blue}{\AcroEB}} \def\AcroB{\AcroT{} Bundle}\def\cAcroB{\textcolor{blue}{\AcroB}} \def\bUrl{http://www.math.uakron.edu/~dpstory} % Colors \ifusebw \universityColor{black} \sectionColor{black} \quesNumColor{black} \tocColor{black} \fi \makeatletter \ifusebw \def\@linkcolor{black} \def\@citecolor{black} \def\@filecolor{black} \def\@urlcolor{black} \fi \let\bslash=\@backslashchar %\renewcommand{\paragraph}{\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} \renewcommand{\paragraph} {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt} {\normalfont\normalsize\bfseries}} \renewcommand{\subparagraph} {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}% {\normalfont\normalsize\bfseries}} \def\FitItIn{\eq@fititin} \def\endredpoint{\FitItIn{{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleleft$}}} \def\chgCurrLblName#1{\def\@currentlabelname{#1}} \makeatother \hypersetup{linktocpage} \def\cs#1{\texttt{\bslash#1}} \newcommand\redpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi \vskip\medskipamount\noindent \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleright$}} \newcommand\handpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi \vskip\medskipamount\noindent \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{blue}\fi\ding{042}}} \def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} \def\meta#1{\textit{\texttt{#1}}} \let\pkg\textsf \let\env\texttt \let\opt\texttt \let\app\textsf \def\AEB{\textsf{AeB}} \def\AcroTeX{Acro\!\TeX} \def\HTML{HTML}\def\FDF{FDF} \def\PDF{PDF}\def\URL{URL} \let\amtIndent\leftmargini \def\bNH{\begin{NoHyper}}\def\eNH{\end{NoHyper}} \def\nhnameref#1{\bNH\nameref{#1}\eNH} \def\nhNameref#1{\bNH\Nameref{#1}\eNH} \def\nhurl#1{\bNH\url{#1}\eNH} \def\grayV#1{\textcolor{gray}{#1}} \def\darg#1{\{#1\}} \def\parboxValign{t} \renewcommand*{\backrefalt}[4]{% See page\ifcase #1\or ~#2.\else s~#2.\fi } \newenvironment{aebQuote} {\list{}{\leftmargin\amtIndent}% \item\relax}{\endlist} \newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{% \raisebox{.5\baselineskip+#1}{% \expandafter\parbox\expandafter[\parboxValign]% {\marginparwidth}{\aebbkFmtMp#2}}}} \def\aebbkFmtMp{\kern0pt\itshape\small \ifusebw\color{gray}\else\color{blue}\fi \raggedleft\hspace{0pt}} \def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}% \kern-.6em \hbox{$\mathcal S$}}$} \title{\texorpdfstring{Acro\!\TeX}{AcroTeX} eDucation Bundle\texorpdfstring{\\}{: } The \texorpdfstring{\pkg{eq2db}}{eq2db} Package} \author{D. P. Story} \subject{Manual of Usage for eq2db Distribution} \keywords{AcroTeX, LaTeX, PDF, ASP, Database, Email, quizzes} \university{{\AcroT} Software Development Team} %\university{THE UNIVERSITY OF AKRON\\ % Theoretical and Applied Mathematics} \email{dpstory@acrotex.net} \version{2.0} \copyrightyears{1999-\the\year} % \def\OpenToHere{\OpenAction{\JS{this.gotoNamedDest("Here")}}} % \def\OpenHere{\hypertarget{Here}{\strut}}\OpenToHere \reversemarginpar \makeatletter \let\web@copyright\@gobble \let\web@revision\@gobble \renewcommand\webdirectory {% \par\ifeqforpaper\else\minimumskip\fi\vspace{\stretch{1}}% \begin{flushleft}\textbf{\large\web@directory}% \vspace{-3pt} \begin{itemize}\setlength{\itemsep}{-3pt}% \bfseries \item \leavevmode\hyperlink{webtoc}{\web@toc}% \item Begin \hyperlink{\web@Start.1}{Documentation} \item \href{aeb_man.pdf}{\AcroEB} \item \textsf{\href{eformman.pdf}{eForm}} Support \end{itemize} \end{flushleft} } \def\maketitle@trailer@ul{\web@copyright\ \copyright\ \webcopyrightyears\ \webversion} \def\maketitle@trailer@ll{\web@revision\ \@date} \def\maketitle@trailer@ur{\url{http://www.acrotex.net}} \def\maketitle@trailer@lr{\href{mailto:\webemail}{\webemail}} %\renewcommand\titlepageTrailer %{% % \web@copyright\ \copyright\ \webcopyrightyears\ \webversion % \hfill\url{http://www.acrotex.net}\\ % \web@revision\ \@date \hfill\href{mailto:\webemail}{\webemail} %} \makeatother \newcounter{exampleno} \def\theexampleno{\arabic{exampleno}} \newcommand\Example{\refstepcounter{exampleno}% \paragraph*{Example.}} \begin{execJS}{execjs} aebTrustedFunctions(this, aebAddWatermarkFromFile, { bOnTop: false, cDIPath: "C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf" }) aebTrustedFunctions(this, aebSaveAs, "Save") \end{execJS} \begin{document} \maketitle\tableofcontents \section{Introduction} \emph{Short Summary:} Converts a self-contained \pkg{exerquiz} \env{quiz} to one that is submitted to a server-side script.\endredpoint \medskip The \pkg{eq2eb} package is meant to be used with the \pkg{exerquiz} package, one of the components of the \textbf{{Acro\!\TeX} eDucation Bundle} (\texttt{ctan.org/pkg/acrotex}). The package redefines the `End Quiz' button (of the \env{quiz} environment) appropriately so that when the user clicks the `End Quiz' control, the results of the quiz are sent to a server-side script. The \pkg{eq2db} Package has six options: \begin{questions} \item \texttt{\hyperref[eqRecordOption]{eqRecord}}: Save quiz data to a database, such as Microsoft Access. (Supported for FDF submission.) \item \texttt{\hyperref[eqEmailOption]{eqEmail}}: Email quiz data to the instructor. (Supported for FDF and HTML submission.) \item \texttt{\hyperref[eqTextOption]{eqText}}: Save quiz data to a tab-delimited text file. Can then be opened and analyzed using Microsoft Excel. (Supported for FDF and HTML submission.) \item \texttt{\hyperref[customOption]{custom}}: A hook for developers to use \texttt{eq2db} with their own script. \item \texttt{\hyperref[taggedOption]{tagged}}: Write quiz data in an XML-like data stream. \item \texttt{submitAs=\meta{\upshape FDF|HTML|XML}}: (new in v2.0) The \texttt{submitAs} option allows the document author to submit as FDF, HTML, or XML. The scripts provided by this package are designed FDF submittal and HTML submittal. Scripts for an XML submittal type are left as an exercise. With regard to HTML submission, read Section~\ref{s:IntroHTMLSub} below. \end{questions} For FDF submittal, accompanying each of the first three options listed above is a server-side script. These are ASP pages written with \app{VBScript}. A \app{Windows} server running Microsoft IIS is required; Adobe \textsl{FDF Toolkit} is also required to be installed on the server. \subsection{Introduction to HTML submission}\label{s:IntroHTMLSub} My upcoming book (if it ever comes), \AEBBook~\cite{book:AEBB}, has a rather extensive chapter titled ``Server-side Scripting and the \pkg{eq2db} Package.'' In the course of writing that chapter, I decided to throw in the towel on the \textsl{FDF Toolkit}, the mainstay for FDF submission, and to look at HTML submission. Yes, PDF form data can be submitted as HTML form data. As result, I wrote a number of scripts for general purpose PDF form documents and for quiz documents (see Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2}); identical functioning scripts were written for the \app{Windows} server-platform using \app{ASP} and \app{VBScript} and for the \app{Linux} server-platform using \app{PHP}. \paragraph*{{\AEB} demonstration websites.}\label{para:SSDemoPages}\leavevmode These two websites were created to illustrate server-side concepts and examples brought up in the book. The links on these pages demonstrate the two sets of scripts listed in Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2}, and much more. \begin{quote} \nhurl{http://faculty.nwfsc.edu/web/math/storyd/dps/} \end{quote} The above Web page is on a \app{Windows} server hosted by Northwest Florida State College (NWFSC). The server-side script is written as ASP pages using VBScript. \begin{quote} \nhurl{http://www.acrotex.net/dps/} \end{quote} This Web page is on a \app{Linux} server hosted by {\AcroTeX.Net}. The server-side script is written with PHP. A parallel development of all scripts is maintained for these two server platforms. You are invited to navigate your Web browser to each of these {\URL}s and experience forms submission from a {\PDF} document. \section{The Distribution and Requirements} The \pkg{eq2db} Package is distributed with the following files: \begin{questions} \item \texttt{eq2dbman.pdf}: This document, the documentation for the {\LaTeX} package \pkg{eq2db} and its related files. \item \texttt{eq2db.dtx} and \texttt{eq2db.ins}: The {\LaTeX} package with its installation file. \item \textsf{eqRecord.asp}: An \textsf{ASP} script for saving \pkg{exerquiz} quizzes to a data\-base. \item \textsf{eqEmail.asp}: An \textsf{ASP} script for forwarding \pkg{exerquiz} quizzes via e-mail. \item \textsf{eqText.asp}: An \textsf{ASP} script for saving \pkg{exerquiz} quizzes to a tab-delimited file. \item \texttt{quiz1.tex}, \texttt{quiz2.tex}, \texttt{quiz3.tex}, \texttt{quiz4.tex} (quizzes~1 and~2 demo use the \texttt{eqRecord} option; \texttt{quiz3} demos \texttt{eqEmail}, and \texttt{quiz4} demos \texttt{eqText}.) \item \texttt{eqQuiz.mdb}: A Microsoft Access 2000 database is used with the demostration files \texttt{quiz1.tex} and \texttt{quiz2.tex}. \end{questions} The \pkg{eq2db} package requires the \pkg{exerquiz} package to create online quizzes and to create supporting buttons and text fields. The \pkg{exerquiz} package, in turn, assumes a number of packages; a listing of these can be found in the documentation for the \AcroEB. \section{The \texttt{eqRecord} option}\label{eqRecordOption} In this section we describe how to create an online quiz that is to be submitted to the server-side script \app{eqRecord.asp}\footnote{The script \textsf{eqRecord.asp} comes with absolutely \emph{no guarantees}. Extensive testing should be made on your own system to assure yourself script is reliable enough to use in practice. Feel free to modify the script to suite your needs.}. For this option, quiz results are saved to a database. The \opt{eqRecord} option and its corresponding script \app{eqRecord.asp} require that Adobe's \textsf{FDF Toolkit} is installed on your \app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}. \redpoint \texttt{quiz1.tex} and \texttt{quiz2.tex} are the demo files for this option. \paragraph*{In the preamble.} The steps to create a quiz to be submitted to \textsf{eqRecord} are simple enough. First, the preamble of your document should look something like this: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()] \documentclass{article} \usepackage[designi]{web} \usepackage{exerquiz} \usepackage[eqRecord!grayV(,tagged)]{eq2db} \end{Verbatim} You may have other packages loaded, as well as other options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the following sense: If the \pkg{eq2db} package is not loaded, then an \pkg{exerquiz} \env{quiz} is self-contained, that is, it is not submitted to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are submitted to a server-side script. The \opt{tagged} option may be optionally included in the option list of \pkg{eq2db}, shown in gray. \paragraph*{In the body.} Next, you write your \pkg{exerquiz} \env{quiz}: \begin{equation} \begin{minipage}{336pt} \begin{Verbatim}[fontsize=\small] \eqSubmit{http://www.example.edu/scripts/eqRecord.asp\#FDF} {QuizIt}{Math101} \begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%. \begin{questions} \item ... ... \item ... \end{questions} \end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz \end{Verbatim} \end{minipage}\label{display:BodyEqRec} \end{equation} Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz}, it takes three parameters. \begin{equation} \begin{minipage}{225pt} \begin{Verbatim}[fontsize=\small,commandchars=!()] \eqSubmit{!meta(submitURL)}{!meta(dbName)}{!meta(dbTable)} \end{Verbatim} \end{minipage}\label{display:SubmitRec} \end{equation} \subparagraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential information use by the server-side scripts. The parameters of \cs{eqSubmit} are briefly described. \begin{aebQuote}\rightskip0pt \begin{description}\def\NH{\relax\hspace*{-\labelsep}}% \item\NH\meta{submitURL} is the {\URL} to the script \texttt{eqRecord.asp\#FDF}. Internally, the value of this parameter is saved in the text macro \cs{eq@CGI}. Note that the name of the script \texttt{eqRecord.asp} has \texttt{\#FDF} appended (the hash mark `\texttt{\#}' followed by the fragment identifier {\FDF}\index{fragment identifier (FDF)@fragment identifier (FDF)}). \item\NH\meta{dbName} is the name of the database to use. My examples use ODBC, with \texttt{QuizIt} as the DSN (data source name). \item\NH\meta{dbTable} is the name of the table into which the data record is to be inserted (this is \texttt{Math101} in the example above). \end{description} \end{aebQuote} The three arguments of the command \cs{eqSubmit} are used to define the values of \cs{db@Name}, \cs{db@Table} and \cs{eq@CGI}, respectively, the values of which are used to populate the hidden fields. Assuming \textsf{eqRecord.asp} is installed on your web server, and the \textsl{FDF Toolkit} has also been installed (see Section~\ref{settingup}), we are ready to submit the quiz. \subsection{Field Values Processed by \textsf{eqRecord.asp}}\label{eqRfieldvalues} The \textsf{eqRecord} script processes two classes of field data: certain ``\hyperref[hardwired]{hard-wired}'' field data; and field data having a \hyperref[hierarchalfields]{hierarchal} name with a root of either \anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or \texttt{IdInfo.Name.Last}. Details of each of these follow. \subsubsection{``Hard-wired'' Fields}\label{hardwired} When you compile your source document using the package \pkg{eq2db} with the \texttt{eqRecord} option, the package creates three hidden text fields, with field titles of \texttt{dbName}, \texttt{dbTable} and \texttt{quizName}. These hidden fields are created under the `End Quiz' button. At submit time, these fields are populated and submitted. Below is an enumerated list of these three fields with a brief description of each: \begin{enumerate} \item \texttt{dbName}: The name of the database to which the data is to be saved. (I've been using ODBC to reference the database.) \item \texttt{dbTable}: The name of the table within \texttt{dbName} where the data is to be stored. \item \texttt{quizName}: The name of the quiz or test. Name would uniquely characterize the quiz/test the student has taken. \end{enumerate} The first two hidden fields are populated by the second and third arguments, respectively, of \cs{eqSubmit}, as defined in display~\eqref{display:SubmitRec}. The third piece of data, \texttt{quizName}, is obtained from the first required argument of the \env{quiz} environment. See the skeleton example in display~\eqref{display:BodyEqRec}, there you'll see \verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz name and is passed to the server-side script as the value of the \texttt{quizName} hidden text field. \subsubsection{Fields with Hierarchal Names}\label{hierarchalfields} Other than the fields described in \nameref{hardwired}, \textsf{eqRecord.asp} processes only fields with hierarchal names that have a root name of \anglemeta{quizName} (see \nhnameref{hardwired} on page~\pageref{hardwired}) or a root name of \texttt{IdInfo}. \paragraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the field title of one of the hidden fields, its value is picked up as the first argument of the \env{quiz} environment; the value is stored in the text macro \cs{currQuiz}. In addition to the ``hard-wired'' hidden fields described earlier, there are actually three more hidden fields (under the `End Quiz' button) with root name \anglemeta{quizName}. These are \begin{itemize} \item \cs{currQuiz.numQuestions}: The number of questions in the quiz \item \cs{currQuiz.numCorrect}: The number of correct questions \item \cs{currQuiz.Responses}: a list of all the responses of the user \end{itemize} The values of these fields are also sent to \textsf{eqRecord.asp}. There is a mechanism for creating more hidden fields the values of which are sent to the script. The technique for doing this will be discussed later. \paragraph*{\texttt{IdInfo}:}\chgCurrLblName{IdInfo}\label{para:IdInfo} As mentioned earlier, \textsf{eqRecord.asp} processes fields that use a hierarchal naming convention, with root name of \anglemeta{quizName} or \texttt{IdInfo}. Fields whose root name is \texttt{IdInfo} are meant to hold information about the person taking the quiz: first name, last name, student number, etc. For example, you can create fields the user fills in for self-identifi\-cation. In the preamble, you can define new commands: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] % User's First Name \newcommand\FirstName[2]{\textField{IdInfo.Name.First}{#1}{#2}} % User's Last Name \newcommand\LastName[2]{\textField{IdInfo.Name.Last}{#1}{#2}} % User's SSN \newcommand\SSN[2]{\textField[\MaxLen{11} \AA{\AAKeystroke{AFSpecial_Keystroke(3);} \AAFormat{AFSpecial_Format(3);} }]{IdInfo.SSN}{#1}{#2}} \end{Verbatim} \noindent Note that I've defined these fields so that their names follow a hierarchal name structure, with a root of \texttt{IdInfo}. The two required arguments are the dimensions of the text field being constructed. For example, \verb+\FirstName{100bp}{10bp}+ creates a text field with a title of \texttt{IdInfo.Name.First} which is \texttt{100bp} wide and \texttt{10bp} high. \redpoint See the demo file \texttt{quiz1.tex} for examples. \medskip\noindent Additional \texttt{IdInfo} fields can be constructed. \subsection{Mapping PDF Field Names onto DB Field Names}\label{mappdf2db} \textsf{eqRecord.asp} is a quasi-general script for mapping the values of PDF fields into corresponding fields in a database. The way \textsf{eqRecord} is set up, the DB field name is derived from the PDF field name. For example, the value of the PDF field \texttt{Quiz1.numQuestions} is stored in the DB under the DB field name of \texttt{numQuestions}. For field names such as \texttt{IdInfo.Name.Last}, we can't map this into the DB field name \texttt{Name.Last} because for some databases (notably, Microsoft Access) database field names containing a `dot' are not legal. As a work around, \textsf{eqRecord.asp} strips all dots from the field name, and replaces them with the value of the VB Script variable \texttt{dotReplace}. The definition of \texttt{dotReplace} in \textsf{eqRecord.asp} is \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] Dim dotReplace : dotReplace = "_" \end{Verbatim} \noindent That is, a `dot'(\texttt.) is replaced by an `underscore' (\texttt\_). \medskip\noindent The table below illustrates the mapping of PDF field name onto database field names. Suppose the \texttt{quizName} is \texttt{Quiz1}: \medskip \begin{longtable}{>{\ttfamily}l>{\ttfamily}ll} \multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endfirsthead \multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endhead quizName (e.g.,\,Quiz1) & quizName & Yes\\ Quiz1.numQuestions & numQuestions & Yes\\ Quiz1.numCorrect & numCorrect & Yes\\ Quiz1.Responses & Responses & Yes\\ IdInfo.Name.Last & Name\_Last& No\\ IdInfo.Name.First& Name\_First & No\\ IdInfo.SSN & SSN & No\\ \multicolumn1l{N/A} & TimeOfQuiz & Yes\\ \end{longtable} \noindent The last entry needs comment: \textsf{eqRecord.asp} generates a time stamp when a quiz is processed. This time stamp is stored in a field with a name of \texttt{TimeOfQuiz}. This is a required field in your database. \subsection{Adding more Hidden Fields}\label{moreHiddenFields} When you add fields with a hierarchal name with a root of \cs{currQuiz} or \texttt{IdInfo}---whether hidden or not---the values of these fields will be submitted and processed by \textsf{eqRecord.asp}. When you add fields in your document, there should be a corresponding DB field to receive this data (see Section~\ref{mappdf2db} for naming conventions). You can also add hidden fields to transmit information about the quiz that the user does not need to see. \Example Suppose you have a point value to each question and want to report the point score (rather than the number missed). In this case, you would use the \cs{PointsField} field instead of the \cs{ScoreField} (though you could use both). \cs{PointsField} has a hierarchal name, but its root does not begin with \cs{currQuiz}; consequently, the value of this field is not submitted to \textsf{eqRecord.asp}. (The value of this field is a string what is meant to be read by the user; it reads, for example, ``Score: 16 out of 20''; we don't want this string submitted anyway, we would want the point score (16) and the total points (20) submitted.) We want to transmit the points scored and the total number of points to the server-side script. The \pkg{eq2db} package defines two helper commands for creating hidden fields (these hidden fields are hidden under the `End Quiz' button); these are \cs{addHiddenField} and \cs{populate\-HiddenField}. Suppose we had a quiz, \texttt{Quiz1}, in which we wanted to report points scored and total points. First, we need to add two hidden fields, we'll call them \texttt{Quiz1.ptScore} and \texttt{Quiz1.nPointTotal}; we create the hidden fields using \cs{addHiddenField}: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \addHiddenTextField{Quiz1.ptScore}{} \addHiddenTextField{Quiz1.nPointTotal}{\theeqpointvalue} \end{Verbatim} \noindent The first parameter is the title (name) of the field, the second parameter is the default value. For the first line, no default value is given; for the second line, a default value of \cs{theeqpointvalue} is given. The counter \cs{eqpointvalue} contains the total number of points for the quiz so we can insert that value at \texttt{latex} compile-time. The value of the first field added, \texttt{Quiz1.ptScore}, is not known until a user takes a quiz and submits results. The \pkg{eq2db} command \cs{populateHiddenField} inserts the necessary JavaScript that would populate the specified field. For example, \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \populateHiddenField{Quiz1.ptScore}{ptScore} \end{Verbatim} The first parameter is the field name, the second is the value the field is to hold when the user clicks on `End Quiz'. The command \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \populateHiddenField{fieldname}{fieldvalue} \end{Verbatim} expands to, \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] this.getField("fieldname").value = fieldvalue; \end{Verbatim} which is the JavaScript for populating the field, is inserted into the code just prior to the submission of the data. \redpoint See second quiz in the sample file \texttt{quiz1.tex} for a complete example of creating a quiz with weight set for each question, and for reporting the point score and total points. \endredpoint \medskip\noindent The table below lists some variables (both \LaTeX{} and JavaScript) that might be useful in extracting desired information from quiz for submittal. \begin{longtable}{>{\ttfamily}l>{\PBS\raggedright}p{.55\linewidth}} \multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endfirsthead \multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endhead Score & Score of the user with one point per problem. This value is always reported in the hidden text field \texttt{quizName.numCorrect}. This is a JavaScript variable known when the user finishes the quiz. This value is always reported in \texttt{quizName.numQuestions}, the hidden text field.\\ \cs{thequestionno} & The number of questions in the current quiz. A \LaTeX{} macro; known at compile-time.\\ Responses & A comma-delimited list of all responses of the user. A JavaScript variable known when the user finishes the quiz. Always reported in the hidden field \texttt{quizName.Responses}\\ ptScore & The point score of the user's quiz. A JavaScript variable, known when the user finishes quiz.\\ \cs{theeqpointvalue} & The total number of points in the current quiz. A \LaTeX{} macro, known at compile-time.\\ pcScore& The score expressed as a percent. A JavaScript variable known when the user finishes the quiz. \\ quizGrade & The letter grade of the user's quiz. A JavaScript variable, known at ``run-time''. \\ \cs{eqGradeScale} & The grade scale for the quiz. A \LaTeX{} macro, known at ``compile-time''.\\ \end{longtable} %\redpoint Other useful variables---perhaps at developers request---will be %added in the future. \endredpoint \subsection{Setting Up}\label{settingup} In this section, we briefly discuss configuring your server and setting up the demo files that accompany this distribution. \subsubsection{Configuring the Server} On the server side, in order for \textsf{eqRecord.asp} to run correctly, Microsoft Internet Information Server (IIS), version 4.0 or greater, is needed. The script \textsf{eqRecord.asp} needs to be placed where ASP scripts have execute permissions. The \textsf{eqRecord.asp} uses the \textsl{Adobe FDF Toolkit}\footnote{Currently located at the \href{http://partners.adobe.com/public/developer/acrobat/devcenter.html}{Acrobat Family Developer Center}.}, version 6.0. Follow the directions for installation contained in the accompanying documentation. Install \textsf{eqRecord.asp} in a folder (perhaps called \texttt{Scripts}) designated to execute scripts. If you don't have such a folder, then the following steps explain how to create a virtual directory through IIS that points to this folder. \begin{enumerate} \item Create a new folder on the system (\texttt{Scripts}, for example). Its recommended location is inside the \texttt{Inetpub} folder. \item Place \textsf{eqRecord.asp} in this newly created folder. \item In the MMC snap-in for IIS, create a virtual directory by right-clicking on the Default Web Site and selecting \texttt{New\;>\;Virtual Directory}. \item Type ``Scripts'' (or whatever the name of the folder you created in~Step~1) as the alias for the virtual directory, and then link it to the physical directory you created in Step~1. \item Make sure that ``Script execution'' privileges are enabled. If not, enable them. \end{enumerate} \subsubsection{Set Up the Demo Files} Place the Access 2000 database, \texttt{QuizIt.mdb}, in a folder that is accessible by the server, such as the root level of your web server, or perhaps, a folder dedicated to database files. Register the database with the ODBC Data Source Administrator as a System DSN under the System Data Source Name of ``QuizIt''. Modify the first parameter of \cs{eqSubmit} in \texttt{quiz1.tex} and compile (\texttt{latex}), then create \texttt{quiz1.pdf} using \textsf{Acrobat Distiller}, \textsf{pdftex} or \textsf{dvipdfm}, and place it on your server. Test by opening \texttt{quiz1.pdf} in your web browser and taking a sample test. Good luck, I hope it works! \subsubsection{Comments on Demo Files}\label{demofiles} \paragraph*{\texttt{quiz1.tex}:} This file has two quizzes, \texttt{Quiz1} and \texttt{Quiz2}. \texttt{Quiz1} has no frills, the user enters his/her name and SSN, takes the quiz, and results are saved to the \texttt{eqQuiz.mdb} Access database. \texttt{Quiz2} is a bit more interesting as it demonstrates how to assign points to each question, and how to report the results. The techniques used in this quiz were discussed in Section~\ref{moreHiddenFields}. \paragraph*{\texttt{quiz2.tex}:} The quizzes of \texttt{quiz1.tex} did not check whether the user is enrolled in the class, and as such, is allowed to take the quiz. The demo file \texttt{quiz2.tex} demonstrates how to\dots \begin{questions} \item check whether the user has entered a valid SSN, that is, the SSN of someone enrolled in the class, or is permitted to take the quiz \item set a deadline date to take the quiz \item set a time limit to take the quiz \end{questions} Other variations are possible. \subsection{Accessing Results in the DB} The database that is to hold quiz results is placed on a web-server and consequently, is not easily accessible by the instructor. The ASP script \textsf{GenericDB}\footnote{\url{http://www.genericdb.com/}} developed by Eli Robillard, is a tool that can be used to access the database through your web browser. Using \textsf{GenericDB}, you can view, edit, update, add new and delete database records---and it's free! Check it out! \section{The \texttt{eqText} Option}\label{eqTextOption} In this section, we describe how to submit your data to a server-side script that save the data to a tab-delimited text field. The \opt{submitAs} option can be used with the \env{eqText} option. With \texttt{submitAs=FDF}, the form data is submitted in the FDF format, the native form data format for PDF, the target script should be \app{eqText.asp}. When \texttt{submitAs=HTML} is used, the form data is submitted as ordinary HTML form data, which can then be processed by any public domain script; alternately, you can use one of the scripts in Table~\ref{table:QuizScripts1}. These four scripts are available on the CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}. \begin{table}[htb]\centering \begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}} \multicolumn{1}{>{\bfseries}r}{Option and return type}&% \multicolumn{1}{>{\bfseries}l}{Script Files for \app{Windows} \& \app{Linux}}\\ \texttt{eqText}, {\HTML} return&eqText\_h.asp eqText\_h.php\tabularnewline[3pt] \texttt{eqText}, {\FDF} return&eqText\_hf.asp\#FDF\penalty0 eqText\_hf.php\#FDF \end{tabular} \caption{Scripts for \opt{eqText} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts1} \end{table} \subsection{Submit as FDF} We describe how to create an online quiz that is to be submitted to the server-side script \textsf{eqText.asp}\footnote{The script \textsf{eqText.asp} comes with absolutely \emph{no guarantees}. Extensive testing should be made on your own system to assure yourself script is reliable enough to use in practice.}. With this option, you save your quiz data to a tab-delimited file. The \textsl{FDF Toolkit}\FmtMP[\baselineskip]{FDF Toolkit required} is required to be installed on the \app{Windows} server. \redpoint The demo file for this option is \texttt{quiz4.tex}. \paragraph*{In the preamble.} Begin the document with the usual preamble for an \pkg{exerquiz} document, but include the \pkg{eq2db} package with the \opt{eqRecord} option. \begin{equation} \begin{minipage}{355pt} \begin{Verbatim}[fontsize=\small,commandchars=!()] \documentclass{article} \usepackage{amsmath} \usepackage[!grayV(!anglemeta(driver)),designi]{web} % driver: dvips, pdftex, xetex \usepackage{exerquiz} \usepackage[!grayV(submitAs=FDF,)eqText]{eq2db} \end{Verbatim} \end{minipage}\label{display:PreamEqText} \end{equation} Shown in gray are the \anglemeta{driver} and \opt{submitAs} options. The \opt{pdflatex} and \opt{xelatex} applications are automatically detected, so only \opt{dvips} needs to be specified if you are building your PDF with \app{Acrobat Distiller}. The submission type is FDF by default, so \opt{submitAs=FDF} need not be listed in the options of \pkg{eq2db}. \paragraph*{In the body.} The following is a rough outline of an \pkg{exerquiz} quiz document that submits to \app{eqRecord.asp}, the preamble declarations of display~\eqref{display:PreamEqText}. \begin{equation} \begin{minipage}{330pt} \begin{Verbatim}[fontsize=\small] \eqSubmit{http://www.example.edu/scripts/eqText.asp\#FDF} {c:/Inetpub/Data/math101.txt}{Math101} \begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%. \begin{questions} \item ... ... \item ... \end{questions} \end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz \end{Verbatim} \end{minipage}\label{display:eqTextTemplate} \end{equation} Notice that `\texttt{\#FDF}' is appended to the path, this informs the PDF viewer to expect the server-side script to return FDF form data. \medskip Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz}, it takes three parameters. \begin{equation} \begin{minipage}{276pt} \begin{Verbatim}[fontsize=\small,commandchars=!()] \eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)} \end{Verbatim} \end{minipage}\label{display:SubmitTxt} \end{equation} \subparagraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential information use by the server-side scripts. Its parameters are briefly described. \begin{description} \item\meta{submitURL} is the {\URL} to the server-side script \texttt{eqText.asp}. Internally, the value of this parameter is saved in the text macro \cs{eq@CGI}. \item\meta{pathToTabFile} is the path to the tab-delimited file on the server where the script is to save the data. On \app{Windows}, \meta{pathToTabFile} is the physical (absolute) path to the file, on \app{Linux} it can be a relative path (relative to the folder containing the executing script). Internally, this value is saved in the text macro \cs{db@Name}.\footnote{Choice for the names of \cs{db@Name} and \cs{db@Table} were originally based on the \texttt{eqRecord} option where data is saved to a database.}\xdef\fnNameChoice{\thefootnote} \item\meta{courseName} is the course name of the class taking the quiz. Internally, this value is saved in the text macro \cs{db@Table}.${}^\text{\fnNameChoice}$ \end{description} \subsubsection{Field Values Processed by \textsf{eqText.asp}}\label{eqTfieldvalues} The \textsf{eqText} script processes two classes of field data: certain ``\hyperref[hardwiredText]{hard-wired}'' field data; and field data having a \hyperref[hierarchalfieldsText] {hierarchal} name with a root of either \anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or \texttt{IdInfo.Name.Last}. Details of each of these follow. \paragraph*{``Hard-wired'' Fields.}\label{hardwiredText} When you compile your source document with the package \pkg{eq2db} with the \texttt{eqText} option, the package creates a number of hidden text fields. These hidden fields are created under the `End Quiz' button. At submit time, these fields are populated and submitted along with the quiz data. Below is an enumerated list of these hidden fields with a brief description of each: \begin{enumerate} \item \texttt{pathToTxtFile}: The value of second argument of \cs{eqSubmit} populates this text field. \item \texttt{courseName}: The value of the third parameter of \cs{eqSubmit} populates this text field. \item \texttt{quizName}: The name of the quiz or test, this is \cs{currQuiz}. Name should uniquely characterize the quiz/test the student is taking. \end{enumerate} The first two hidden fields are populated by the second and third arguments, respectively, of \cs{eqSubmit}, as defined in display~\eqref{display:SubmitTxt}. The third piece of data, \texttt{quizName}, is obtained from the first required argument of the \env{quiz} environment. See the skeleton example in display~\eqref{display:eqTextTemplate}, there you'll see \verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz name and is passed to the server-side script as the value of the \texttt{quizName} hidden text field. \paragraph{Fields with Hierarchal Names.}\label{hierarchalfieldsText} Other than the fields described in \nameref{hardwired}, \textsf{eqText.asp} processes only fields with hierarchal names that have \cs{currQuiz} as a root name (see \nhnameref{hardwired} above) or a root name of \texttt{IdInfo}. \subparagraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the field title of one of the hidden fields, its value is picked up as the first argument of the \env{quiz} environment; the value is stored in the text macro \cs{currQuiz}. In addition to the ``hard-wired'' hidden fields described earlier, there are actually five more hidden fields (under the \textsf{End Quiz} button) with root name \cs{currQuiz}. These are, \begin{itemize} \item \cs{currQuiz.numQuestions}: The number of questions in the quiz. \item \cs{currQuiz.numCorrect}: The number of correct questions. \item \cs{currQuiz.Responses}: A list of all the responses of the user. \item \cs{currQuiz.ptScore}: The point score the student received on completion of the quiz. \item \cs{currQuiz.nPointTotal}: The total number of points in the quiz. \end{itemize} The values of these fields are also sent to the server-side script for the \texttt{eqText} option. There is a mechanism for creating more hidden fields the values of which are sent to the script. The technique for doing this is discussed in \Nameref{moreHiddenFields}. \subparagraph*{\texttt{IdInfo}:}\label{spara:IdInfoText} As mentioned earlier, the \textsf{eqText} scripts process fields that use a hierarchal naming convention, with root name of \cs{currQuiz} or \texttt{IdInfo}. Fields whose root name is \texttt{IdInfo} are meant to hold information about the person taking the quiz: first name, last name, student number, and so on. Refer to the paragraph titled \textbf{\nhnameref{para:IdInfo}} on page~\pageref{para:IdInfo} for more information. \subsubsection{Setting up the Script} On the server side, in order for \textsf{eqText.asp} to run correctly, Microsoft Internet Information Server (IIS), version 4.0 or greater, is needed. The script \textsf{eqText.asp} should be placed where ASP scripts have execute permissions. \subsection{Submit as HTML} When the \opt{eqText} and \opt{submitAs=HTML} options are specified for \pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the \opt{eqText} option, it is meant that the server-side script save the form data as a tab-delimited file. You can develop your own script for doing this, or you can use one of the scripts of Table~\ref{table:QuizScripts1}, available on the CD-ROM of the book \AEBBook~\cite{book:AEBB}. The advantage of submitting as HTML is that the \textsl{FDF Toolkit} is not needed, and the techniques for writing a server-side script are well known. The preamble of your document should look something like the following. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \documentclass{article} \usepackage[designi]{web} \usepackage{exerquiz} \usepackage[eqText,submatAs=html,tagged]{eq2db} \end{Verbatim} The \opt{tagged} option is recommended for the \opt{eqText} option but no required. You may have other packages loaded, as well as other options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the following sense: If the \pkg{eq2db} package is not loaded, then an \pkg{exerquiz} quiz is self-contained, that is, it is not submitted to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are submitted to a server-side script. In addition to the introduction of the \pkg{eq2db} package in the preamble, there are two more important commands: \begin{equation} \begin{minipage}{300pt} \begin{Verbatim}[commandchars=!()] \eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)} \rtnURL{!meta(returnURL)} \end{Verbatim} \end{minipage}\label{display:eqSubmitT} \end{equation} \cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined in \pkg{eq2db}, is required only when the return from the server is an {\HTML} page, but is recommended. \paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential information use by the server-side scripts, \cs{rtnURL} provides a return {\URL} that points to where the student should navigate after the quiz. Their parameters, as indicated in display~\eqref{display:eqSubmitT}, are briefly described. \begin{description} \item\meta{submitURL} is the {\URL} of one of the server-side scripts in Table~\ref{table:QuizScripts1}. Internally, the value of this parameter is saved in the text macro \cs{eq@CGI}. \item\meta{pathToTabFile} is the path to the tab-delimited file on the server where the script is to save the data. On \app{Windows}, \meta{pathToTabFile} is the physical (absolute) path to the file, on \app{Linux} it can be a relative path (relative to the folder containing the executing script). Internally, this value is saved in the text macro \cs{db@Name}.${}^\text{\fnNameChoice}$ \item\meta{courseName} is the course name of the class taking the quiz. Internally, this value is saved in the text macro \cs{db@Table}.${}^\text{\fnNameChoice}$ \item\meta{returnURL} is the {\URL} of the page the student should return to after finishing the quiz. The value of \cs{rtnURL} is required when the script returns an {\HTML} page, and is useful when the return is {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL} to hold \meta{returnURL}. \end{description} \paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data. The scripts of Table~\ref{table:QuizScripts1} were written for the upcoming book {\AEBBook} and are available on the accompanying CD-ROM. Refer the book for the details of implementing these scripts. \paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts1} are of two types: HTML return and FDF return. In the first case, after the student has submitted his/her quiz, the server-side script returns an HTML page to the browser window with an assessment of the student's efforts on the quiz. In the second case, the script sends back an alert dialog box message saying the data is received and saved; the quiz is self-marking for the student to review. Details are laid out in {\AEBBook}~\cite{book:AEBB}. \section{The \texttt{eqEmail} Option}\label{eqEmailOption} In this section, we describe how to submit your data to a server-side script that in turn sends an email message to a list of recipients, the body of the messages contains the student's quiz results. The \opt{submitAs} option can be used with the \env{eqEmail} option. With \texttt{submitAs=FDF}, the form data is submitted in the FDF format, the native form data format for PDF, the target script should be \app{eqEmail.asp}. When \texttt{submitAs=HTML} is used, the form data is submitted as ordinary HTML form data, which can then be processed by any public domain script; alternately, you can use one of the scripts in Table~\ref{table:QuizScripts2}. These four scripts are available on the CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}. \begin{table}[htb]\centering \begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}} \texttt{eqEmail}, {\HTML} return&eqEmail\_h.asp\penalty0eqEmail\_h.php\tabularnewline[3pt] \texttt{eqEmail}, {\FDF} return&eqEmail\_hf.asp\#FDF\penalty0 eqEmail\_hf.php\#FDF \end{tabular} \caption{Scripts for \opt{eqEmail} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts2} \end{table} \subsection{Submit as FDF} We describe how to create an online quiz that is to be submitted to the server-side script \app{eqEmail.asp}\footnote{The script \textsf{eqEmail.asp} comes with absolutely \emph{no guarantees}. Extensive testing should be made on your own system to assure yourself script is reliable enough to use in practice. Feel free to modify the script to suite your needs. If your improvements are noteworthy, please allow me to incorporate them into the basic \textsf{eqEmail.asp} for others to use. }. For this option, quiz results are e-mailed to the instructor. The \textsl{FDF Toolkit} is required to be installed on the \app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}. \redpoint \texttt{quiz3.tex} is the demo file for this option. \medskip\noindent The steps to create a quiz to be submitted to \textsf{eqEmail} are simple enough. First, the preamble of your document should look something like this: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \documentclass{article} \usepackage[designi]{web} \usepackage{exerquiz} \usepackage[eqEmail]{eq2db} \end{Verbatim} \noindent You may have other packages loaded, as well as other options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the following sense: If the \pkg{eq2db} package is not loaded, then an \pkg{exerquiz} \env{quiz} is self-contained, that is, it is not submitted to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are submitted to a server-side script. Next, you write your \pkg{exerquiz} \env{quiz}: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF} {dpspeaker@example.edu}{Math101} \begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%. \begin{questions} \item ... ... \item ... \end{questions} \end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz \end{Verbatim} Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz}. \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()] \eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)} \end{Verbatim} The first parameter is the URL to the server-side script, in the example above, we have \texttt{http://www.example.edu/scripts/eqEmail.asp\#FDF} (note the suffix of \texttt{\#FDF}); the second parameter, \meta{recipients}, is the e-mail address of the person to receive the quiz results; the third parameter, \meta{courseName} is the course name. In the above example, the course name is \texttt{Math101}. \redpoint If meta{recipients} is a comma-delimited list of e-mail addresses, then \textsf{eqEmail.asp} will parse the list, and use the first e-mail in the list in the \texttt{From} field of the e-mail. Other email addresses in the list also receive copies of the quiz results.\endredpoint \medskip There is another parameter of importance. The first argument of the \env{quiz} environment is the \texttt{quizName} of the quiz, this is \texttt{Quiz1} in the above example. Assuming \textsf{eqEmail.asp} is installed on your web server, and the \textsl{FDFToolkit} has also been installed (see Section~\ref{settingup}), we are ready to submit the quiz. Below is the body of one of my test e-mails I made using \texttt{quiz3.pdf}: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] Course Information Course Name: Math101 Quiz: Quiz1 TimeOfQuiz: 8/23/2003 8:12:40 PM Student Results Name_First: Don Name_Last: Story SSN: 121212121 Responses: Leibniz,2x e^(x^2),-1,-cos(x) numCorrect: 4 numQuestions: 4 \end{Verbatim} \noindent If you add more fields, as described in Section~\ref{moreHiddenFields}, this information should be appended to the body of the e-mail. \subsubsection{Field Values processed by \textsf{eqEmail.asp}} Actually, \textsf{eqEmail.asp} is a variation of \textsf{eqRecord.asp} and many of the details of this section are the same \hyperref[eqRfieldvalues]{Section~\ref*{eqRfieldvalues}}. The ``hard-wired'' fields are \texttt{mailTo}, \texttt{courseName} and \texttt{quizName}. These fields are hidden under the `End Quiz' button, and are populated at submit time. As in the \texttt{eqRecord} option, the value of the \texttt{quizName} field comes from the argument of the \env{quiz} environment: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF} {dpspeaker@example.edu}{Math101} \begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%. \begin{questions} \item ... ... \item ... \end{questions} \end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz \end{Verbatim} In this quiz, the field with name \texttt{quizName} will have a value of \texttt{Quiz1}. \medskip See paragraph ``\nameref{hierarchalfields}'', page~\pageref{hierarchalfields}, as well as Section~\ref{moreHiddenFields} on page~\pageref{moreHiddenFields} for the \texttt{eqRecord} option, the details are the same. \subsubsection{Setting up and Modifying the Script} On the server side, in order for \textsf{eqEmail.asp} to run correctly, Microsoft Internet Information Server (IIS), version 4.0 or greater, is needed. The script \textsf{eqEmail.asp} should be placed where ASP scripts have execute permissions. There are two methods of sending e-mail: \begin{questions} \item \texttt{CDONTS}: This method (which is commented out by default) can be used on an NT server. Uncomment if you want to use CDONTS, and comment out the CDOSYS code lines that follow. \item \texttt{CDOSYS}: This can be run on a Win2000 or WinXP server. \end{questions} The script needs to be modified appropriate to your server, in particular, search down in \texttt{eqEmail.asp} for the configuration line \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] eqMail.Configuration.Fields.Item ("http://schemas.microsoft.com/cdo/configuration/smtpserver") = "mySMTP" \end{Verbatim} \noindent replace \texttt{mySMTP} with your SMTP server. The subject heading of the returning e-mail has the following format: \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] Quiz Results: Quiz1 of Math101 \end{Verbatim} If you want another subject format, modify \texttt{eqMail.Subject} as desired. \subsubsection{References} The following links were used as a reference in the development of the \texttt{Email.asp} script. \begin{itemize} \item CDOSYS: \begin{itemize} \item \href{http://invisionportal.com/show_tutorial.asp?TutorialID=160}{Invision Portal} Tutorial: CDOSYS email tutorial \item \href{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cdosys/html/_cdosys_imessage_interface.asp} {MSDN}: CDO for Windows 2000. The IMessage Interface. (Use MIE to view this page.) \item \href{http://www.asp101.com/articles/john/cdosmtprelay/default.asp}{ASP 101} Sending Email Via an External SMTP Server Using CDO \end{itemize} \item CDONTS \begin{itemize} \item \href{http://www.juicystudio.com/tutorial/asp/cdonts.html}{Juicy Studio} The ASP CDONTS Component \item \href{http://www.devasp.com/Samples/mail.asp}{DevASP} Sending Mail from ASP with CDONTS.NewMail Object \end{itemize} \end{itemize} \subsection{Submit as HTML} When the \opt{eqEmail} and \opt{submitAs=HTML} options are specified for \pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the \opt{eqEmail} option, it is meant that the server-side script should take the incoming form data, build an email the body of which reports the quiz results, and send the message to a list of recipients. You can develop your own script for doing this or you can use the scripts provide with the book \AEBBook~\cite{book:AEBB}. The advantage of submitting as HTML is that the \textsl{FDF Toolkit} is \emph{not needed}, and the techniques for writing a server-side script are well known. The preamble of your document should look something like the following. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \documentclass{article} \usepackage[designi]{web} \usepackage{exerquiz} \usepackage[eqEmail,submatAs=html]{eq2db} \end{Verbatim} The \opt{tagged} option is \emph{not recommended} for the \opt{eqEmail}. You may have other packages loaded, as well as other options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the following sense: If the \pkg{eq2db} package is not loaded, then an \pkg{exerquiz} quiz is self-contained, that is, it is not submitted to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are submitted to a server-side script. In addition to the introduction of the \pkg{eq2db} package in the preamble, there are two more important commands: \begin{equation} \begin{minipage}{300pt} \begin{Verbatim}[commandchars=!()] \eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)} \rtnURL{!meta(returnURL)} \end{Verbatim} \end{minipage}\label{display:eqSubmitE} \end{equation} \cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined in \pkg{eq2db}, is required only when the return from the server is an {\HTML} page, but is recommended. \paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential information use by the server-side scripts, \cs{rtnURL} provides a return {\URL} that points to where the student should go to next after the quiz. Their parameters, as indicated in display~\eqref{display:eqSubmitE}, are briefly described. \begin{description}\def\NH{\relax\hspace*{-\labelsep}}% \item\NH\meta{submitURL} is the {\URL} of one of the server-side scripts in Table~\ref{table:QuizScripts1}. Internally, the value of this parameter is saved in the text macro \cs{eq@CGI}. \item\NH\meta{recipients} is a comma-delimited list of email addresses to whom the quiz results are sent. For example, \begin{Verbatim}[xleftmargin=\amtIndent] dpspeaker@talking.edu,taofdps@talking.edu \end{Verbatim} The first email address is picked off and used in the `From' field of the email while the whole list is entered into the `To' field. Internally, this value is saved in the text macro \cs{db@Name}.${}^{\text{\fnNameChoice}}$ \item\NH\meta{courseName} is the course name of the class taking the quiz. Internally, this value is saved in the text macro \cs{db@Table}.${}^{\text{\fnNameChoice}}$ \item\NH\meta{returnURL} is the {\URL} of the page the student should return to after finishing the quiz. The value of \cs{rtnURL} is required when the script returns an {\HTML} page, and is useful when the return is {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL} to hold \meta{returnURL}. \end{description} \paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data. The scripts of Table~\ref{table:QuizScripts2} were written for the upcoming book \AEBBook~\cite{book:AEBB} and are available on the accompanying CD-ROM. Refer the book for the details of implementing these scripts. \paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts2} are of two types: HTML return and FDF return. From the student's point of view, his/her experience is the same as the \opt{eqText} option with \texttt{submitAs=HTML}. In the first case, after the student has submitted his/her quiz, the server-side script, as sending out an email response to the \anglemeta{recipients}, returns an HTML page to the browser window with an assessment of the student's efforts on the quiz. In the second case, the script sends back an alert dialog box message saying the data is received and results are sent to the instructor (the \anglemeta{recipients}); the quiz is self-marking for the student to review. Details are presented in \AEBBook~\cite{book:AEBB}. \subsection{The \texttt{tagged} option}\label{taggedOption} When the student submits online quiz data to one of the server-side scripts, just prior to submission, the hidden field \cs{currQuiz.Responses} is populated with the student's answers. For example, \begin{Verbatim}[xleftmargin=\amtIndent] Newton,2x,-1,-cos(x) \end{Verbatim} is how the responses field is populated, by default. This data gives no indication of which are correct, how many points for each question, and so on. To obtain more information about the quiz taken by the student and his responses, you can specify the \opt{tagged} option. When this option is taken, the quiz data is written as a ``XML-like'' string. Figure~\ref{fig:tagXML} is an example of the data that populates the \cs{currQuiz.Responses} field and which is sent to the server when the \opt{tagged} option is specified. \begin{figure}[htb] \begin{minipage}{5.45in} \begin{Verbatim}[fontsize=\small] Newton 2x -1 -cos(x) \end{Verbatim} \end{minipage}% \caption{Example of a tagged XML string}\label{fig:tagXML} \end{figure} Referring to Figure~\ref{fig:tagXML}, the XML string packs more information in it than the default string. The quiz name is \texttt{Quiz1}, the {\PDF} file the student used is \texttt{quiz1.pdf} and there are four questions (\texttt{n=4}). The first question was a text fill-in type, worth $3$ points, the student responded correctly. The second question was a math fill-in worth $4$ points, he missed this one with an answer of \texttt{2x}. The root element \texttt{results} contains child elements or nodes called \texttt{question}. Each \texttt{question} node contains information about one of the questions in the quiz. The \texttt{question} node has several attributes, these attributes are seen in Figure~\ref{fig:tagXML} above: \begin{itemize} \item \texttt{n} is the question number. This is not the question number the user sees, but the value of an internal counter that increments each time a new question is posed. \item \texttt{type} is the type of question, possible values are \texttt{"text"} (text response), \texttt{"math"} (math response), \texttt{"mc"} (multiple choice), \texttt{"ms"} (multiple selection), \texttt{"grp"} (grouped response), and \texttt{"essay"} (multi-line text response). The latter is not graded by \pkg{exerquiz} but simply transmitted to the server. \item \texttt{ptype} is the problem (question) type, its value is normally \texttt{"na"} for `not applicable'. This attribute is used to describe the question in more detail within the XML. The value of \texttt{ptype} is set within the {\LaTeX} source file with \cs{QT\texttt{\darg{\meta{ptype}}}} command. Placement of this command is just after the \cs{item} command within the \env{questions} environment. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] \item\PTs{4}\QT{limits} Compute $\lim_{n\to\infty}...$ \end{Verbatim} Now, the \texttt{ptype} attribute will read \texttt{ptype="limits"}. If each problem is so tagged, the \texttt{ptype} attribute can be queried as part of larger quiz management system to view a student's effort with respect to all questions having the specified \texttt{ptype}. Such a system was never implemented, but the attribute is available. \item \texttt{points} is the number of points assigned to this question. \item \texttt{credit} is the amount of partial credit the student earned for this question. Questions types where this attribute can be nonzero are \texttt{"mc"}, \texttt{"ms"}, \texttt{"text"} (in response to a \cs{RespBoxTxtPC} question), and \texttt{"grp"}. \item \texttt{correct} is normally \texttt{"0"} (a wrong answer) or \texttt{"1"} (a correct answer); multiple selection (\texttt{"ms"}) and grouped (\texttt{"grp"}) questions use an array of values for the \texttt{correct} attribute, however. When calculating the score field (\cs{ScoreField}), the problem is either right or wrong; however, the calculation of the points field (\cs{PointsField}) takes into account the partial credit so a problem may be partially correct. \end{itemize} \paragraph*{Reconstructing the quiz.} Using the XML data as well as the information provided by the \texttt{IdInfo} collection of fields, it is possible to reproduce the {\PDF} document exactly as the student submitted it. A demonstration file was developed for exactly this purpose and is available on the CD-ROM that accompanies the \AEBBook~\cite{book:AEBB}. The \app{Acrobat} application is required. \section{The \texttt{custom} Option}\label{customOption} This option allows a script developer to utilize the macros of the \pkg{eq2db} Package to prepare an {\ifusebw\AcroT\else\cAcroT\fi} document to submit to a custom script. Simple create a file named \texttt{eq2dbcus.def} and include any custom creation of fields you may need for your script. When you then take the \texttt{custom} option, \begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] \documentclass{article} \usepackage[designi]{web} \usepackage{exerquiz} \usepackage[custom]{eq2db} \end{Verbatim} After the command definitions of \pkg{eq2db} are read, \texttt{eq2dbcus.def} is input. The rest is up to you. \redpoint That's all for now! Hope you find the package useful. Now I really must get back my retirement. \dps \addtocontents{toc}{\protect\vspace{2ex}} \newpage \markright{References} \begin{thebibliography}{[1]}\label{references} \addcontentsline{toc}{section}{\protect\numberline{}References} \bibitem{book:AEBB}\hypertarget{references}{}% \textsl{\AEBBook}, D. P. Story, in preparation. \end{thebibliography} \end{document}