Creating custom layouts using base commands

Usually the pre-defined layouts that SDAPS provides are sufficent. However, there may be special cases that need more customization. Such customization is possible, but it does require a more in depth understanding of LaTeX and the SDAPS packages.

If you do this, please make sure to properly test the output. The easiest way of such testing is to use the annotate command that SDAPS provides, as it visualises the view that SDAPS has of the questionnaire. Doing this testing is essential as small errors and even side effects of how LaTeX executes code may render the information about the questionnaire useless!

Even seemingly “simple” environments like tabularx may not be usable together with SDAPS!

General question structure

To define a question, you need to define 1. the start of the question and its type, 2. the possible answers to the question 3. the checkboxes and textboxes, and finally 4. the end of the question.

A very simple example might look like the following.

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mycheckbox\sdaps_checkbox:nn
\let\myanswer\sdaps_answer:n
\let\myquestionend\sdaps_qobject_end:n
\ExplSyntaxOff

\myquestionbegin{name}{Choice}{Exported question text}
Please check after reading this text: \mycheckbox{}{}
\myanswer{check}
\myquestionend{name}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Choice=1. Exported question text
[13]Box[1]=Checkbox,0,209.5491pt,729.69331pt,9.95845pt,9.95845pt,box,1.00374pt,1_1,1
[14]Answer[1]=check
[15]Variable[1]=1

Question with one checkbox

Please have a look at the resulting document and the generated metadata. In particular, please note:

• The export shows “QObject-Choice” this is from the Choice specified and denotes the question type

• The name argument does not show up. It only needs to match the one at the end and primarily serves error detection purposes.

• SDAPS will see the question as “Exported question text” with one answer “check”

• The checkbox is automatically exported including its coordinates

Warning

Be careful! The below example shows the effect that tabularx has. This environment expands its content multiple times, and the result is that the automatic numbering breaks; making this the 3rd question rather than the first! Other subtle errors like this can occur with certain environments, so make sure to double check everything is OK!

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mycheckbox\sdaps_checkbox:nn
\let\myanswer\sdaps_answer:n
\let\myquestionend\sdaps_qobject_end:n
\ExplSyntaxOff

\begin{tabularx}{\textwidth}{|X|}
  \myquestionbegin{name}{Choice}{The tabularx environment breaks everything ...}
  Please check after reading this text: \mycheckbox{}{}
  \myanswer{check}
  \myquestionend{name}
\end{tabularx}

Required code in preamble:

\usepackage{tabularx}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[20]QObject-Choice=3. The tabularx environment breaks everything ...
[21]Box[3]=Checkbox,0,215.9491pt,719.40335pt,9.95845pt,9.95845pt,box,1.00374pt,3_1,1
[22]Answer[3]=check
[23]Variable[3]=3

Question inside tabularx

The different question types

Headings

This is the easiest case, and it can be used for structuring the document.

