Provide Percentage for Ballot Item Results

[bradley-holt]

Description

In addition to the number of votes, please provide the percentage of the total votes that those votes represent for each ballot item result.

Steps to Reproduce

curl 'https://example.org/town-meeting-season-2011/town-meeting-day-2011/city-of-burlington' \
-H 'Accept: application/json'

Actual Results

{
   "title":"City of Burlington",
   …
   "ballot_item_results":{
      …
      "113838":{
         "text":"Approval of Increase in Maximum Tax Rate for…",
         "results":{
            "Yes":1849,
            "No":4047
         }
      },
      …
   }
   …
}

Expected Results

{
   "title":"City of Burlington",
   …
   "ballot_item_results":{
      …
      "113838":{
         "text":"Approval of Increase in Maximum Tax Rate for…",
         "results":{
            "Yes":{
               "votes":1849,
               "percent":31.4
            },
            "No":{
               "votes":4047,
               "percent":68.6
            }
         }
      },
      …
   }
   …
}

Additional Comments

The benefits of having this in the JSON, as opposed to calculated in JavaScript, include:

• Consistency of rounding in HTML and JavaScript
• Allows the module to determine the precision in one place
• Reduced duplication of logic

[gdoteof]

Internally, we are building the data structure to match the original spec; with HTML and CSV representations being generated from that.

This change forces a rewrite of other parts of the code; tabling for now. Please comment on how necessary this is.

[bradley-holt]

This is trivial to implement in JavaScript. However, my main concern is that it opens up the possibility of inconsistencies (see Dont Repeat Yourself, a.k.a. Single Point Of Truth). In the HTML view, the percent value is calculated by dividing the result by the total votes, multiplying this by 100, and then number formatting the resultant number with 1 decimal place. Duplicating this logic in JavaScript brings the following risks:

1. Somehow the server and JavaScript end up with different values for the total votes
2. The exact method of rounding is inconsistent between the HTML view and the JavaScript (unlikely)
3. The method of rounding gets changed in the HTML view (e.g. to floor or ceiling), but not in the JavaScript
4. The number of decimal places changes in the HTML view, but not in the JavaScript

Point 1 could be solved by providing the total of all votes in the JSON, as a consistency check. Points 2 and 3 can be mitigated by having a clear expectation as to how rounding will be performed (which I think we already have). Point 4 could be addressed by providing the number of decimals to which to round in the JSON (perhaps a precision field). Would adding fields for total votes and precision be easier, or would these require a rewrite as well?

[acrawford]

hmm maybe I'm not understanding how this was going to work... I was going to use a list of election season Drupal nodes via views, that would allow you to click on an election event. The clicked link would take you to a page that is the Drupal node for that event, with a node_election_event.tpl.php template. In that template, The basic HTML elements of the page would already exist. I would load jQuery, CSS, and the custom JavaScript from Bradley/Jason to:

1. query the API for data
2. output the data to the proper DOM element(s)
3. style the proper DOM element(s)

in this way, the HTML output of the API was just for testing purposes (it will actually never be used/linked to on the website).. so no worries about % consistency. I figured everything would flow via JSON. I guess it is poor form to have the .js generate HTML elements (result tables) and so the HTML output has some utility. What is the intent on how this is going to work? /me shoot self in foot

[bradley-holt]

In general, I think it's a good practice to make things work without JavaScript being required and then enhance with JavaScript. Even though almost everyone has JavaScript enabled these days, we've found that it builds a discipline into the process that helps expose potential issues and creates a better product in general. There are also other benefits such as SEO and better accessibility (although most screen readers can execute JavaScript now). Another benefit is that if we need to introduce navigation (e.g. for navigating districts and/or drill downs), then we can use the hash-bang URL pattern (or HTML5 push state) for AJAX driven navigation of content that exists in HTML. Twitter does this, for example, where http://twitter.com/#!/BradleyHolt maps to http://twitter.com/BradleyHolt. This helps generally to keep things sane, helps with SEO, and allows users to share links to specific content.

[gdoteof]

I agree with your reasons @bradley-holt , though I think in this case '%' can reasonably be considered an enhancement since we really aren't providing any new information; it's just prettying up what is already there.

However since we need to include the winner anyway; it makes sense to do that at the same level as 'percent' and 'votes' so it is trivial to add this as well.

[bradley-holt]

If I end up doing it in JavaScript, it's fairly trivial. This was more of an issue of maintainability. If it's trivial to add this along with the "winner" data, then great.

[gdoteof]

this is added with fd22384966b361242f0184a1f28c28f8a6ba94f0

[bradley-holt]

I'm still seeing the same results in the JSON. Has this been deployed?

[gdoteof]

oh. hmm. I put the percentage at the ballot item level. Are you even using this results array at the district level for anything? It wasn't in the API and I put in there.. not sure why.

I will add the percentage though to this just for completeness, but do wonder if it is being used. (it isn't being rendered in the HTML)

[gdoteof]

ok, really fixed with 50c4010

[acrawford]

this change is now on live on dev and percentages are there in the city-of-burlington JSON

[bradley-holt]

That's a good point, not sure if we'll end up using it at this level or not. Regardless, it's working now—thanks.