Repository navigation
Expand file tree
/
Copy pathExploringSimpleModule.tex
More file actions
325 lines (267 loc) · 23 KB
/
Copy pathExploringSimpleModule.tex
File metadata and controls
325 lines (267 loc) · 23 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
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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
\startcomponent[ExploringSimpleModule]
\starttext
\section{Exploring a Simple Module}
Now that you understand the how the XML structure relates to FAIMS modules, let's explore the simple module we uploaded in the last section.
\placefigure[force][login-screen]{A user login screen.}{\externalfigure[image25.png][width=.5\textwidth]}
To create this first login screen (\in{Figure}[login-screen]), we used the XML code in \in{Codeblock}[codeLoginScreen].
\placecode[here][codeLoginScreen]{XML code for a user login screen.}{
\startXML
<User f="nodata">
<User>
<Select_User t="dropdown" f="user"/>
<Login t="button" l="Control"/>
</User>
</User>
\stopXML
}
The outermost set of \inlXML{<User>} tags comes right after the \inlXML{<module>} tags, so they create a {\bf tab group}. You can name these whatever you want. The only rule you should follow, for reasons we'll get into very shortly, is that it should start with an uppercase letter. The {\em tag name} you write is displayed in the breadcrumb navigation bar at the top of the screen.
Notice that the topmost \inlXML{<User>} tag contains the {\em attribute} \inlXML{f} with an {\em attribute value} of \inlXML{nodata}. Including the word \inlXML{nodata} in the \inlXML{f} attribute's value prevents the FAIMS-Tools from automatically generating unwanted code associated with the data schema. In practical terms: inputs that are provided in the \quotation{User} tab group, including the \quotation{Select User} dropdown menu, are not considered \quotation{data} that must be saved to the FAIMS database. We chose to put \inlXML{nodata} here because we only want the \quotation{User} tab group to be for letting people log in.
Now that we've got our \inlXML{<User>} tab group, it's time to make our actual \inlXML{<User>} tab with its relevant GUI elements. We're naming this tab \quotation{User} as well, because it's where the User logs in and that seems like a good name, but we could have named it something else if we thought we'd get it confused with the tab group. Whatever tag name we choose will be displayed in the list of tabs. When you name a tab group something, its tag name must be capitalized.
The \inlXML{<Select_User>} and \inlXML{<Login>} elements represent GUI elements, or the actual things users will interact with when they're viewing a tab. Notice the \inlXML{t} attribute, which is where we can define part of what this element looks like or does. You'll find a list of these in the FAIMS cookbook. For \inlXML{<Select_User>} we're using \inlXML{t="dropdown"}, which means this GUI element is a drop-down menu.
So how do we determine what's in that drop down menu? In this case, by creating an attribute, \inlXML{f="users"}, which in this context FAIMS understands to mean \quotation{get the list of usernames from the server and put them here.}\footnote{{\bf Note from FAIMS programmer Christian Nassif-Haynes:} If you use \inlXML{t=dropdown}, then it is possible for the user to avoid logging in (in error or intentionally) by selecting the null option and clicking the login button. If you want to prevent logging with the null user option (de facto avoiding the login), then you need to manually modify the {\tt ui_logic.bsh} file after it's been generated or use \inlXML{t=list}, following the guidelines below. Lists, unlike dropdowns, do not allow null elements so using a \inlXML{t="list"} for login, as in the code below, prevents the problem of logging in with null user.
<User f="nodata">
~~<User f="noscroll">
~~~~<Select_User t="list" f="user" l="Control"/>
~~</User>
</User>
}
Setting \inlXML{t="button"}, as in the case of \inlXML{<Login>}, creates a button you can tap. The purpose of the button is described by the text that comes after it; otherwise, it's just a button, which probably isn't going to be very useful for your module. Here we've included the code \inlXML{l="Control"} within the tag, which causes FAIMS to link to the \quotation{Control} tab group when it is tapped. In fact, the \inlXML{l} attribute works not only for buttons, but many other GUI elements as well. Note carefully that the \quotation{Control} tab group linked to by the \inlXML{l} attribute's value is defined further down in the {\tt module.xml} file; this code only functions because the destination is valid. If we had \inlXML{1="Control"} and then didn't actually have a \quotation{Control} to link to, it's safe to say this wouldn't work. Also note that references are case-sensitive, so writing \inlXML{control} with a lower-case \quotation{c} would fail.
So let's say we're using our module, we've just clicked the dropdown menu and chosen our user, then we've hit the button that says \quotation{Login.} If you're using the finished sample module, you'll find yourself looking at the screen in \in{Figure}[main-tab].
\placefigure[force][main-tab]{The \quotation{main} tab.}{\externalfigure[image13.png][width=.5\textwidth]}
Let's take a look at the code for this tab group here. As you review \in{Codeblock}[codeXMLtoFAIMS], see if you can figure out which elements are tab groups, tabs, and GUI elements.
\placecode[here][codeXMLtoFAIMS]{Matching XML to FAIMS elements.}{
\startXML
<Control f="nodata">
<Main>
<Record_Interview t="button" l="Interview"/>
<GPS_Diagnostics t="gpsdiag"/>
</Main>
<search>
Records
</search>
</Control>
\stopXML
}
\placefigure[force][XML-GUI]{How XML in {\tt module.xml} describes different FAIMS Elements.}{\externalfigure[image43.png][width=1\textwidth]}
The XML in {\tt module.xml} describes the different FAIMS elements and how they should appear in the module.
This \quotation{Control} tab group encompasses two other elements, \quotation{Main} and \quotation{Search.} Let's look at each individually.
The \inlXML{<Main>} element creates the first tab. Inside that tab we have a GUI element, \inlXML{Record_Interview.} The \inlXML{t="button"}, which means this element is a button; \inlXML{1="Interview"}, so the button links to another tab somewhere else in the module called \quotation{Interview.} The other GUI element here is \quotation{GPS Diagnostics,} which has the element type \inlXML{gpsdiag.} This element type specifically means that in the final module, it will create text labels and display information about the Android device's GPS location. In the screenshot, we see the \inlXML{gpsdiag} element at work: it's telling us that our phone's GPS is \quotation{not initialized,} a charming way of sayingn \quotation{not turned on.} Until we do turn it on, this is the best \inlXML{gpsdiag} is going to do.
Let's turn on our Android device's internal GPS antenna by tapping \useURL[url22][https://www.youtube.com/watch?v=o_eSwq1ewsU][][{the three vertical dots}]\from[url22] in the upper right of the screen to open the settings menu.
\placefigure[force][on-GPS]{Turn on internal GPS by tapping the dots in the red box.}{
\startcombination[2*1]
{\externalfigure[image45.png][width=.5\textwidth]}{}
{\externalfigure[image34.png][width=.5\textwidth]}{}
\stopcombination
}
With the GPS antenna turned on, the \inlXML{gpsdiag} element now displays quite a bit more information, including the status of the GPS antenna, location in both Latitude/Longitude and Easting/Northing, and an accuracy measurement.
So much for the \inlXML{<Main>} tab. Let's look at the next tab, which you may have already noted is a little peculiar. For one thing, the tag name begins with a lowercase letter. Didn't we tell you never to do that? Furthermore, the text contained within, \quotation{Records,} isn't in tags. What's going on here?
Don't worry; you haven't missed anything. It's just that there are certain kinds of tabs that FAIMS-Tools is already specially programmed to recognize. These kinds of tabs are complicated and a lot of work to make, so rather than ask you to create them, we've created a shorthand that FAIMS-Tools recognizes and runs with. These \quotation{shorthand} tabs have lowercase names, which is why you generally shouldn't come up with a lowercase tag name; you might accidentally write the name of a shorthand FAIMS-Tools recognizes, which will create a mess as it tries to follow its prewritten instructions at the same time as the instructions you've created.
In this case, the tab is \quotation{search,} which, once some data has been collected, will contain GUI elements that allow you to search records according to various criteria, including term or entity type. We don't have to include code for all these GUI elements; FAIMS-Tools knows to include them in a tab labelled with the shorthand \quotation{search}. The only thing we have included is the plaintext \quotation{Records}, without a tag. When FAIMS-Tools sees text like this written inside an element, it labels the element that way instead of basing its name on the tab group. This is why you see \quotation{Records} as the tab label when you might have expected to see \quotation{search}.
\placefigure[force][search-element]{The Search element before and after adding a few records.}{
\startcombination[2*1]
{\externalfigure[image69.png][width=.5\textwidth]}{}
{\externalfigure[image65.png][width=.5\textwidth]}{}
\stopcombination
}
Going back to the finished module, let's tap the \quotation{Main} tab and then click the \quotation{Record Interview} button, which, you may recall, will take us to \quotation{Interview.} \quotation{Interview} looks like \in{Figure}[interview-tab]:
\placefigure[force][interview-tab]{Scroll to see all fields in the \quotation{Interview} tab.}{
\startcombination[3*1]
{\externalfigure[image44.png][width=.3\textwidth]}{}
{\externalfigure[image6.png][width=.3\textwidth]}{}
{\externalfigure[image22.png][width=.3\textwidth]}{}
\stopcombination
}
The code to create this long screen is below. This is a lot more code than you've seen before in one go, but it serves as a very useful example of a lot of different techniques, so resist the urge to skim it. Take your time, and when you don't recognize what a tag is or what an element is for, see if you can guess what it does just from context.
\startXML
<Interview>
<Interview>
<Title f="id notnull">
<desc>This title should be a sensible title, unique to each item, briefly summarising the contents of the item, for example "Ilocano songs recorded in Burgos, Ilocos Sur, Philippines, 17 April 1993"</desc>
</Title>
<Description f="notnull">
<desc>Description may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text summary account of the content. {[}DCMT{]} Description may also offer an annotation, or a qualitative or evaluative comment about the resource, such as a statement about suitability for a particular application or context.</desc>
</Description>
<Private t="radio" f="notnull">
<desc>Choose either "false", meaning that the metadata for the item should be publicly available, or "true", meaning that the metadata for the item should be hidden (perhaps because you plan to check it and edit it later).</desc>
<opts>
<opt>True</opt>
<opt>False</opt>
</opts>
</Private>
<Origination_Date f="notnull">
<desc>Date the item was captured or created, using the format yyyy-mm-dd. If you are unsure of the day, month or decade enter the first day of the relevant period: e.g. "1970s" 1970-01-01, "2001" 2001-01-01, "February 1993" 1993-02-01. If entering a date of this type, clarify in the originationDateNarrative field. If you really did record on 1 January 2001, say so in the originationDate field.</desc>
</Origination_Date>
<Origination_Date_Narrative>
<desc>Use this field to provide any necessary comments on the scope of the value you entered in the origination date field, e.g. "unknown date in February 1993"</desc>
</Origination_Date_Narrative>
<Add_Agent_Role t="button" lc="Agent_Role"/>
<List_of_Agent_Roles t="dropdown" ec="Agent_Role"/>
<Linguistic_Data_Type>
<desc>If data are relevant to linguistics, choose one of the three basic linguistics data types. Primary text: Linguistic material which is itself the object of study; Lexicon: a systematic listing of lexical items; Language description: describes a language or some aspect(s) of a language via a systematic documentation of linguistic structures. If your data are not relevant to linguistics, leave this field blank.</desc>
<opts>
<opt>Lexicon</opt>.
<opt>Language Description</opt>
<opt>Primary Text</opt>
</opts>
</Linguistic_Data_Type>
<Discourse_Type>
<desc>Used to describe the content of a resource as representing discourse of a particular structural type. Dialogue: interactive discourse with two or more participants; drama: planned, creative, rendition of discourse involving two or more participants; formulaic: ritually or conventionally structured discourse; ludic: language whose primary function is to be part of play, or a style of speech that involves a creative manipulation of the structures of the language; oratory: public speaking, or of speaking eloquently according to rules or conventions; narrative: monologic discourse which represents temporally organized events; procedural: explanation or description of a method, process, or situation having ordered steps; report: a factual account of some event or circumstance; singing: words or sounds {[}articulated{]} in succession with musical inflections or modulations of the voice; unintelligible: utterances that are not intended to be interpretable as ordinary language.</desc>
<opts>
<opt>Dialogue</opt>
<opt>Drama</opt>
<opt>Narrative</opt>
<opt>Procedural</opt>
<opt>Ludic</opt>
<opt>Singing</opt>
<opt>Oratory</opt>
<opt>Report</opt>
<opt>Unintelligible speech</opt>
<opt>Formulaic</opt>
</opts>
</Discourse_Type>
<Linguistic_Subject>
<desc>Use to describe the content of a resource if it is about a particular subfield of linguistic science.</desc>
<opts>
<opt>Phonology</opt>
<opt>Text And Corpus Linguistics</opt>
<opt>Historical Linguistics</opt>
<opt>Language Documentation</opt>
<opt>Lexicography</opt>
<opt>Typology</opt>
</opts>
</Linguistic_Subject>
<Country f="notnull">
<desc>This should be the standard name of the country in which the file was recorded (see http://www.ethnologue.com/country_index.asp). Prefix the country name with the two-letter ISO3166-1 code (http://www.iso.org/iso/country_codes.htm).</desc>
<opts>
<opt>PH - Philippines</opt>
<opt>AU - Australia</opt>
</opts>
</Country>
<Region_Villiage>
<desc>Indicate the geographical scope of the item. Enter data in the order locality, state or province, country.</desc>
<opts>
<opt>{[}locality{]}, {[}state or province{]}, {[}country{]}</opt>
<opt>Burgos, Ilocos Sur, Philippines</opt>
</opts>
</Region_Villiage>
<Language_Local_Name>
<desc>The purpose of this field is to reflect language names in local use, with local spellings, if different from official name.</desc>
<opts>
<opt>Language - local spelling {[}free text{]}</opt>
<opt>Ilocano</opt>
</opts>
</Language_Local_Name>
<Language_Content_ISO639-3>
<desc>Content language is the language included in your data (spoken and/or written). Insert the 3-letter ISO 639-3 code for your language, and the standard name of the language as spelt in the ethnologue entry {[}search on www.ethnologue.com/site_search.asp{]}. Separate the code and the language with a hyphen, e.g. "ilo - Ilocano"</desc>
<opts>
<opt>mis - Uncoded languages</opt>
<opt>und - Undetermined languages</opt>
<opt>mul - Multiple languages</opt>
<opt>zxx - No linguistic content</opt>
<opt>{[}3-letter ISO639-3 code{]} - {[}Ethnologue name of language{]}</opt>
<opt>ilo - Ilocano</opt>
<opt>eng - English</opt>
</opts>
</Language_Content_ISO639-3>
<Language_Subject_ISO639-3>
<desc>Subject language is the language that is the subject of your research. Insert the 3-letter ISO 639-3 code for your language, and the standard name of the language as spelt in the ethnologue entry {[}search on www.ethnologue.com/site_search.asp{]}. Separate the code and the language with a hyphen, e.g. "ilo - Ilocano"</desc>
<opts>
<opt>zxx - No linguistic content</opt>
<opt>{[}3-letter ISO639-3 code{]} - {[}Language subject of your research{]}</opt>
<opt>mis - Uncoded languages</opt>
<opt>und - Undetermined languages</opt>
<opt>mul - Multiple languages</opt>
<opt>ilo - Ilocano</opt>
</opts>
</Language_Subject_ISO639-3>
<Attached_Audio t="audio"/>
<Attached_Video t="video"/>
</Interview>
</Interview>
\stopXML
First, the easy stuff. You should already be able to guess what the first element, \inlXML{<Interview>}, is: a tab group. Since there's another opening tag also called \inlXML{<Interview>}, you've probably also guessed that the tab group \inlXML{<Interview>} has a tab labelled \inlXML{<Interview>}. So let's skip straight to the GUI elements located within this tab.
The first element is \inlXML{<Title>} (\in{Codeblock}[codeTitle]).
\placecode[here][codeTitle]{Breaking down \inlXML{<Title>}.}{
\startXML
<Title f="id notnull">
<desc>This title should be a sensible title, unique to each item, briefly summarising the contents of the item, for example "Ilocano songs recorded in Burgos, Ilocos Sur, Philippines, 17 April 1993"</desc>
</Title>
\stopXML
}
For the \inlXML{<Title>} element, there is no UI \quotation{type} (represented by \inlXML{t=}) specified. So it becomes the default \quotation{type;} a text input field. (See \goto{{\em Type Guessing for GUI Elements in FAIMS-Tools}}[type-guessing-for-gui-elements-in-faims-tools] for an explanation of how this was determined.) The flag \inlXML{f=notnull} designates that this is a required field; the record cannot be saved if it is empty. If you can imagine your stress levels skyrocketing because of teammembers not remembering to enter in their (X), set the relevant element to \inlXML{f=notnull} and they will have no choice but to remember.
\inlXML{<desc>} allows you to set a description that your users can access by tapping and holding for a few seconds on the info button as in \in{Figure}[desc-popup].
\placefigure[force][desc-popup]{A description pop-up appears.}{\externalfigure[image70.png][width=.5\textwidth]}
That wraps up the \inlXML{<Title>} element. Now we have an opening tag for another GUI element, \inlXML{<Private>}. Private is a radio button UI object, required, has a description, and includes two options (\quotation{True} and \quotation{False}). Review the code in \in{Codeblock}[codePrivate] and see if you can understand how all of this is accomplished.
\placecode[here][codePrivate]{XML for \inlXML{<Private>}.}{
\startXML
<Private t="radio" f="notnull">
<desc>Choose either "false", meaning that the metadata for the item should be publicly available, or "true", meaning that the metadata for the item should be hidden (perhaps because you plan to check it and edit it later).</desc>
<opts>
<opt>True</opt>
<opt>False</opt>
</opts>
</Private>
\stopXML
}
This next element (\in{Codeblock}[codeAgentRole]), \inlXML{<Add_Agent_Role>}, designates a button element (\inlXML{t="button"}) that links to the tab group \inlXML{Agent_Role.} This will allow users to register new Agent Roles.
\placecode[here][codeAgentRole]{XML for \inlXML{<Add_Agent_Role>.}}{
\startXML
<Add_Agent_Role t="button" lc="Agent_Role"/>
\stopXML
}
Note that this time, instead of using an \inlXML{l} to redirect elsewhere, \inlXML{lc} was used. The difference is that using \inlXML{lc} instead of \inlXML{l} establishes a parent-child relationship, with the entity linking becoming a parent and the entity being linked to becoming a child. This is useful for organizing your module's data in a neat, hierarchical way.
\in{Codeblock}[codeAgentRoleDD] designates a dropdown menu, \inlXML{<List_of_Agent_Roles>}, which is populated with a list of \inlXML{Agent_Role} records. Specifically, they will be the \inlXML{Agent_Role} records which were saved using the button element above. The FAIMS-Tools knows these are the right records to display because the button and dropdown menu appear in the same tab group.
\placecode[here][codeAgentRoleDD]{XML for \inlXML{List_of_Agent_Roles}.}{
\startXML
<List_of_Agent_Roles t="dropdown" ec="Agent_Role"/>
\stopXML
}
The final two element types used in this tab are the \inlXML{t="audio"} and \inlXML{t="video"} types (\in{Codeblock}[codeAttachAV]). These two element types allow you to record audio and video files and attach them to your records.
\placecode[here][codeAttachAV]{XML for attaching audio and video.}{
\startXML
<Attached_Audio t="audio"/>
<Attached_Video t="video"/>
\stopXML
}
\placefigure[force][audio-UI]{With the audio UI element, you'll get a popup window that allows you to start and stop your audio recording.}{\externalfigure[image58.png][width=.5\textwidth]}
The final elements are on the Agent Role tab group, and include a few element types we've already seen: two text input fields: \inlXML{<First_Name>} and \inlXML{<Last_Name>} both with flags that designate them as \inlXML{ids} and a dropdown menu, \inlXML{<Role>} which contains a few options and is also flagged as an \inlXML{id} (\in{Codeblock}[codeAddAgentRoleTabGroup]).
\placefigure[force][agent-role]{\quotation{Agent Role} tab group appears when adding agent roles.}{\externalfigure[image54.png][width=.5\textwidth]}
\placecode[here][codeAddAgentRoleTabGroup]{XML for \quotation{Agent Role} tab group.}{
\startXML
<Agent_Role>
<desc>Enter participant name in the format Lastname, Firstname. Choose the participant role from the closed vocabulary provided. Use the description field to provide additional information on role or agents. Enter participant name in the format Lastname, Firstname. Choose the participant role from the closed vocabulary provided. Add more participants by clicking the "+" button to the right. If you need to provide extra information on the agent or the role, use the item's "Description" field to provide additional information on role or agents.</desc>
<Agent_Role>
<First_Name f="id"/>
<Last_Name f="id"/>
<Role f="id">
<opts>
<opt>Data Inputter</opt>
<opt>Performer</opt>
<opt>Speaker</opt>
<opt>Developer</opt>
<opt>Transcriber</opt>
<opt>Photographer</opt>
<opt>Interpreter</opt>
<opt>Singer</opt>
<opt>Signer</opt>
<opt>Compiler</opt>
<opt>Recorder</opt>
<opt>Depositor</opt>
<opt>Interviewer</opt>
<opt>Editor</opt>
<opt>Author</opt>
<opt>Translator</opt>
<opt>Researcher</opt>
<opt>Annotator</opt>
<opt>Participant</opt>
</opts>
</Role>
</Agent_Role>
</Agent_Role>
\stopXML
}
Now that we've explained each part, go back and review the whole one more time. You can go a long way creating modules for your team only by using the techniques we've explicitly covered above. It's very possible that you've already learned everything you need to know to make an effective module for your team.
As an exercise, follow these instructions and produce your own copy of the module's code in {\tt module.xml}. Then save that to the server and run the {\tt generate.sh} script to produce necessary files. Go to \quotation{create module} and upload the necessary files to the server as the \quotation{Simple Sample Module.}
Congratulations; you've just a simple module.
\stoptext
\stopcomponent