For example, the \section command simply calls \sdaps_qobject_begin:nnn { section }{ Head }{ #1 } and \sdaps_qobject_end:n { section } for you. Something similar happens for the choicegroup and other grouping environments where a heading is defined for all questions.

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\myquestionend\sdaps_qobject_end:n
\ExplSyntaxOff

\myquestionbegin{heading}{Head}{Heading}
  Something inside the section.
\myquestionend{heading}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Head=1. Heading
[13]Variable[1]=1

Grouping questions

Multiple choice

The simple multiple choice question is of type Choice. We already saw the first example earlier. Simply add more checkboxes and answers as needed. SDAPS will match each checkbox to one answer in the order that it finds the defintions.

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mycheckbox\sdaps_checkbox:nn
\let\myanswer\sdaps_answer:n
\let\myquestionend\sdaps_qobject_end:n
\ExplSyntaxOff

\myquestionbegin{name}{Choice}{Attended events}
Which of the following events did you attend?
\begin{itemize}
  \item[\mycheckbox{}{}] \myanswer{Keynote} The Keynote
  \item[\mycheckbox{}{}] \myanswer{Workshop} A workshop
  \item[\mycheckbox{}{}] \myanswer{Party} Our glorious party
  \item Something else entirely \myanswer{other}
    \ExplSyntaxOn
      \sdaps_textbox_hstretch:nnnnn{}{2mm}{5mm}{40mm}{1}
    \ExplSyntaxOff
\end{itemize}
\myquestionend{name}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Choice=1. Attended events
[14]Answer[1]=Keynote
[13]Box[1]=Checkbox,0,46.08492pt,712.58836pt,9.95845pt,9.95845pt,box,1.00374pt,1_1,1
[16]Answer[1]=Workshop
[15]Box[1]=Checkbox,0,46.08492pt,694.27495pt,9.95845pt,9.95845pt,box,1.00374pt,1_2,2
[18]Answer[1]=Party
[17]Box[1]=Checkbox,0,46.08492pt,675.96153pt,9.95845pt,9.95845pt,box,1.00374pt,1_3,3
[19]Answer[1]=other
[20]Box[1]=Textbox,0,178.93889pt,659.36952pt,384.42575pt,19.9169pt,1.00374pt,1_4,
[21]Variable[1]=1

Multiple choice question using itemize

Note that we placed a textbox rather than a checkbox as one of the possible answers.

Single choice

We can also define a single choice question. For this, we need to make two small adjustments. The first is to use the Option question type. The second is to tell SDAPS that we would like to use the singlechoice style for checkboxes.

The checkbox style change will be in effect for the scope of the question.

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mycheckbox\sdaps_checkbox:nn
\let\myanswer\sdaps_answer:n
\let\myquestionend\sdaps_qobject_end:n
\let\mysetcheckboxtype\sdaps_checkbox_set_type:n
\ExplSyntaxOff

\myquestionbegin{name}{Option}{Attended events}
\mysetcheckboxtype{singlechoice}
Which one of the following events did you attend?
\begin{itemize}
  \item[\mycheckbox{}{}] \myanswer{Talk room A} Talk in room A
  \item[\mycheckbox{}{}] \myanswer{Talk room B} Talk in room B
  \item Something else entirely \myanswer{other}
    \ExplSyntaxOn
      \sdaps_textbox_hstretch:nnnnn{}{2mm}{5mm}{40mm}{1}
    \ExplSyntaxOff
\end{itemize}
\myquestionend{name}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Option=1. Attended events
[14]Answer[1]=Talk room A
[13]Box[1]=Checkbox,0,46.08492pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_1,1
[16]Answer[1]=Talk room B
[15]Box[1]=Checkbox,0,46.08492pt,694.27495pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_2,2
[17]Answer[1]=other
[18]Box[1]=Textbox,0,178.93889pt,678.60309pt,384.42575pt,19.9169pt,1.00374pt,1_3,
[19]Variable[1]=1

Single choice question using itemize

Note that we placed a textbox rather than a checkbox as one of the possible answers.

Ranges

Quite often one has single choice question which represent a value on a range. One could create these using the Option type question, but with Range it becomes more convenient.

Range questions can contain a single range and further answers like “Not applicable”.

The range is specified with a separate command. For the purpose of this command, the first and last box that is part of the range needs to be specified. This is done with a zero based index (i.e. the first checkbox is 0, the second 1, …).

Example LaTeX codeResultMetadata

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mycheckbox\sdaps_checkbox:nn
\let\myanswer\sdaps_answer:n
\let\myrange\sdaps_range:nnn
\let\myquestionend\sdaps_qobject_end:n
\let\mysetcheckboxtype\sdaps_checkbox_set_type:n
\ExplSyntaxOff

\myquestionbegin{name}{Option}{Attended events}
\mysetcheckboxtype{singlechoice}
Did you like the keynote?
\begin{itemize}
  \item
    it was bad
      \mycheckbox{}{} ~
      \mycheckbox{}{} ~
      \mycheckbox{}{} ~
      \mycheckbox{}{} ~
      \mycheckbox{}{} ~
    it was great
  \item[\mycheckbox{}{}] I did not attend the keynote
\end{itemize}
\myrange{lower}{0}{bad}
\myrange{upper}{4}{great}
\myanswer{did not attend}
\myquestionend{name}

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Option=1. Attended events
[13]Box[1]=Checkbox,0,114.51073pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_1,1
[14]Box[1]=Checkbox,0,131.73024pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_2,2
[15]Box[1]=Checkbox,0,148.94975pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_3,3
[16]Box[1]=Checkbox,0,166.16927pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_4,4
[17]Box[1]=Checkbox,0,183.38878pt,712.58836pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_5,5
[18]Box[1]=Checkbox,0,46.08492pt,694.27495pt,9.95845pt,9.95845pt,ellipse,1.00374pt,1_6,6
[19]Range-lower[1]=0,bad
[20]Range-upper[1]=4,great
[21]Answer[1]=did not attend
[22]Variable[1]=1

Range question

Note that lower must always be the earlier checkbox. You can however assign different values to each checkbox using the second parameter to the checkbox command, thereby redefining the numeric value. The main different to the Option question is simply how the question will be represented in the report.

Codeboxes

There is experimental support for code boxes, that is not yet available using a nice wrapper. This can be used to create QR code read fields.

Example LaTeX codeResultMetadata

\myquestionbegin{name}{Text}{This is a QR code question}
\mysettextboxtype{codebox}

Place barcode sticker into the box:
% Note that we use hspace + vrule for sizing here, that is a bit weird but
% a reasonable method of setting a size
\mytexthbox{}{3bp}{ \hspace{8cm} \vrule width 0pt height 3cm depth 2cm }
\myquestionend{name}

Required code in preamble:

% Prepare some stuff so that we can access the specialized commands more easily.
\ExplSyntaxOn
\let\myquestionbegin\sdaps_qobject_begin:nnn
\let\mytexthbox\sdaps_textbox_hbox:nnn
\let\myquestionend\sdaps_qobject_end:n
\let\mysettextboxtype\sdaps_textbox_set_type:n
% Set a global overlay with a nice icon (quite likely, you will just want
% to place text into the hbox below rather than just placing spacing).
\sdaps_context_set:n {
  codebox = {
    centered_text = {
      \begin{tikzpicture}[yscale=-0.1, xscale=0.1]
        \path[draw=black,fill=black,stroke=] (-1,0)
          -- (-1,5) -- (4,5) -- (4,0) -- cycle(7,0) -- (7,5) -- (12,5) -- (12,0) -- cycle(0,1) -- (3,1) -- (3,4)
          -- (0,4) -- cycle(8,1) -- (11,1) -- (11,4) -- (8,4) -- cycle(1,2) -- (1,3) -- (2,3) -- (2,2) -- cycle(5,2) --
          (5,3) -- (6,3) -- (6,2) -- cycle(9,2) -- (9,3) -- (10,3) -- (10,2) -- cycle(5,4) -- (5,6) -- (2,6) -- (2,7)
          -- (6,7) -- (6,4) -- cycle(0,6) -- (0,7) -- (1,7) -- (1,6) -- cycle(7,6) -- (7,7) -- (8,7) -- (8,6) --
          cycle(-1,8) -- (-1,13) -- (4,13) -- (4,8) -- cycle(5,8) -- (5,13) -- (6,13) -- (6,8) -- cycle(7,8) -- (7,9)
          -- (8,9) -- (8,10) -- (7,10) -- (7,13) -- (8,13) -- (8,11) -- (9,11) -- (9,10) -- (10,10) -- (10,9) -- (9,9)
          -- (9,8) -- cycle(10,9) -- (12,9) -- (12,8) -- (10,8) -- cycle(0,9) -- (3,9) -- (3,12) -- (0,12) --
          cycle(1,10) -- (1,11) -- (2,11) -- (2,10) -- cycle(11,10) -- (11,11) -- (12,11) -- (12,10) -- cycle(11,11) --
         (10,11) -- (10,12) -- (9,12) -- (9,13) -- (12,13) -- (12,12) -- (11,12) -- cycle;
       \end{tikzpicture}
    },
  }
}
\ExplSyntaxOff

[1]Author=Author
[2]Title=Title
[3]SDAPSVersion=1.9.10
[4]Duplex=true
[5]PrintQuestionnaireId=0
[6]PageSize=597.50793pt,845.04694pt
[7]Style=qr
[8]CheckMode=checkcorrect
[9]GlobalID=
[10]GlobalIDLabel=
[11]CornerMarkMargin=28.45274pt,28.45274pt,34.1433pt,34.1433pt
[12]QObject-Text=1. This is a QR code question
[13]Box[1]=Codebox,0,204.34308pt,729.6933pt,237.27507pt,148.28625pt,1.00374pt,1_1,
[14]Variable[1]=1

Codebox question and field