Repository navigation
Expand file tree
/
Copy pathMatchModule.tex
More file actions
250 lines (193 loc) · 11.3 KB
/
Copy pathMatchModule.tex
File metadata and controls
250 lines (193 loc) · 11.3 KB
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
\startcomponent[MatchModule]
\starttext
\section[iterating-to-match-the-oral-history-module]{Iterating to Match the Oral History Module}
Now that we've created a very straightforward version of the Oral History module, let's layer in some additional features. By the end of this section, we will have discussed all the steps that went into making the version of the Oral History Module you can download from the FAIMS Demo Server.
Select \quotation{Demo Server} from the dropdown menu in the FAIMS setting menu, then download the \quotation{finished} version of the Oral History module. Our goal in this section will be to update the version you produced to match this more complex iteration.
\placefigure[force][OHD]{Tap \quotation{Oral History Demo} to download.}{\externalfigure[image48.png][width=.5\textwidth]}
The Oral History module has a bit more metadata information included than the version we've already discussed. You can update this information in the \quotation{Module} tab on your FAIMS server installation.
\placefigure[force][OHD-metadata]{More detailed metadata.}{
\startcombination[2*1]
{\externalfigure[image33.png][width=.5\textwidth]}{}
{\externalfigure[image59.png][width=.5\textwidth]}{}
\stopcombination
}
The first screen of the Oral History Demo (\in{Figure}[user-list]) looks similar to our module.
\placefigure[force][user-list]{Match your model to \quotation{Oral History Demo} by adding a User List.}{\externalfigure[image31.png][width=.5\textwidth]}
In the same {\tt module.xml} file we used for our version of Oral History update the code in \in{Codeblock}[codeOutdatedUserList] to match \in{Codeblock}[codeUpdatedUserList] (new code in a dark gray background).
%TODO: change the above to new code in {\bf bold} once a font with a nice bold has been chosen
\placecode[here][codeOutdatedUserList]{Current code.}{
\startXML
<User f="nodata">
<User>
<Select_User t="dropdown" f="user"/>
<Login t="button" l="Control"/>
</User>
</User>
\stopXML
}
\placecode[here][codeUpdatedUserList]{This code replicates \quotation{Oral History Demo}.}{
\startXML
<User f="nodata">
\stopXML
\startChange
<User_List>
<Users t="list" f="user" l="Control">
Users:
</Users>
</User_List>
\stopChange
\startXML
</User>
\stopXML
}
This replicates the \quotation{User List} tab illustrated in the above screenshot.
Save your modified {\tt module.xml}, run {\tt ./generate.sh} in your Ubuntu terminal again, edit your current module and upload the new necessary files in place of the old ones. Now download this updated module to your FAIMS app.
Importantly, to download the updated version of the module, you must touch and hold the \quotation{Simple Sample Module} in the list of modules until the dialogue in \in{Figure}[SSM-popup] is displayed.
\placefigure[force][SSM-popup]{Tap and hold \quotation{Simple Sample Module} to open this pop-up.}{\externalfigure[image14.png][width=.5\textwidth]}
Tap \quotation{Update}, then \quotation{Update Settings}, wait for the update to occur, and finally load the module as usual.
\alert{\bf Note: While we can update Simple Sample Module to have an interface that mimics the Oral History module, we're going to make some changes that will make the module not completely functional. This is because, as you may recall, you can't change the Data Schema of a module once it's already been uploaded to the server. So the interface elements will look right, because the necessary files that govern those can be changed out freely, but the parts actually responsible for managing the data you collect to the server won't have gotten the memo that the module's been altered. If this weren't an exercise, and we wanted an absolutely functional module, we'd just create a new one from the updated necessary files and tell our team members to switch to it.}
\placefigure[force][OHD-control]{\quotation{Oral History Demo} combines \quotation{Main} and \quotation{Record} into \quotation{Control}.}{\externalfigure[image24.png][width=.5\textwidth]}
On the screen in \in{Figure}[OHD-control], we need to condense a few elements from our original module. Change the code in \in{Codeblock}[codeOutdatedCondenseTabs] to match the code in \in{Codeblock}[codeUpdatedCondenseTabs].
\placecode[here][codeOutdatedCondenseTabs]{Current code.}{
\startXML
<Control f="nodata">
<Main>
<Record_Interview t="button" l="Interview"/>
<GPS_Diagnostics t="gpsdiag"/>
</Main>
<search>
Records
</search>
</Control>
\stopXML
}
\placecode[here][codeUpdatedCondenseTabs]{Condense \quotation{Main} and \quotation{Record} into \quotation{Control}.}{
\startXML
<Control f="nodata">
\stopXML
\startChange
<Control>
<New_Oral_History_Form t="button" l="Form"/>
<New_Diary t="button" l="Diary"/>
<GPS_Diagnostics t="gpsdiag"/>
<Sample_Types t="dropdown" />
<List_of_Samples t="list" />
</Control>
\stopChange
\startXML
</Control>
\stopXML
}
\in{Codeblock}[codeUpdatedCondenseTabs] replaces the \quotation{Main} and \quotation{Record} tab groups with a single one labelled \quotation{Control}. (In a moment, we will define the \quotation{Form} and \quotation{Diary} tab groups linked to by the above buttons. We will also have to populate the \quotation{Sample Types} dropdown and \quotation{List of Samples} list by writing some additional code.)
Save {\tt module.xml} and run the {\tt generate.sh} script again. Now use them to update your module again. You should see something similar to \in{Figure}[SSM-control] after selecting a user in the uploaded module.
\placefigure[force][SSM-control]{\quotation{Control} tab in your updated module.}{\externalfigure[image8.png][width=.5\textwidth]}
For the next step, we'll add new UI tab groups for each of our buttons: \quotation{Form} and \quotation{Diary} that we linked to in \in{Codeblock}[codeFormDiary].
\placecode[here][codeFormDiary]{Add \quotation{Form} and \quotation{Diary} tab groups.}{
\startXML
<Form>
<Recording_Form>
</Recording_Form>
<Interview_Details>
</Interview_Details>
<Main_Subjects>
</Main_Subjects>
</Form>
<Diary>
<Diary>
</Diary>
</Diary>
\stopXML
}
Make sure that the \inlXML{<Form>} and \inlXML{<Diary>} elements are written directly within \inlXML{<module>} so that the FAIMS-Tools correctly interprets them as tab groups. It may help, when drafting new elements, to write both the opening and closing tags and then fill in the middle.
Now, under each of these new tab groups, we'll create individual tabs. The \quotation{Form} group has three tabs: \quotation{Recording Form}, \quotation{Interview Details}, and \quotation{Main Subjects}. Note that if these tab titles contain multiple words, you must use underscores between each word. When FAIMS creates the title for each tab, underscores will be replaced with spaces.
\placefigure[force][empty-tab]{Three newly created empty tabs.}{\externalfigure[image53.png][width=.5\textwidth]}
Now we have the individual tabs for each section, but those tabs don't have any content just yet. For simple text fields, like \quotation{Birth Place} and \quotation{Parents' Birth Place} you can simply add a self-closing tag with the field's title as in \in{Codeblock}[codeBirthPlace].
\placecode[here][codeBirthPlace]{A self-closing \quotation{Birth Place} tag.}{
\startXML
<BIRTH_PLACE/>
\stopXML
}
Also, non-alphabetical characters, like apostrophes are not allowed as tag names in XML, so the FAIMS-Tools would fail to generate a module which contains the code in \in{Codeblock}[codeApostropheFail].
\placecode[here][codeApostropheFail]{The apostrophe causes this to fail.}{
\startXML
<PARENTS'_BIRTH_PLACE:/>
\stopXML
}
If such characters must be included, the solution is to firstly give the element a sensible name without an apostrophe or colon as in \in{Codeblock}[codeApostropheFix].
\placecode[here][codeApostropheFix]{First name the element without an apostrophe.}{
\startXML
<PARENTS_BIRTH_PLACE/>
\stopXML
}
Then, to make FAIMS-Tools display the apostrophe and colon in the GUI, write them as the element's text as in \in{Codeblock}[codeApostropheFix2].
\placecode[here][codeApostropheFix2]{Write any special characters in the element's text.}{
\startXML
<PARENTS_BIRTH_PLACE>
PARENTS' BIRTH PLACE:
</PARENTS_BIRTH_PLACE>
\stopXML
}
This is similar to what we did with the \quotation{search} feature in the last section.
Now, note that every tab group which you intend to save requires at least one {\em identifier}. In the original Oral History module, the identifiers were \inlXML{PERSON} and \inlXML{LANGUAGE_GROUP}. We can use the \inlXML{f} attribute to denote that in our new module as in \in{Codeblock}[codeDenoteID].
\placecode[here][codeDenoteID]{Denoting an {\em identifier}.}{
\startXML
<PERSON f="id"/>
<LANGUAGE_GROUP f="id"/>
\stopXML
}
For the GPS fields and their corresponding \quotation{Take From GPS} button, refer to \in{Codeblock}[codeGPS]. \inlXML{<gps>} is a special, self-contained shortcut tag that FAIMS will replace with several fields for the latitude, longitude, Easting, and Northing, as well as a button for inserting this data from GPS.
\placecode[here][codeGPS]{XML for GPS fields and button.}{
\startXML
<gps/>
\stopXML
}
To add fields for attached files, you can use the {\tt Audio} and {\tt Video} tags, as in \in{Codeblock}[codeAVtag]. Simply set the type \inlXML{t} to video or audio as required.
\placecode[here][codeAVtag]{XML for attaching audio and visual files.}{
\startXML
<Attached_Audio_Files t="audio"/>
<Attached_Videos t="video"/>
\stopXML
}
\placefigure[force][input-examplees]{Examples of simple text fields, GPS input, and attaching files.}{
\startcombination[3*1]
{\externalfigure[image26.png][width=.3\textwidth]}{}
{\externalfigure[image15.png][width=.3\textwidth]}{}
{\externalfigure[image52.png][width=.3\textwidth]}{}
\stopcombination
}
To add the radio buttons, use the code in \in{Codeblock}[codeRadioButtons].
\placecode[here][codeRadioButtons]{XML for radio buttons.}{
\startXML
<Recorded t="radio">
Recorded?
<opts>
<opt>Recorded</opt>
<opt>Notes Only</opt>
<opt>No</opt>
</opts>
</Recorded>
\stopXML
}
Note that to have the radio buttons' contents appear would require that the entire module is re-created and uploaded to the FAIMS server. Updating the existing module on the server, would cause the menu to appear but lack its options.
\placefigure[force][radio-buttons]{Radio buttons in \quotation{Interview Details} and a simple text field in \quotation{Main Subjects}.}{
\startcombination[2*1]
{\externalfigure[image42.png][width=.5\textwidth]}{}
{\externalfigure[image49.png][width=.5\textwidth]}{}
\stopcombination
}
The \quotation{Timestamp} and \quotation{Created By} values are not actually fields that we'll allow users to enter in manually, so we won't put in a data entry field. Instead, we'll make FAIMS set and update these fields when the record is created. Since there's no simple shortcut for that, for now we'll put in the code in \in{Codeblock}[codeTimeCreated].
\placecode[here][codeTimeCreated]{XML for \quotation{Timestamp} and \quotation{Created by}.}{
\startXML
<Timestamp/>
<Created_by/>
\stopXML
}
There's actually not a lot more we can do until we've generated our necessary files. Then, we'll take {\tt ui_logic.bsh} and make a few alterations that make use of these tags.
\placefigure[force][autofill]{\quotation{Timestamp} and \quotation{Created by} are automatically filled in by FAIMS.}{
\startcombination[2*1]
{\externalfigure[image37.png][width=.5\textwidth]}{}
{\externalfigure[image1.png][width=.5\textwidth]}{}
\stopcombination
}
\stoptext
\stopcomponent