Firebolt Mapping Application: Important Files

1) config.ord

This document is to describe the syntax of the config.ord files used in the iOS Application Firebolt. This descriptor assumes the user knows the basics of the operation of FireBolt, can modify the contents of FireBolt’s associated DropBox account, and understands basic programming and computer terminology, including the use of notepad-style text editors.

Code is denoted using the courier font and centered, like this

This is code. Code will be about things inside the config file

Important things are underlined for clarity

Table of Contents

i. File Placement within the Dropbox File System

ii. Basic Syntax

iii. Simple Ordering

iv. Multiple Character Systems

v. Example Config File Creation

i. File Placement within the Dropbox File System

There will be one configuration file for each departmental entry in the master dropbox file system. This file will be called “config.ord”, and will be formatted using the UTF-8 standard (The default in most text editors). The file extension, a *.ord, is custom to this application and stands for “Order”. This file can be created and edited using any standard “Notepad” style text editors. Download a sample config.ord file.

This configuration file will be placed in the following address:

/[Department]/Maps/

Failure to place the file in the proper directory will result in the file being unable to be read.

ii. Basic Syntax

Any line preempted by a double slash will be treated as a comment, and not considered in the ordering of the files. Comments are provided for the end user to annotate any changes or specific notes.

// This is a comment, and will not affect the ordering

Note that multi-line comments, commonly denoted by /* and */ in some programming languages, will not be considered comments, and will cause errors. Also, note that comments are only considered on a line-by-line basis, so end-of-line comments will not be considered comments.

BB //This is NOT a comment, and will cause an error

Any empty line will be ignored

Any line with only uppercase alphabetic characters is a valid entry, and will be considered in the final ordering.

Entries will be evaluated in pairs, each element of the pair representing the beginning and end of a set. This means there will always be an even number of entries in a config.ord file.

Do not leave any trailing whitespace at the end of lines.

AA_

Note that numbers are not needed to define the orderings of the columns. All columns are assumed to start (at any number) on the left and iterate upwards towards the right. This is done automatically by Firebolt. The config file is concerned only about the vertical ordering of the letters.

iii. Simple Ordering

The ordering is derived from the pairs of entries, and the order in which they are in the config file. The file is read from top to bottom, in sets of two. These pairs denote the endpoints of the definition of the set. Say, for example, our ordering went from “A” to “Z”, a simple alphabetical ordering. Our config file would consist of only the next two lines (barring any comments).

This tells the computer the ordering begins at “A” and ends at “Z”. A more complex, but still valid, ordering could be denoted

This would be read as such: The first set of definitions is “A” through “D”, and the next set is “Z” counting down through “E” (which is supported by this format). If one were to traverse the entire set explicitly, we would see the following ordering:

A, B, C, D, Z, Y, X, …, G, F, E

The breaks in ordering are not necessary for implicit orderings, like the alphabet. One could write an config.ord file as such:

Which would iterate through the alphabet, “A” through “G”, and then “H” through “Z”, but this is not necessary. The format carries with it implicit orderings within a set, including traversing backwards.

Note that one can also skip individual letters or sections. For example,

would skip the letters E and F.

iv. Multiple Character Systems

So far, we’ve only covered single-character systems. Using any number of characters to define the order is possible in this format.

Consider the general double letter format that iterates from “AA” all the way to “ZZ”. This can be interpreted two ways, namely

AA, BB, CC, DD, …, YY, ZZ

or as the much more explicit version,

AA, AB, AC, AD, …, AZ, BA, BB, …, ZX, ZY, ZZ

This format eliminates this possibility, leaving no ambiguity in the interpretation of the ordering. This has the side effect of having to be more verbose.

Consider the first case, AA, BB, …, ZZ. This can be seen as having a consistent “Level of Change”, meaning each entry has all of its characters changed in the same way, namely, incremented. That means, given a character “N”, we know we iterate to the next character, “N+1”. This would qualify as a set, and can be defined simply as

The second case, AA, AB… AZ, BA, …, ZZ does not have a consistent “Level of Change”, meaning we can’t apply the incrementation across all the characters. If we were to apply the incrementation across all characters, “AB” would become “BC”, which is not correct. This is why this case must be broken up into 26 different subsets, each defined with a consistent “Level of Change”. This broken-up definition would give us a final definition:

…

Note that this has been edited with ellipses for brevity. As mentioned before, the explicit definition removes ambiguity at the cost of having to be more verbose. Note that, when using any definitions, you do not need to iterate until the ending of the conventional ordering. For example, if your maps only go from “AA” to “BE” using the second-case ordering, you only need to have:

AZ
BA
BE

Note that it is also valid to iterate to the end of the conventional ordering, so it would also work to have:

AZ
BA
BZ

This format may be more helpful than using ‘BE’ at the end of your config file if you know that you may eventually add BF, BG, and so forth underneath BE, and don’t want to have to remember to go in and change the config.ord file.

Keeping these definitions to a minimum helps the app and anyone else who must understand the config files, at the cost of having to update the config file should anything change.

v. Example Config File Creation

