***** OVERALL COMMENTARY *****

This README assumes you have at least a passing familiarity with JSON, at least on a conceptual level. You should always examine the file as it stands before you attempt to edit it; knowledge of the file, along with this guide, should be enough to guide you through adding data to, or editing current data in, the JSON files used in this site.

JSON ignores whitespaces (spaces, newlines and tabs). The following JSON code:
  "pends": [ { "year": "2016", "month": "05" }, { "year": "2016", "month": "06" } ] 
is equivalent to the following JSON code:
  "pends": 
  [ 
    { 
      "year": "2016", 
      "month": "05" 
    }, 
    { 
      "year": "2016", 
      "month": "06" 
    } 
  ]
Use whatever format is most readable for you.

Whenever you add an item to an array, or a property to an object, be sure to put a comma after it UNLESS it is the last (or only) item in the array (or property in the object). If that is the case, be sure NOT to put a comma after it. jQuery's JSON parser is VERY picky.

Whenever you add data to a file, make a local backup first. Add your data, save the file, and then IMMEDIATELY load the page(s) that uses the file to make sure that your syntax is correct. If the page does not load correctly, and you cannot immediately figure out why (here's your first hint: it might be either a missing, or extraneous, comma), restore the file from your backup, save the file (to restore page functionality) and start again.

Remember to use HTML Entities for all non-standard characters, e.g., Æ should be &AElig;, < should be &lt;, & should be &amp;, etc.

If you have any concerns, or there is something not covered here, email Kameshima at cadell@gmail.com for advice.

***** COURTREPORTS.JSON *****

courtreports.json holds the data for the archive of Court Reports. The page is sorted in descending order by the "reign" property of each reign object. The list of Courts within each reign is sorted in descending order by the "file" property (which, due to the file name syntax, approximates reverse chronological order, as intended).

File syntax: 
{ 
  reigns: [ Array of reign objects ],
  default: url, (the web address of the folder where, by default, Court Reports are located)
  searchaction: url (the web address of the form action to search Court Reports)
}
reign object syntax:
{
	royalty: string, (the name of the Royalty)
	dates: string, (the time span, in month/AS/year, that the Royalty ruled)
	reign: number, (the chronological order of the reign)
	notes: string, (OPTIONAL, any notes to be displayed about the reign, see Yngvar and Caryl (reign 1) for an example)
	courts: [ Array of court objects ]
}
court object syntax:
{
	event: string, (the name of the event)
	eventnote: optional string, (OPTIONAL, any notes to be displayed about the event)
	date: string, (the text date of the event)
	file: string, (the file name of the Court Report, as located in the )
	location: string
}

Addition of data:
* To start a new reign:
	  1. Add a new reign object to the start of the "reigns" array:
	    a. "courts" should consist of a single "Coronation" entry, which can be copied from the previous reign and the file name changed. 
  	  b. "reign" should be one higher than the previous reign. 
	    c. "dates" should be the month/year of Coronation " - current".
	  2. Change the dates of the last reign object from "current" to the month/year of decoronation.
* To add a new court, add a new court object to the start of the "courts" array of the current reign.

Conventions:
* Pennsic War is listed as "Pennsic War <Roman Numeral>" located in "Greater &AElig;thelmearc" REGARDLESS of how the actual Court Report is titled.

***** LETTERS.JSON *****

letters.json holds the archive of submission letters. This file is used both to create the Submission Archives as well as the list of "letters currently open for comment" on the front page.

File syntax:
{
  items: [ Array of letter objects ],
  internaldefault: string, (the default location of internal letters, with "{0}" being a placeholder for the iloi string)
	externaldefault: string, (the default location of internal letters, with "{0}" being a placeholder for the xloi string)
	reportdefault: string, (the default location of internal letters, with "{0}" being a placeholder for the lor string)
	loardefault: string (the default location of internal letters, with "{y}" being a placeholder for the year and "{m}" for the month)
}
letter object syntax:
{
	name: string, (the display name of the letter, usually "AE###")
	iloi: string, (the OSCAR ID of the internal letter OR the URL to the internal letter)
	iloidate: string, (the date, in MM/DD/YYYY format, that the internal letter was released)
	iloicloses: string, (OPTIONAL, the date, in MM/DD/YYYY format, that the internal letter closes for commentary; default is iloidate + 1 month)
	xloi: string, (OPTIONAL, the OSCAR ID of the external letter OR the URL to the external letter)
	xloidate: string (OPTIONAL, the date, in MM/DD/YYYY format, that the external letter was released)
	xloicloses: string (OPTIONAL, the date, in MM/DD/YYYY format, that the external letter closes for commentary; default is (first of month of xloidate) + 3 months)
	lor: string (OPTIONAL, the filename of the letter of report OR the URL to the letter of report)
	lordate: string (OPTIONAL, the date, in MM/DD/YYYY format, that the letter of report was released)
	loar: LoAR object (OPTIONAL, the year and month the initial LoAR was released for this letter)
	pends: [ Array of LoAR objects ] (OPTIONAL, the years and months of any LoARs with pended items from this letter)
}
LoAR object syntax:
{
  year: string (4 digits)
  month: string (2 digits)
}

The list of open letters uses the following defaults for determining how long a letter should be listed as open for comment:
  * Internal letters are assumed to close exactly one month after they open, e.g., if a letter is published on June 14, it will be listed as open until July 14. Specifying the "iloicloses" property of the letter object will override this assumption.
  * External letters are assumed to close three months after the first of the month in which they open, e.g., if a letter is published on June 14, it will close on September 1 (three months after June 1). Specifying the "xloicloses" property of the letter object will override this assumption.

Addition of data:
* To start a new letter, add a new letter object to the start of the "items" array. The only properties that should be included are "name" "iloi" and "iloidate". If the letter will not be open for commentary for exactly one month, add the "iloicloses" property.
* To add XLoI information to a letter, add the "xloi" and "xloidate" properties to the object. (Remember to put commas where you need them, and not where you don't!) If the letter will not follow the default for how long it will be open for commentary, add the "xloicloses" property.
* To add LoR information to a letter, add the "lor" and "lordate" properties to the object.
* To add LoAR information to a letter, add the "loar" property with a properly formatted object. For example, for the June 2016 LoAR, your line of JSON code should look like:
  "loar": { "year": "2016", "month": "06" }
* To add LoAR information about a pended item to a letter:
  * If this is the first such LoAR, add the "pends" property with a properly formatted array of LoAR objects. For example, if the June 2016 LoAR contains information about one or more pended items, your line of JSON code should look like:
    "pends": [ { "year": "2016", "month": "06" } ]
  * If this is not the first such LoAR, add another object to the "pends" array. For example, if both the May and June 2016 LoARs contain information about one or more pended items, your line of JSON code should look like:
    "pends": [ { "year": "2016", "month": "05" }, { "year": "2016", "month": "06" } ]
  
***** MENU.JSON *****

menu.json holds the data that populate the various menus on the website:
* The top drop-down menu for the standard, fully interactive version of the site;
* The "hamburger" side menu for the mobile version of the site;
* The sidebar menu for the screen-reader-friendly version of the site.

Conventions:
* A menu item will EITHER be a link, or have sub-items, BUT NOT BOTH. This is for mobile users, who would need to tap on a menu item to access the sub-items, but would then be taken to the link associated with the parent item.
* If a menu item is a link, it will EITHER have the "link" property defined, or have "globalLink" defined as true and the "linkName" property (and possibly "page" and/or "param") defined, BUT NOT BOTH. Global links are common links used throughout the site and are defined in /js/site.js.
* This syntax can recurse as many times as necessary, i.e., sub-items can have sub-items that have sub-items that have sub-items and so on.
* Unless you are adding a new page to the site, you should never have to update this file. Be sure to test the page before adding it to the menu.

File syntax: { items: [ Array of menu item objects] }
menu item object syntax:
{
  label: string, (the text of the menu item)
  link: string, (PSEUDO-OPTIONAL, the URL destination when the menu item is clicked)
  globalLink: boolean, (PSEUDO-OPTIONAL, true if this is a global link, see above)
  linkName: string, (REQUIRED IF globalLink IS TRUE, the name of the global link, see above)
  page: string, (OPTIONAL, if globalLink is true, this is appended to the link)
  param: string, (OPTIONAL, if globalLink is true, this is appended (after page, if defined) to the link, with a "?" separating them)
  items: [ Array of menu item objects ], (PSEUDO-OPTIONAL, a list of items organized as sub-items to this item)
  newtab: true/false, (OPTIONAL, if true and "link" is defined, the link will open in a new tab/window)
  tooltip: string (OPTIONAL, if "link" is defined, this text will appear as a tooltip when a user hovers their mouse over the link)
}

***** NEWSFEED.JSON *****

newsfeed.json contains items for the "Latest News from the Æthelmearc College of Heralds" section of the front page. These items are only displayed on or after their "publish" date and on or before their "unpublish" date, so it is not necessary to wait until an item is relevant before adding it, nor is it necessary to remove an item immediately upon becoming irrelevant. If an item does not have an "unpublish" date, it will remain on the site for 1 month.

File syntax: { items: [ Array of news item objects ] }
news item object syntax:
{
  publish: string, (the date, in "MMM DD, YYYY" format, of the date the item should start being displayed)
  unpublish: string, (OPTIONAL, the date, in "MMM DD, YYYY" format, of the date the item should stop being displayed)
  title: string, (the title of the news item)
  author: string, (the author of the news item)
  content: string (the HTML-formatted content of the news item)
}

***** ROSTER_STAFF.JSON *****

roster_staff.json contains information about Silver Buccle and the senior heraldic staff of the Kingdom. This file is used to create the "Senior Staff" page and the Full Roster.

File syntax: { items: [ Array of senior herald objects ] }
senior herald object syntax:
{
  link: string, (OPTIONAL, the page that will be loaded into the subsequent accordion section when the header is clicked)
  label: string, (OPTIONAL, the bookmark to use to automatically open the subsequent accordion section and scroll the page)
  description: string, (a description of the heraldic office)
  title: string, (OPTIONAL, the heraldic title that accompanies the office)
  email: string, (OPTIONAL, the email address of the heraldic office),
  vacant: true/false, (OPTIONAL, true if the office is not currently occupied)
  heraldName: string, (REQUIRED IF NOT VACANT, the name of the herald that currently occupies the office)
  personaltitle: string, (OPTIONAL, the personal heraldic title of the herald that currently occupies the office)
  deputies: [ Array of senior herald objects ] (OPTIONAL, any deputies that report to this herald)
  
}

***** ROSTER_REGIONALS.JSON *****

roster_regionals.json contains information about Kingdom Regional Deputy Heralds. This file, in concert with roster_locals.json, is used to create the "Regional & Local Heralds" page and the Full Roster.

This file has the same syntax as roster_staff.json, WITH ONE EXCEPTION: the "link" property is used to synchronize data read from roster_locals. (See the "roster_locals" section below for reference.) For everything else, see the "roster_staff" section for reference.

***** ROSTER_LOCALS.JSON *****

roster_locals.json contains information about the groups in each region and the local heralds for those groups. This file, in concert with roster_regionals.json, is used to create the "Regional & Local Heralds" page and the Full Roster.

File syntax: { items: [ Array of region objects ] }
region object syntax:
{
  link: string, (used to synchronize data into the correct section of the accordion, see below)
  groups: [ Array of group objects ]
}
group object syntax:
{
  "group": string, (OPTIONAL, the name of the group)
  "img": url, (OPTIONAL, the URL of the miniature of the group's arms)
  "title": string, (OPTIONAL, the heraldic title for the group's herald)
  "email": string, (the email address for the group's herald; can be a full email address, or else "@aeheralds.net" will be amended)
  "vacant": true/false, (OPTIONAL, true if the office is not currently occupied)
  "herald": string, (REQUIRED IF NOT VACANT, the name and rank of the herald that currently occupies the office)
  "deputies": [ Array of deputy herald objects ], (OPTIONAL, listings for any deputy heralds for this office)
  "groups": [ Array of group objects ] (OPTIONAL, listings for any sub-groups belonging to this group (e.g., cantons of a Barony)
}
deputy herald object syntax:
{
  "title": string, (OPTIONAL, the title of the deputy if applicable, or "Deputy" works fine)
  "herald": string, (the name and rank of the herald that currently occupies the deputy office)
}

Regionals and Locals:
* How Regionals and Locals synchronize:
  1. roster_regionals is read and parsed to create the accordion. Each header contains a "link" attribute that contains the "link" property of the regional herald object.
  2. roster_locals is read and parsed. For each region object in roster_locals, the page tries to find a header element with the "link" attribute equal to the "link" property of the region object. If it finds one, it fills the corresponding accordion body element with a grid created using the "groups" property of the region object.
* It is therefore necessary that the "link" properties in roster_regionals and roster_locals are the same for a region and its corresponding groups.
* The decision was made to keep this information in two files rather than one because, in general, the information for local heralds is far more volatile than the information for regional heralds. Thus, it was deemed sufficiently important to modify local herald information without endangering the syntactical correctness of the regional herald information.

***** ROSTER_ATLARGE.JSON *****

roster_atlarge.json contains information about "At-Large Heralds," that is, heralds that are not staff, regional, or local. This file is used to create the "At-Large Heralds" page and the Full Roster.

File syntax: { items: [ Array of herald objects ] }
herald object syntax:
{
  title: string, (OPTIONAL, the herald's rank)
  name: string, (the herald's name, used for alphabetization)
  email: string, (OPTIONAL, the herald's email address)
  heraldictitle: string, (OPTIONAL, the herald's heraldic title)
  specialty: string (OPTIONAL, a heraldic specialty the herald wishes to have listed)
}

***** ROSTER_SILENT.JSON *****

roster_silent.json contains information about heralds in the Silent Heraldry (ASL interpretation) program. This file is used to create the "Silent Herald" section of the "Senior Staff" page and the Full Roster.

This file has the same syntax as roster_atlarge.json. See that section for reference.