\startcomponent[CodingModulesCreationProcess]

\section{The Module Creation Process}

Before getting into the nitty-gritty specifics of how to structure {\tt module.xml}, it's useful to review what the overall process of creating a module will look like. Below is an overview of the steps you'll follow.

Back on your Ubuntu install in the virtual machine, open up a Terminal window using the Ubuntu Dash program. You can read how here: \useURL[url20][https://help.ubuntu.com/community/UsingTheTerminal][][{\tt\tfx\hyphenatedurl{https://help.ubuntu.com/community/UsingTheTerminal}}]\from[url20].

The Terminal is Ubuntu's command line tool that we'll use to navigate the file system and run commands and programs, so this is probably a good time to make sure you're acquainted with it before proceeding.

\placefigure[force][terminal]{How to open the terminal using Ubuntu.}{\externalfigure[image5.png][width=.5\textwidth]}

Seeing as this will be your first time running FAIMS-Tools, you should make sure that you have the very latest version before doing anything else. From within the terminal, navigate to the same directory as the {\tt module.xml} file then run the dependency installation script. This is shown in \in{Codeblock}[update-generator].

\promptref{update-generator}{BASH shell commands to update the generator.}{%

\bashprompt{cd ~/FAIMS-Tools/generators/christian}

\bashprompt{git pull}

\bashprompt{sudo ./install-dependencies.sh}

}

Once you have the latest version of FAIMS-Tools, you can begin creating a module. Start your chosen text editor and open the {\tt module.xml} file. If you're using the text editor we recommended for the virtual machine, you can simply get it from the directory where you installed the FAIMS-Tools (usually {\tt FAIMS-Tools/generators/christian/module.xml}). If you're using a text editor on your main machine, you'll need to export {\tt module.xml} outside the virtual machine and work from there.

Before you make any edits, it's a very good idea to save an extra copy of {\tt module.xml} file as {\tt moduleTemplate.xml}. The version you're going to develop your module in and run through FAIMS-Tools needs to be named {\tt module.xml}, but if you want to do any other module development in the future you're going to want to have a blank lying around to work with. Once you've made your backup copy, you don't have to worry about messing around in {\tt module.xml}.

Once you've finished coding, editing, and troubleshooting {\tt module.xml} (and don't worry; we'll explain how to do all of that in the coming section), the instructions are complete and you're ready to generate your module. From the same directory you originally found {\tt module.xml} in, run the commands in \in{Codeblock}[run-generator] from the command line terminal. You won't have to type the rest of a command: just hit tab and the terminal will try to guess\footnote{The first command could be typed with fewer characters {\tt cd \lettertilde{}/F<tab>g<tab>c<tab>m<tab>)}}.

\promptref{run-generator}{BASH shell commands to run the generator.}{%

\bashprompt{cd ~/FAIMS-Tools/generators/christian}

\bashprompt{./generate.sh}

}

The {\tt ./generate.sh} command will look through {\tt module.xml} and create the necessary files that the FAIMS server needs to create a module.

Navigate to the newly created \quotation{module} folder and you'll see that the script created 6 new files. That wasn't so hard, was it?

\placefigure[force][generated-files]{The files generated by the generator.}{\externalfigure[image39.png][width=.5\textwidth]}

In the web browser, on your Ubuntu installation, open up the FAIMS server and select the \quotation{Modules} tab. On the \quotation{Modules} tab, click on the \quotation{Create Module} button.

\placefigure[force][server-modules]{Modules page on the FAIMS server.}{\externalfigure[image27.png][width=.5\textwidth]}

In a web browser, load up the web interface for the FAIMS server and log in.

The \quotation{Create Module} page offers a number of fields that allow you to describe the module name (required), version, year, description, author, and more. Give your module the name \quotation{Simple Sample Module}. On the right hand side of the screen are several boxes with file upload buttons (marked \quotation{browse}). For each of these boxes, click \quotation{browse} and attach the module necessary files you just created. Once again, the files for each box are:

\startitemize[n]

\item Data Schema: {\tt data_schema.xml}

\item UI Schema: {\tt ui_schema.xml}

\item Validation Schema: {\tt validation.xml}

\item UI Logic: {\tt ui_logic.bsh}

\item Arch16n (optional, since it's only useful if you designed your module to support interchangeable terms, but it can be ugly if you leave it out): {\tt arch16n.properties} or {\tt english.0.properties}

\item CSS (optional, but recommended): {\tt ui_styling.css}

\placefigure[force][create-module]{Filling in the create module page.}{\externalfigure[image17.png][width=.5\textwidth]}

Click the \quotation{Submit} button at the bottom of the page to have the FAIMS Server compile your module.

\placefigure[force][submit-button]{The important submit button.}{\externalfigure[image10.png][width=.5\textwidth]}

Once the server creates the module, you'll be directed back to the main \quotation{Module} tab.

\placefigure[force][module-appears]{Now the module appears.}{\externalfigure[image7.png][width=.5\textwidth]}

If you click on the module name, you'll see a screen where you can manage the module, including editing the module metadata, schemas, add user accounts, and downloading or exporting your module. You may also browse any records uploaded from mobile devices using the \quotation{Module Details} area and \quotation{Search Entity Records} button. Near the bottom of the page, you can delete the module. For more information on deploying or deleting modules from the server, see \useURL[url21][https://www.fedarch.org/resources/handouts.pdf][][{FAIMS Handout 103}]\from[url21].

Now, open up the FAIMS mobile app on your Android device. Click on the three vertical dots in the upper right to open the \quotation{Settings} menu.

\alert{Some Samsung devices may show the menu differently, such as the Samsung S III. A Nexus 7 tablet shows it in the top right corner.}

In the Setting menu, you'll see the option to select a specific FAIMS server to connect to. By default, this is set to the FAIMS Demo server in Sydney, Australia. Click on the dropdown and you'll see that you can set the server address manually (through the \quotation{New Server} option) or, if you're connected to the same network as the server, you can use the \quotation{Auto Discover Server} to expedite the server setup. We'll assume that your Android device is currently on the same wifi network as your server, so choose \quotation{Auto Discover Server} and then hit the \quotation{Connect} button. If auto-detection does not see your server, you may also select \quotation{New Server} from the dropdown list and enter the IP address manually. The IP address is visible in the address bar of your internet browser when you are connected to the FAIMS server and will look similar to {\tt 192.168.1.133}. Often, the default port of {\tt 80} will work.

\placefigure[force][select-server]{Tap the three vertical dots to open \quotation{Select Server.}}{%

\startcombination[2*1]

{\externalfigure[image19.png][width=.5\textwidth]}{}

{\externalfigure[image9.png][width=.5\textwidth]}{}

}

After a few seconds to a minute, the FAIMS app will find your server. Once connected, you will see a list of modules available to use, either locally on your device (designated by a blue phone icon) and those available for download from the server (designated by a black server icon). Once you have downloaded a module, it will show both icons so long as you are still connected to a server that also has the module.

\placefigure[force][phone-icon]{Blue phone icons after the module is downloaded.}{\externalfigure[image2.png][width=.5\textwidth]}

Tap on the item \quotation{Simple Sample Module} from the list, which is the one we just uploaded to the server, and the FAIMS app will copy it to your device. A sidebar with the module metadata will appear. You can browse that quickly, and then tap the \quotation{Load Module} button.

\placefigure[force][sidebar]{Sidebar with module metadata.}{\externalfigure[image12.png][width=.5\textwidth]}

Once the module has loaded, you'll be presented with the first tab group of the module, in this case, a user login screen. User logins allow FAIMS to track which users are responsible for which changes. As any archaeologist who has had to decipher and track down which initials belonged to the field worker who sloppily wrote them on a level sheet or artifact bag can tell you, automatically attaching user names to record can make life much easier when going through field collections and forms back at the office or lab. You can add more users via the FAIMS server by selecting the module and clicking the \quotation{Edit Users} button.

\placefigure[force][login-menu]{User login menu.}{\externalfigure[image25.png][width=.5\textwidth]}

\placefigure[force][edit-user]{Add or remove users throught the \quotation{Edit User} tab.}{\externalfigure[image40.png][width=.5\textwidth]}

And there you have it. That's essentially what making a module with a {\tt module.xml} file will look like.

Of course, as you've probably realized, the part we glossed over--designing and troubleshooting {\tt module.xml}--was also the tricky part. Fortunately, it's not that tricky after all.