Debian Codegraph @

texmf-dist/source/latex/eq-pin2corr/eq-pin2corr.dtx

raw
1 % \iffalse
2 % makeindex -s gglo.ist -o eq-pin2corr.gls eq-pin2corr.glo
3 % makeindex -s gind.ist -o eq-pin2corr.ind eq-pin2corr.idx
4 %<*copyright>
5 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
6 %% eq-pin2corr.sty package, %%
7 %% Copyright (C) 2021 D. P. Story %%
8 %% [email protected] [email protected] %%
9 %% %%
10 %% This program can redistributed and/or modified under %%
11 %% the terms of the LaTeX Project Public License %%
12 %% Distributed from CTAN archives in directory %%
13 %% macros/latex/base/lppl.txt; either version 1.2 of the %%
14 %% License, or (at your option) any later version. %%
15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16 %</copyright>
17 %<package>\NeedsTeXFormat{LaTeX2e}
18 %<package>\ProvidesPackage{eq-pin2corr}
19 %<package> [2021/05/29 v2.0 Applies PIN security to quizzes]
20 %<*driver>
21 \documentclass{ltxdoc}
22 %\usepackage[colorlinks,hyperindex=false,linktocpage,bookmarksnumbered]{hyperref}
23 \usepackage[colorlinks,hyperindex=false]{hyperref}
24 \usepackage{fancyvrb}
25 \usepackage{calc}
26 %\usepackage{eq-pin2corr}
27 %\def\texorpdfstring#1#2{#1}
28 %\pdfstringdefDisableCommands{\let\\\textbackslash}
29 \OnlyDescription % comment out for implementation details
30 \EnableCrossrefs
31 \CodelineIndex
32 \RecordChanges
33 \gdef\brpr#1{\texttt{\char123\relax#1\char125\relax}}
34 \let\darg\brpr
35 \let\env\texttt
36 \let\opt\texttt
37 \let\app\textsf
38 \let\pkg\textsf
39 \let\uif\textsf
40 \def\EXCL{!}
41 \def\visispace{\symbol{32}}
42 \def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
43 \def\meta#1{\textsl{\texttt{#1}}}
44 \def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
45 \def\CMD#1{\textbackslash#1}
46 \makeatletter
47 \renewcommand\theparagraph{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
48 \renewcommand\thesubparagraph{\texorpdfstring{\protect\P\protect\P\protect\ }{\textparagraph\textparagraph}}
49 \renewcommand{\section}
50 {\renewcommand{\@seccntformat}[1]{\thesection\quad}%
51 \@startsection {section}{1}{\z@}%
52 {-3.5ex \@plus -1ex \@minus -.2ex}%
53 {2.3ex \@plus.2ex}%
54 {\normalfont\Large\bfseries}}
55 \renewcommand{\subsection}
56 {\renewcommand{\@seccntformat}[1]{\thesubsection\quad}%
57 \@startsection {subsection}{1}{\z@}%
58 {-3.5ex \@plus -1ex \@minus -.2ex}%
59 {2.3ex \@plus.2ex}%
60 {\normalfont\large\bfseries}}
61 \renewcommand{\subsubsection}
62 {\renewcommand{\@seccntformat}[1]{\thesubsubsection\quad}%
63 \@startsection {subsubsection}{1}{\z@}%
64 {-3.5ex \@plus -1ex \@minus -.2ex}%
65 {2.3ex \@plus.2ex}%
66 {\normalfont\large\bfseries}}
67 %
68 \renewcommand{\paragraph}
69 {\renewcommand{\@seccntformat}[1]{\theparagraph\unskip\,}%
70 \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
71 \renewcommand{\subparagraph}
72 {\renewcommand{\@seccntformat}[1]{\thesubparagraph\unskip\,}%
73 \@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}{\bfseries}}
74 \edef\amtIndent{\the\parindent}
75 \newenvironment{aebQuote}
76 {\list{}{\leftmargin\amtIndent}%
77 \item\relax}
78 {\endlist}
79 \let\@latex@warning\@gobble
80 \makeatother
81 \InputIfFileExists{aebdocfmt.def}{\PackageInfo{eq-pin2corr}{Inputting aebdocfmt.def}}
82 {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
83 \PackageInfo{eq-pin2corr}{aebdocfmt.def cannot be found}}
84 \begin{document}
85 \addtolength{\marginparwidth}{3pt}
86 \GetFileInfo{eq-pin2corr.sty}
87 \title{The \textsf{eq-pin2corr} Package}
88 \author{D. P. Story\\
89 Email: \texttt{[email protected]}}
90 \date{processed \today}
91 \maketitle
92 \setcounter{secnumdepth}{5}
93 \setcounter{tocdepth}{5}
94 \bgroup
95 \value{secnumdepth}=3
96 \value{tocdepth}=3
97 \tableofcontents
98 \egroup
99 \DocInput{eq-pin2corr.dtx}
100 \IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here. Execute
101 \begin{quote}\texttt{makeindex -s gind.ist -o eq-pin2corr.ind eq-pin2corr.idx}\end{quote}
102 on the command line and recompile
103 \texttt{eq-pin2corr.dtx}.}
104 \IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here. Execute
105 \begin{quote}
106 \texttt{makeindex -s gglo.ist -o eq-pin2corr.gls eq-pin2corr.glo}
107 \end{quote}
108 on the command line and recompile \texttt{eq-pin2corr.dtx}.}
109 \end{document}
110 %</driver>
111 % \fi
112 % \MakeShortVerb{|}
113 % \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
114 % {\PackageInfo{web}{cannot find aebdonotindex.def}}
115 % \begin{macrocode}
116 %<*package>
117 % \end{macrocode}
118 %
119 % \section{Introduction}
120 % This package is an add-on to the \env{quiz} environment of the \pkg{exerquiz} package. It uses
121 % the \pkg{eq-save} package. To correct a quiz, the document consumer must press
122 % the \uif{Correct} button of a quiz and successfully enter the correct PIN number.
123 %
124 % \changes{v1.0}{2021/02/20}{Completed documentation, publish package for first time}
125 %
126 % \paragraph*{Purpose.} This package adds PIN security to a quiz created by
127 % the \env{quiz} environment. This package is designed for the educational
128 % sector, for instructors who use the quizzes of \pkg{exerquiz} to assess their
129 % students understanding of the course material.
130 %
131 % \paragraph*{PDF Viewers.} Discussion of PDF viewers for document author and document consumer.
132 % \begin{aebQuote}
133 % \begin{description}
134 % \item[Instructor] Any PDF viewer may be used as a PDF previewer, \app{sumatraPDF}, for instance,
135 % can be used, but it has not functionality. To test the newly created document
136 % to see if it is functioning correctly, must use \app{Adobe Reader DC} or \app{Acrobat DC}.\footnote
137 % {We use DC here to refer to actually any Adobe AA/AR application. Earlier versions of these applications
138 % will work.}
139 % \item[Document consumers (students)] The \pkg{exerquiz} and \pkg{eq-pin2tocorr} extensively
140 % use JavaScript to perform many background tasks. For the student to have any success in this
141 % workflow, he/she must use \app{Adobe Reader}.
142 % \end{description}
143 % \end{aebQuote}
144 % \paragraph*{Workflow.} The package is designed for the following workflow:
145 % \begin{enumerate}
146 % \item The instructor creates the quiz using the \pkg{exerquiz} and
147 % \pkg{eq-pin2corr} packages.
148 % \item The instructor delivers the ``PDF quiz'' to each student. (System drive or email)
149 % \item The student takes the quiz. The student can press the \uif{Correct}
150 % but, unless he/she knows the PIN, the quiz is not marked up.
151 % \item The student saves the PDF quiz in \app{Adobe Reader DC}.
152 % \item The student returns the PDF to the instructor. (System drive or email)
153 % \item The instructor presses the \uif{Correct} button to mark up the quiz
154 % and record the grade of the student. The instructor saves the quiz.
155 % \item The instructor returns the PDF, at some point, to the student.
156 % \item Both instructor and student happily go on with their lives.
157 % \end{enumerate}
158 % \section{Options and package requirements}
159 % \begin{macrocode}
160 \newif\ifPINshowScore \PINshowScorefalse
161 \DeclareOption{showscore}{\PINshowScoretrue}
162 \DeclareOption{!showscore}{\PINshowScorefalse}
163 \ProcessOptions\relax
164 \RequirePackage{exerquiz}[2021/05/21]
165 \RequirePackage{eq-save}[2021/04/27]
166 % \end{macrocode}
167 % \section{Package commands}
168 % Implement local versions\DescribeMacro{\showScoreOn}\DescribeMacro{\showScoreOff}{} of the package options \opt{showscore} and \opt{!showscore},
169 % these are \cs{showScoreOn} and \cs{showScoreOff}.
170 % \begin{macrocode}
171 \def\showScoreOn{\PINshowScoretrue}
172 \def\showScoreOff{\PINshowScorefalse}
173 % \end{macrocode}
174 % \subsection{PIN security on the \textsf{Correct} control}
175 % Define \DescribeMacro{\SaveAndSendMsg} a message that appears on the console when the PIN entered is not correct.
176 % \begin{macrocode}
177 \flJSStr[noquotes]{\SaveAndSendMsg}{Success! %
178 Now save and send to the instructor}
179 % \end{macrocode}
180 % \DescribeMacro\postSubmitQuizPIN
181 % Begin by modifying the \cs{postSubmitQuiz} command,
182 % which is a hook within the executing code of the \uif{End Quiz} control.
183 % \begin{macrocode}
184 \begin{defineJS*}[\makeesc\@\makecmt\%]{\postSubmitQuizPIN}
185 // Begin post submit quiz code%
186 @ifPINSecurity%
187 @ifPINshowScore@else
188 var f = this.getField("ScoreField.@oField");
189 if ( f!=null ) {
190 f.textSize=0;
191 f.value = "@SaveAndSendMsg";
192 } else {
193 var f = this.getField("PointsField.@oField");
194 if (f!=null) {
195 f.textSize=0;
196 f.value = "@SaveAndSendMsg";
197 }
198 }@fi@fi
199 oRecordOfQuizData["ScoreData.@oField"]=%
200 [1*Score,1*NQuestions,1*ptScore,1*NPointTotal];
201 oRecordOfQuizData["RightWrong.@oField"]=%
202 eval(RightWrong.toSource());
203 oRecordOfQuizData["ProbDist.@oField"]=%
204 eval(ProbDist.toSource());
205 cntCorrectResponses();
206 \end{defineJS*}
207 % \end{macrocode}
208 % The command name for the action of the \uif{End Quiz} control is
209 % \DescribeMacro{\eQzBtnActns}\cs{eQzBtnActns}.
210 % We save this and pre-pend a single code line, as needed.
211 % \begin{macrocode}
212 \let\eQzBtnActnsSave\eQzBtnActns
213 \def\makeEndQuizPIN{%
214 \let\eQzBtnActns\eQzBtnActnsPIN
215 \let\postSubmitQuiz\postSubmitQuizPIN
216 }
217 \def\eQzBtnActnsPIN{\ifPINshowScore\else
218 var bDisplaySilent=true;\r\fi
219 \eQzBtnActnsSave
220 }
221 %\makeEndQuizPIN
222 % \end{macrocode}
223 % The command name for the action of the \uif{Correct} control is \cs{CorrBtnActionsJS}
224 % we save this and later modify it.
225 % \begin{macrocode}
226 \let\CorrBtnActionsJSSave\CorrBtnActionsJS
227 % \end{macrocode}
228 % We can turn on and off the PIN feature by expanding \DescribeMacro{\usePINCorrBtn}
229 % \cs{usePINCorrBtn} and \DescribeMacro{\restoreCorrBtn}\cs{restoreCorrBtn}.
230 % \begin{macrocode}
231 \newif\ifPINSecurity \PINSecurityfalse
232 \def\usePINCorrBtn{\PINSecuritytrue
233 \makeEndQuizPIN % dps5-25
234 \let\CorrBtnActionsJS\CorrBtnActionsPwdJS}
235 \def\restoreCorrBtn{\PINshowScoretrue\PINSecurityfalse
236 \restoreEndQuiz % dps5-25
237 \let\CorrBtnActionsJS\CorrBtnActionsJSSave}
238 % \end{macrocode}
239 % The instructor can tediously press the \uif{Correction} button, or place
240 % an entry,
241 %\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small,
242 %commandchars={!()},codes={\catcode`\%=9}]
243 %var _PinCode1 = "02JRVZdRgYgCA-Rtje8VkD";
244 %\end{Verbatim}
245 %in the file \texttt{config.js}. If such a variable exists and its value
246 %matches the PIN hash string, the instructor clicks the \uif{Correction} button
247 %to get the quiz markup. Conceivably, the instructor might want different PIN names
248 %and string hash values. The \DescribeMacro\classPINVar\cs{classPINVar} is a convenient
249 %way of declaring the PIN variable name; eg, if |\classPINVar{_PinCode1}| is declared
250 %prior to the \env{quiz} environment, the instructor need not manually enter the PIN.
251 %\changes{v1.1}{2021/05/22}{Added \string\cs{ifFreezeQuiz} switch and \string\cs{FreezeThisQuiz}
252 %convenience macro}
253 % \begin{macrocode}
254 \def\classPINVar#1{\def\PINclassPV{#1}}
255 \let\PINclassPV\@empty
256 % \end{macrocode}
257 % \DescribeMacro\FreezeThisQuiz
258 % Causes the interactive parts of a quiz to be readonly. This can be passed
259 % into the \uif{End Quiz} control so that when the student presses \uif{End Quiz}
260 % the quiz will be frozen (after a warning); or through the \uif{Correct} button,
261 % then the returned quiz will be readonly.
262 % \begin{macrocode}
263 \newif\ifFreezeQuiz\FreezeQuizfalse
264 \def\FreezeThisQuiz{\FreezeQuiztrue}
265 \def\FreezeThisQuizNot{\FreezeQuizfalse}
266 % \end{macrocode}
267 % \DescribeMacro\CorrBtnActionsPwdJS
268 % The modified action for the \uif{Correct} button.
269 % we save this and later modify it.
270 % \begin{macrocode}
271 \begin{defineJS*}[\makeesc\|\makecmt\%]{\CorrBtnActionsPwdJS}
272 |ifx|PINclassPV|@empty%
273 var userPIN = "";|else%
274 var userPIN = "|PINclassPV";|fi
275 if (userPIN == "") userPIN = undefined;
276 try {
277 if ( typeof eval(userPIN) == "undefined") userPIN = undefined;
278 } catch(e) { userPIN = undefined; }
279 if (typeof userPIN == "undefined") {
280 var resp=app.response({
281 cQuestion: "Enter the PIN number",
282 cTitle: "View Answers",
283 bPassword: true
284 });
285 var _resp=Collab.hashString(resp);
286 if (resp != null) var _bQzResults = ( _resp ==_PinCode );
287 } else var _bQzResults = ( eval(userPIN) ==_PinCode );
288 if (_bQzResults) {
289 % \end{macrocode}
290 % (2021/05/24) Do nothing if no quiz data
291 % \begin{macrocode}
292 if (typeof oRecordOfQuizData["ScoreData.|currQuiz"]!="undefined") {
293 RightWrong=eval("RightWrong.|currQuiz");
294 ProbDist=eval("ProbDist.|currQuiz");
295 correctQuiz("|currQuiz",3);
296 DisplayQuizResults("|currQuiz",3,3);
297 if (typeof correctSumryTbl == "function")
298 correctSumryTbl("|currQuiz",3);%
299 % \end{macrocode}
300 % (2021/05/22) If \cs{ifFreezeQuiz} is true, we add some code to freeze all operational
301 % components of this quiz.
302 % \begin{macrocode}
303 |ifFreezeQuiz
304 var aFrzExt=new Array("obj.","grpobj.","essay.",%
305 "beginQuiz.","endQuiz.");
306 for (var i=0; i<aFrzExt.length; i++) {
307 var f=this.getField(aFrzExt[i]+"|currQuiz");
308 if (f!=null) f.readonly=true;
309 }|fi
310 } else {
311 var retn=app.alert({%
312 cMsg: "No quiz data, do you want to mark it anyway?",%
313 cTitle: "AcroTeX", nIcon: 2, nType: 2});
314 if (retn==4) {
315 var bDisplaySilent=false;
316 InitializeQuiz("|currQuiz",1,0);
317 var f=this.getField("ScoreData.|currQuiz");
318 f.value="0;0;0;0";
319 cntCorrectResponses();
320 correctQuiz("|currQuiz",3);
321 DisplayQuizResults("|currQuiz",3,3,false);
322 if (typeof correctSumryTbl == "function")
323 correctSumryTbl("|currQuiz",3);
324 }
325 }
326 } else {
327 if (resp != null) {
328 console.clear()
329 console.println("Something went wrong, %
330 you entered an incorrect PIN Id, %
331 or the class PIN Id (\\\\classPINVar) was incorrect or undefined");
332 app.beep(0);
333 console.show();
334 }
335 }
336 \end{defineJS*}
337 % \end{macrocode}
338 %
339 % \subsection{Declare PIN for \textsf{Correction} and \textsf{Begin Quiz} controls}
340 % Two PIN-related commands are defined: (1) \cs{declPINId} is for security on the
341 % \uif{Correct} control; (2) \cs{declRePINId} is for security on the \uif{Begin Quiz}
342 % control.\medskip
343 %
344 % \noindent\DescribeMacro\declPINId\hskip-\marginparsep\texttt{\darg{\ameta{PIN-Id}}\darg{\ameta{hash-str}}}
345 % Set the basic parameters of this PIN security scheme for the \uif{Correct} control:
346 % the pin-id and its corresponding hash-string.
347 % \begin{macrocode}
348 \def\declPINId#1#2{\def\numPINId{#1}\def\hashPINId{#2}}
349 \@onlypreamble\declPINId
350 \declPINId{5243}{02JRVZdRgYgCA-Rtje8VkD} % PIN Id, hash-str
351 % \end{macrocode}
352 % \DescribeMacro\declRePINId\hskip-\marginparsep\texttt{\darg{\ameta{PIN-Id}}\darg{\ameta{hash-str}}}
353 % Set the basic parameters of this PIN security scheme on the \uif{Begin Quiz} control:
354 % the pin-id and its corresponding hash-string.
355 % \begin{macrocode}
356 \def\declRePINId#1#2{\def\numRePINId{#1}\def\hashRePINId{#2}}
357 \@onlypreamble\declRePINId
358 \declRePINId{1234}{By9mbLF0NJMA2sN2x4D0VB}
359 \begin{insDLJS}{pin}{Pin Code}
360 var _PinCode = "\hashPINId";
361 var _rePinCode = "\hashRePINId";
362 \end{insDLJS}
363 % \end{macrocode}
364 % \subsection{Warn and Freeze on \textsf{End Quiz}}
365 % \DescribeMacro\useWarnEndQuiz
366 % (2021/05/22) Optional modifications to the \uif{End Quiz} control.
367 % \changes{v1.1}{2021/05/22}{Define \string\cs{useWarnEndQuiz} and
368 % \string\cs{EndQuizG@tePIN}}
369 % \begin{macrocode}
370 \def\useWarnEndQuiz{\let\EndQuizG@te\EndQuizG@tePIN}
371 \flJSStr{\EndQuizG@te@Msg}{Warning:
372 Are you sure you want to end this quiz?\r\r
373 The quiz will be frozen and no more changes will be allowed.
374 Click 'Yes' to end the quiz or 'No' to continue working on the quiz.}
375 \def\PINgobii#1#2{}
376 \begin{defineJS}[\makeesc\|\makecmt\%]{\EndQuizG@tePIN}
377 // Begin insertion of new code
378 var retn=app.alert({cMsg: |EndQuizG@te@Msg,%
379 cTitle: "AcroTeX", nIcon: 2, nType: 2});
380 if (retn==4) {
381 % \end{macrocode}
382 % Freeze this quiz; we make a relevant fields readonly.
383 % \begin{macrocode}
384 var aFrzExt=new Array("mc.","obj.","grpobj.",%
385 "beginQuiz.","endQuiz.");
386 for (var i=0; i<aFrzExt.length; i++) {
387 var f=this.getField(aFrzExt[i]+"|currQuiz");
388 if (f!=null) f.readonly=true;
389 }%
390 |PINgobii
391 \end{defineJS}
392 % \end{macrocode}
393 % The \cs{PINglobii} vacuums up `\verb*! {!', which appears in \cs{eQzBtnActns} of
394 % \pkg{exerquiz}, in the line \verb*!*EndQuizG@te {!.
395 %
396 % \subsection{PIN Security on \textsf{Begin Quiz}}
397 %
398 % \DescribeMacro\useBeginQuizPIN (2021/05/29) This command redefines the \uif{Begin Quiz} control to
399 % require PIN security to retake the quiz.
400 % \changes{v2.0}{2021/05/29}{Define \string\cs{useBeginQuizPIN}}
401 % \begin{macrocode}
402 \def\useBeginQuizPIN{%
403 \ifx\BeginQuizG@te\BeginQuizG@tePIN\else
404 \let\BeginQuizG@te\BeginQuizG@tePIN\fi}
405 % \end{macrocode}
406 % \cs{restoreBeginQuiz} is defined in \pkg{exerquiz}, but because of a typo,
407 % it was originally defined as \cs{restorBeginQuiz} (no `e'); until the changes trickle
408 % through the system, we cover ourselves by \cs{let}ing \cs{restoreBeginQuiz}
409 % to \cs{restorBeginQuiz}, if the correct spelling of the command does not already
410 % exist.
411 % \begin{macrocode}
412 \@ifundefined{restoreBeginQuiz}{\let\restoreBeginQuiz\restorBeginQuiz}{}
413 % \end{macrocode}
414 % \begin{macrocode}
415 \flJSStr{\BeginQuizG@te@Msgi}{Enter the PIN number
416 to retake this quiz}
417 \flJSStr{\BeginQuizG@te@Msgii}{Press the Begin Quiz control to begin
418 the quiz again}
419 \def\PINgobiii#1#2#3{}
420 % \end{macrocode}
421 % \begin{macrocode}
422 \begin{defineJS}[\makeesc\|\makecmt\%]{\BeginQuizG@tePIN}
423 if (typeof oRecordOfQuizData["ScoreData.|currQuiz"] != "undefined" ) {
424 var resp=app.response({
425 cQuestion: |BeginQuizG@te@Msgi,
426 cTitle: "AcroTeX",
427 bPassword: true
428 });
429 var _respHash=_resp=Collab.hashString(resp);
430 if (_resp == _rePinCode) {
431 oRecordOfQuizData["ScoreData.|currQuiz"]=undefined;
432 app.alert(|BeginQuizG@te@Msgii);
433 var f=this.getField("tallyresets.|currQuiz");
434 if (f!=null) f.value=1+f.value;
435 }
436 } else {
437 |PINgobiii
438 \end{defineJS}
439 % \end{macrocode}
440 % \cs{PINglobiii} gobbles the three tokens `\verb*! {\jsR!', which appear in the definition of \cs{@initQuiz} in
441 % \pkg{exerquiz}, in the line \verb*!\BeginQuizG@te\space\jsLB\jsR\jsT!.
442 %
443 % \section{Tracking the number of \textsf{Begin Quiz} events}
444 % A command \cs{qzResetTally} is defined to hold the number of times a user has taken
445 % the same quiz. This field is readonly, and does not reset, unless you have know how to do it.
446 % \begin{macrocode}
447 % \end{macrocode}
448 % \DescribeMacro{\qzResetTally}\hskip-\marginparsep\texttt{[\ameta{options}]}
449 % The \cs{qzResetTally} text field, similar to \cs{sqTallyTotal}, is used to
450 % count the number of times a student needs to retake the same quiz.
451 % \begin{macrocode}
452 % \end{macrocode}
453 % The default appearance of \cs{qzResetTally}
454 % \begin{macrocode}
455 \def\qzTallyTotalDefaults{%
456 \rawPDF{}\W{1}\BC{0 0 0}\S{I}\textColor{1 0 0 rg}
457 \Q{2}}
458 % \end{macrocode}
459 % The definition of \cs{qzResetTally}
460 % \begin{macrocode}
461 \newcommand\qzResetTally[1][]{%
462 \textField[\presets{\qzTallyTotalDefaults}#1\DV{0}\V{0}
463 \Ff{\FfReadOnly}
464 ]{tallyresets.\currQuiz}{\TBW}{\DefaultHeightOfWidget}}
465 % \end{macrocode}
466 % \subsection{Placing a maximum on the number of resets}
467 % The next level of complication is to add a restriction onto the number of
468 % times the user can retake the quiz.\medskip\par
469 %
470 % \noindent
471 % \DescribeMacro\setMaxRetakes\hskip-\marginparsep\texttt{\darg{\ameta{qz-name}}\darg{\ameta{num}}}
472 % A command that sets the maximum number of retakes \ameta{num} (nonneg integer) by declaring \cs{setMaxRetakes} prior
473 % to the quiz \ameta{qz-name}. \DescribeMacro\nMaxRetakes\cs{nMaxRetakes\darg{\ameta{qz-name}}}
474 % is a public macro that expands to the max number of retakes (\ameta{num}).
475 % \begin{macrocode}
476 \newcommand{\setMaxRetakes}[2]{\expandafter
477 \def\csname1MaxReset#1\endcsname{#2}}
478 \def\nMaxRetakes#1{\@nameuse{1MaxReset#1}}
479 % \end{macrocode}
480 % \subsection{JavaScript support for tracking}
481 % \DescribeMacro\useBeginQuizCnt Modifies \cs{BeginQuizG@te} (\pkg{exerquiz}, 2021/05/21 or later).
482 % \cs{useBeginQuizPIN} also modifies \cs{BeginQuizG@te}. These two are incompatible;
483 % one will overwrite the other. \cs{restoreBeginQuiz} retores \uif{Begin Quiz} to its default definition.
484 % \changes{v2.0}{2021/05/29}{Define \string\cs{useBeginQuizCnt}}
485 % \begin{macrocode}
486 \def\useBeginQuizCnt{%
487 \ifx\BeginQuizG@te\BeginQuizG@teCNT\else
488 \let\BeginQuizG@te\BeginQuizG@teCNT\fi}
489 % \end{macrocode}
490 % \DescribeMacro\maxRetake@Msg The message that appears in an alert dialog box
491 % after the student has started the quiz more than the max number, as set by
492 % \cs{setMaxRetakes}.
493 % \begin{macrocode}
494 \flJSStr[noquotes]{\maxRetake@Msg}{You have taken the quiz the maximum
495 number of times permitted ("+nMaxReset+"). You will not be allowed to
496 continue to re-take this quiz. Move on with your life.}
497 % \end{macrocode}
498 % The action added to \uif{Begin Quiz}, it determines if \cs{qzResetTally} is present for the current quiz
499 % and if so, increments the current value.
500 % \begin{macrocode}
501 \begin{defineJS}[\makeesc\|\makecmt\%]{\BeginQuizG@teCNT}
502 if (typeof oRecordOfQuizData["ScoreData.|currQuiz"] != "undefined" )
503 {
504 var _bOKReset=true;
505 var f=this.getField("tallyresets.|currQuiz");
506 if (f!=null) var value=1*f.value;%
507 |expandafter|ifx|csname1MaxReset|currQuiz|endcsname|relax|else
508 var nMaxReset=|csname1MaxReset|currQuiz|endcsname;
509 if (f!=null && value==nMaxReset) {
510 app.alert("|maxRetake@Msg");
511 _bOKReset=false;
512 }|fi
513 if (_bOKReset) {
514 oRecordOfQuizData["ScoreData.|currQuiz"]=undefined;
515 app.alert(|BeginQuizG@te@Msgii);
516 if (f!=null) f.value=1+value;
517 }
518 } else {
519 |PINgobiii
520 \end{defineJS}
521 % \end{macrocode}
522 % \cs{PINglobiii} gobbles the three tokens `\verb*! {\jsR!', which appear in the definition of \cs{@initQuiz} in
523 % \pkg{exerquiz}, in the line \verb*!\BeginQuizG@te\space\jsLB\jsR\jsT!.
524 % \begin{macrocode}
525 %</package>
526 % \end{macrocode}
527 %\Finale