Electowidget Configuration Reference

The Electowidget configuration is a MediaWiki page in the "Election:" namespace with JSON-formatted configuration information as the content of the page. The configuration is read in as a single associative array or "map" at the root note, with a hierarchy of data contained within.

Formatting rules

Here are the basics of the formatting rules. In each item in the #Configuration parameters section below, you'll see a data type in parenthesis (e.g. str, bool, map, seq). These are the formatting rules for each type:

map

This is a mapping of key/value pairs (also known as an "associative array" or a "hash"). Example { "key_1" : "value_1", "key_2" : "value_2", ... "key_n" : "value_n" } The key portion is always a str. The "value_x" portion may be any data type (including another map or a seq).

seq

An ordered sequence of unnamed values. [ "value_1", "value_2", ... "value_n" ] The "value_x" portion may be any data type (including another seq or a 'map).

str

A quoted string, e.g. "Jefferson"

int

A positive or negative integer (e.g. 42 or -163)

bool

true or false

Please visit the JSON website for exhaustive documentation of JSON syntax.

Configuration parameters

Below is documentation for each of the parameters, which are usually identified by the map keys (e.g. ballot_type). Map keys in parenthesis are not literal map keys, but rather are descriptive of user-defined keys that may be used in that context. In the case of a sequence (seq), the child elements are unnamed parameters.

Root node:(map) - An election configuration is a mapping with a series of parameters, as defined below:

• version: REQUIRED (str) - Version of the election configuration format being used.
  Valid values:

  "0.1"

  Format version number for all versions of Electowidget as of this writing (October, 2005)

• allow_voting: (bool) - 'true' if a link should be displayed to allow logged-in users to edit their vote.
• ballot_type: (str) - Controls the appearance and behavior of the voting user interface.
  Valid values:

  "barscale"

  Bar chart with adjustable bars. Requires JavaScript for optimal use, though essential functionality is accessible without JavaScript by entering a rating in the provided text entry field. Specify minimum and maximum ratings using min_rating and max_rating parameters, and control the size of the sliding scale using barscale_tickpx

  "radioarray"

  Series of descrete ratings selectable by simple radio button control. Specify minimum and maximum ratings using min_rating and max_rating parameters, and set the labels for each rating using radioarray_labels.

  "singlecheckbox"

  Allow users to check (set rating to 1) or uncheck (set rating to 0) for each candidate. Ignores min_rating and max_rating parameters. Useful for conducting a pure Approval election.

  "singleradio"

  Allow users to select (set rating to 1) a single candidate, deselecting all other candidates (setting ratings to 0). Ignores min_rating and max_rating parameters. Useful for conducting a traditional plurality election.

  "stars"

  Graphical bar chart with stars representing the ratings. Requires JavaScript for optimal use, though essential functionality is accessible without JavaScript by selecting a rating from the provided drop-down selection box. Specify maximum rating using max_rating parameter. Ignores min_rating parameter.

• barscale_tickpx: (int) - Used when ballot_type is set to 'barscale' to specify the number of pixels per rating. For example, if min_rating is set to 0, and max_rating is set to 10, setting barscale_tickpx to 2 will cause adjustable portion of the barscale to be 20 pixels wide.
• candidates: (map) - Key/value List of candidates in the election. The key portion is an internal identifier for the candidate used by the program which sometimes shows up in the user interface (though this will hopefully be rare). Set the key to something readable, but short.
  • (candidate key): (map) -
    • candidate_url: (str) - URL to a page describing the candidate
    • display_name: (str) - Name of the candidate as you would like it displayed in the ballots and results.
    • (other fields): (str) - Other fields may be defined by adding field definitions to the features mapping.
• count_subpage_ballots: (bool) - If true, count ballots cast by logged in users.
• description: (str) - Description of the election, which appears at the top of the initial election entry page.
• display_parameters: (bool) - If true, display the parameters for this election on the initial election entry page. At the time of this writing, this is woefully incomplete, but will at least return the list of candidates.
• display_results: (bool) - If true, calculate and display the results of the election with ballots currently on hand.
• election_methods: (seq) - List of election methods to use in tallying the results. Each item of the list is a mapping which has parameters specific to that particular method.
  • (map) - Key/value list of parameters for this particular method.
    • type: REQUIRED (str) - The election tallying method. schulze-wv is recommended by the author of this software.
      Valid values:

      "approval"

      Approval voting

      "chain"

      Chain multiple methods using this election type. For example, one can define a chain such that the Smith method is used, and Minmax(wv) settles any ties should there be multiple Smith method winners. Use the 'methods' parameter described below to provide an ordered list of methods.

      "copeland"

      Copeland method

      "dmc"

      Definite Majority Choice method. This particular implementation implements it as Minmax(Total Approval) as an implementation convenience.

      "instant-runoff"

      Instant runoff voting

      "minmax-margins"

      Minmax(wv) - use 'margins' to measure victory strength.

      "minmax-wv"

      Minmax(wv) - use 'winning votes' to measure victory strength.

      "plurality"

      Plurality

      "range"

      Range Voting

      "schulze-margins"

      Schulze method - use 'margins' to measure victory strength.

      "schulze-wv"

      Schulze method - use 'winning votes' to measure victory strength.

      "schulze-wv-mod"

      Schulze method - use 'winning votes' to measure victory strength, and use 'margins' to resolve ties.

      "smith"

      Choses the member(s) of the Smith set

    • methods: (seq) - Used in conjunction with the chain method. This defines an ordered sequence of methods to use in calculating the winner.
      • (map) -
        • type: (str) - Any valid election method type. See documentation for 'type' parameter under 'election_methods' for more information.
• features: (map) - List of important features/characteristics useful in comparing candidates. 'Political party' is an example of a candidate characteristic important while voting. These features will be listed in a separate column from the candidates' names, and will be sortable.
  • (feature identifier): (map) - Parameters for a particular feature.
    • display_name: (str) - The label for use in the column header.
    • url_field: (str" "desc": "A field identifier for an optional URL associated with a particular feature. The identifier defined here can be used in the (candidate key) mapping defined above.) -
• max_rating: (int) - Maximum rating that voters may assign to a candidate. Not respected by all ballot types.
• min_rating: (int) - Maximum rating that voters may assign to a candidate. Not respected by all ballot types.
• radioarray_labels: (map) - Set of labels to use when the "radioarray" value for ballot_type is chosen.
  • (rating value): (str) - label associated with this particular numerical rating.

---

Note: the configuration parameters list above is semi-automatically generated from the JSON file at Election Config Schema, so any changes need to be also made there in order for changes to be permanent.