summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sdaps/html/_sources/customlayout.rst.txt
blob: 87c553ce0522edf12c918b929ef6f299f90d9aa6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
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.

.. sdaps:: Question with one checkbox
    :sdapsclassic:
    :metadata:

    % 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}

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!

    .. sdaps:: Question inside tabularx
        :preamble: \usepackage{tabularx}
        :sdapsclassic:
        :metadata:

        % 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}


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.

.. sdaps:: Grouping questions
    :sdapsclassic:
    :metadata:

    % 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}


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.

.. sdaps:: Multiple choice question using itemize
    :sdapsclassic:
    :metadata:

    % 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}

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.

.. sdaps:: Single choice question using itemize
    :sdapsclassic:
    :metadata:

    % 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}

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, …).

.. sdaps:: Range question
    :sdapsclassic:
    :metadata:

    % 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}

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:

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.

.. sdaps:: Codebox question and field
    :sdapsclassic:
    :metadata:
    :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

    \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}