What is a 'Study Archive'?

Study archives are nothing more than zip files. They contain a simple directory hierarchy, media files such as images and audio, and text in the form of comma-separated values (CSV) or tab-separated values (TSV). Anyone with a text editor can create a study archive, on any computing platform.

Why Do We Need Study Archives?

Study archives offer a simple, cross-platform format for study cards, allowing you to get at your data, and import it into other applications. You can also prepare your own study archives — for example, on a PC — and import them into Mental Case for iOS. In Mental Case, study archives are used in the classroom edition of Mental Case for iOS so that a teacher can easily distribute study cards to his/her students.

How Do I Create a Study Archive?

The simplest way to create a study archive is to select some cases in Mental Case for Mac OS X, and export them (File > Export...) in Study Archive Format. But even without Mental Case, it is not difficult to create a study archive. You simply need a text editor and file compression utility. Here's how.

Directory Structure

A study archive is expected to have a number of directories. At the root is a directory called Archive. Inside that directory, are directories called Ungrouped and Groups. (Note that these names are case sensitive, so enter them exactly as shown.)

The Ungrouped directory contains notes that do not belong to any group. In the terminology of Mental Case, these notes would be in Loose Notes. The Ungrouped directory should have a file called either Data.csv or Data.tsv, depending on whether the notes are in CSV or TSV format.

The Groups directory contains groups, or cases in the Mental Case terminology. The subdirectory name is the name of the group. A given group can either contain other groups, which is equivalent to a case in Mental Case, or it can contain notes (ie a Data.csv or Data.tsv file), which is the same as a stack in Mental Case.

Here is an example of a particular study archive, showing the hierarchy of directories, and data files.

Directory Example

Archive 
    Ungrouped
        Data.csv
                                                                        

    Groups 
        Case Collection 1
            Case 1
                Data.csv
            Case 2
                Data.tsv
            Case Collection 2
                Case 3
                    Data.csv
                    Image 1.jpg
                    Audio 1.wav
        Case 4
            Data.tsv
                                                

Data File Format

The notes or cards in an archive are stored in files named Data.csv or Data.tsv, depending on whether CSV or TSV format is being used. The rows and columns are defined in the standard way, except that the first row must declare what each column represents. Here is an example:

1 Text, 1 Image, 2 Text

This CSV row contains three columns. Each column begins with a number, followed by a space, and then a data type. The number represents the facet or side of the note. In this example, there are only two sides: the prompt, and the content. The type label can be text, html, image, audio, or video, and is case insensitive. The html label can be used to provide formatted text.

After this first row, each row represents a single note. The types defined in the first row are used to interpret the data. If the label of the column is text, the data is assumed to be text, and so forth. If the label is image, audio, or video, the entry should be a file name for the media in question. The media itself should be stored in the corresponding file in the same directory as the data file.

To omit an entry from a particular note/card, an empty column can be entered. For example, if a particular side should not have an image, the image column for that side should be left vacant.

You need to be careful what tool you use to prepare the data file. Some tools don't support Unicode text, which can cause loss of special characters. You should try to choose a tool that supports Unicode text. For example, Excel does support Unicode, but only if you use the TSV format — not CSV — and make sure you save as Unicode (UTF16).

Zip It

Once you have created the appropriate directories, and entered the note data, the Archive directory should be compressed into a zip file. On the Mac, you can do this by control-clicking on the directory, and choosing the Compress menu item.

Distribute It

If you are a teacher distributing notes to students, you should make the zipped study archive available online somewhere. You could upload to a school intranet, or make it available via a public web site or online storage service such as Dropbox. Students using the Mental Case Classroom Edition can then download and install directly using the appropriate link (URL).

You can use a URL shortening service such as bit.ly to make it easier for students to enter the download link.

You can also just email a study archive. If the extension is studyarch, and the recipient has Mental Case installed, the app will open when the attachment is opened, and offer to import it.

The studyarch URL Protocol

Mental Case defines a URL protocol for study archives. What this means is that you can create URLs (links) using this protocol, and they will automatically open in Mental Case.

To create a study archive URL, you simply take the standard web address of the archive, and replace http with studyarch. For example, if you have your archive at http://myserver.com/FirstLesson.zip, the study archive URL would be studyarch://myserver.com/FirstLesson.zip. If you use this URL in a link, tapping the link will cause Mental Case to open and import the archive.

An Example

The easiest way to see how to setup a study archive is to look at an existing one. Download a demo study archive and play with it. If you want to unzip the archive, to look at its contents, you can just change the extension from studyarch to zip, and then use a standard decompression utility (eg Finder) to expand the archive.

Note that the zip file is named 'Demo', but the root of the folder hierarchy after you unpack it is 'Archive', as described above. When preparing an archive, make sure you name the folder 'Archive', zip it up, and then you can rename the zip file if you choose to.