Study Archive Format

Mental Case now supports a simple open format for exchanging notes and cases: study archive format. The idea of study archives is that they are simple enough that you can create them without any specialized applications, and yet are flexible enough to represent quite complex study cards.

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 iPhone. In Mental Case, study archives are used in the classroom edition of Mental Case for iPhone 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 simply 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'.

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 Collection in Mental Case, or it can contain notes (ie a 'Data.csv' or 'Data.tsv' file), which is the same as a standard Case in Mental Case.

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

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 Mental Case, there are only two sides to each note at this time: the prompt, and the content. The type label can be 'text', 'image', 'audio', or 'video', and is case insensitive. Mental Case only supports text and images at this point in time.

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

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 MobileMe (me.com) or Dropbox (getdropbox.com). Students using the Mental Case Classroom Edition can then download and install directly using the appropriate link (URL).

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. Here is a study archive for you to play with. 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.