JSON formatting

Attributes in this guide must be formatted using JSON formatting. There are a few rules about JSON you will need to know for this guide.

Fundamentally, JSON allows you to define objects. These objects have properties, which are similar to attributes. Properties have a key (name) and value, and a JSON property can take on any string as its value. An example JSON object is below:

{"name":"John", "age":"24"}

Notice that both the key and value are enclosed by double quotations, with a colon separating the two. Additionally, properties are separated by a comma.

You can also define arrays of objects and arrays of strings using JSON by wrapping objects/strings in square brackets and separating them by commas:

[{"name":"John", "age":"24"}, {"name":"Jack", "age":"32"}]

Array of two objects

["Array", "of", "strings"]

Array of three strings

We use these building blocks in our attributes to structure information about candidates. Editing JSON (especially for candidate purposes) can be made less cognitively demanding through the use of a formatting tool like JSON formatter.

Candidates

The default candidates of "Democrat" and "Republican" will not fit for most maps. In order to describe custom candidates for our map, we must set the candidates attribute on the top-level svg element to a JSON array of objects. These objects should have the following properties:

• id: A unique identifier for this candidate, can be any string.
  • This works exactly analogous to the region attribute from earlier.
• name: Name of the candidate, e.g "Democrat"
• margins: A JSON array of margin objects
  • Margin objects have one property, color, that takes on a hexadecimal color.
  • Example: [{ "color": "#1C408C" }, { "color": "#577CCC" }, { "color": "#8AAFFF" }, { "color": "#949BB3" }]
• defaultCount (optional): The value this candidate should have before any regions are filled in. Defaults to 0.

Here is what an example JSON object for a candidate looks like (formatted nicely):

{
    "id": "0",
    "name": "Democrats",
    "margins": [
      {
        "color": "#1C408C"
      },
      {
        "color": "#577CCC"
      },
      {
        "color": "#8AAFFF"
      },
      {
        "color": "#949BB3"
      }
    ]
}

And here is what a correctly formatted array of candidate objects looks like:

[
  {
    "id": "0",
    "name": "Democrats",
    "margins": [
      {
        "color": "#1C408C"
      }
    ]
  },
  {
    "id": "1",
    "name": "Republicans",
    "margins": [
      {
        "color": "#BF1D29"
      },
      {
        "color": "#FF5865"
      }
    ]
  }
]

Note the square brackets and comma at the end of the first object but not the second object.

Once you have this candidate object created, you can set the value of the candidates attribute in Inkscape. Make sure this attribute is set on the svg element. For example:

Setting the winner of a region

If you would like a region to be filled in for a certain candidate(s) when the map is loaded, you can do that by setting the candidate attribute on that region's element to an array of JSON objects with the following properties:

• candidate: the ID for the candidate getting value from this region
• value: how much value the candidate is getting from this region
• margin: what margin color YAPms should display for this candidate
  • This value is zero-indexed. To use the first margin, set to 0

For example, if you had one candidate winning a region of value 1, you would set the candidate attribute to:

[{"candidate":"3","count":1,"margin":0}]

If you had two candidates splitting a region, you would set the attribute to:

[{"candidate":"3","count":3,"margin":0},{"candidate":"4","count":2,"margin":0}]

Modifying the Tossup Candidate

You can also specify a value for the tossup-candidate attribute to modify the name and margins for the default candidate. Just set the attribute to a candidate object as described above. For example:

{
  "id": "",
  "name": "Tossup",
  "defaultCount": 0,
  "margins": [
    {
      "color": "#cccccc"
    }
  ]
}

Troubleshooting

• I set my custom candidate array, but my candidates did not change from default
  • First, double check that you set the candidates attribute on the svg element, which is parent of all other elements.
  • Second, check that your JSON is formatted correctly. The "Validate" function on JSON formatter will alert you to any errors.