We will now walk through the creation of a config file from a source. Here is the city of Goldens map, on the following page.

Note here that the ordering begins with BB and descends to AA. This has a consistent “Level of Change”, and should be considered a single subgroup. Next, we can see that it begins lettering at A, then continues to go up to L.

Now, several personal decisions come in, because there are several valid config files possible, and they depend on what changes you would expect from the map in the future. For example, if you expected the city to expand upward, creating CC, DD, etc. zones, you could define the upper bound as such.

If you thought the bottom were to expand, you could iterate past L all the way to Z if you wished.

So, this gives us four possibilities, all of which are valid and would work in the program:

// Config.ord for Golden

BB	ZZ	BB	ZZ
AA	AA	AA	AA
A	A	A	A
L	L	Z	Z
is most concise, but allows for no expansion. Config must be updated.	Growth upward expected.	Growth downward expected	Growth expected, but not known where. A very safe bet, but possibly not necessary.

I’m going to use the most verbose one. Here is the final config file example.

// Config.ord for Golden, written by Trevor Westphal

// Upper bound as “ZZ” for upward expansion

// Lower bound as “Z” for downward expansion

2) links.json

What is a JSON File and Why do I Need One?

A JSON file is a special type of file that can easily be read by both computers and humans. You need an empty JSON file in your department's Maps folder on Dropbox so that Firebolt can save the data for you gate key links and preplan links. Make sure that you also have a PDF file called "GateKeyIndex.pdf" in your Maps folder- this is the PDF name that all of the key links will be linking back to!

Download an empty links.json file here.

The JSON file stores the information that Bolt needs to draw links to the gate key index page, and to draw links to the individual preplan pages. All you need to do is create an empty file named "links.json", and place it in your department's Maps folder. This file will be a special type of file called a 'JSON' file, which can easily be created using a simple text editor (such as Textmate or Notepad++).

Once the empty JSON file has successfully been created and added to the Maps folder, Bolt will automatically add data to it for your gate key links and preplan links.

Editing Existing Gate Key Links and Preplan Links

Link data can be deleted from these files if you later decide that you don't want a link on a given page, but this must be done so very carefully. *If you accidentally created a link to a nonexistent preplan page, simply clicking on this link in the application will give you an alert that the PDF file does not exist, and the application will delete the preplan link data for you- which means you don't need to go through the process of editing the JSON file directly!

To delete link data, start by downloading your JSON file from Dropbox. JSON files are a very special type of file. They are great for storing data that the computer can easily read and understand, but they are also very sensitive to any extra tabs, spaces, and punctuation marks. This is why it is very important to save your backup copy of the JSON file, and to be very careful and precise when editing it. Make a copy of your JSON file and save it in a safe location on your computer.

This way if you accidentally corrupt the JSON file while editing it, you will still have a working copy of the file. If you forget to make a safe copy of your JSON file and then corrupt the file, you will have to start over with an empty JSON file and re-add all of your links as you did before (or do some research on JSON files, neither of which will be very fun!).

Our JSON file has two different sections- one section is called "gateKeyLinks" and the other is called "preplanLinks". The order that these two sections appear in your JSON file may vary, but this is okay (i.e. the "preplanLinks" data may actually be displayed above the "gateKeyLinks" data). If we want to delete a gate key link, we will delete data from the "gateKeyLinks" section, and if we want to delete a preplan link, we will delete data from the "preplanLinks" section. Below we have a sample JSON file created by Bolt. Our sample file has three gate key links, and two preplan links.

For our example, let's say we have an out of date gate key link that's being drawn on our C2 map page. Open up the JSON file and look under the "gateKeyLinks" section. To delete the key link being drawn on C2, highlight everything from line 3 to line 7 and delete it. Notice that we are deleting all of the text associated with C2, as well as the opening and closing square brackets. Just like an expression such as (3 * 2 + 5 wouldn't make very much sense in math, the computer will be confused if you forget to delete both brackets associated with our data. Our new JSON file will now look something like this:

There's one more special consideration when editing JSON data. Notice anything special about our gate key link data for B4 compared to A2? Our B4 data is followed by a comma! Our gateKeyLinks data is a list of items, and just like you would separate a list of items in English by commas (i.e. My grocery shopping list is: strawberries, milk, eggs, etc), our link data also needs to be separated by commas. For example here we essentially have the gateKeyLink data: [B4], [A2]. If we were to delete either of these key links, then we would also need to delete the comma, because then we would no longer have a list!

What if I have multiple entries for the same map page and I don't know which one to delete?

The easiest way to handle this would probably be to hand draw a quick sketch of the map page the way it is currently rendering, delete all of the JSON entries for the map page, and then go back and re-add the other links that you wanted to keep. If you really want to just delete the one specific entry, then you'll have to compare the coordinates for the link. In the JSON file, following the map page file name is the x coordinate for the link, followed by the y coordinate for the link. Also, make sure to check out an example of Bolt's coordinate system below (with the right-hand bounds of the screen being around 880 pixels, and the lower bounds of the screen being around 560 pixels).