New API Call for Parent + sub-data of ballot item results

[gdoteof]

Essentially what we need to add is a new API call --or-- to potentially change the API spec.

What we need is to get not only the ballot item results at a given level, but also the 'partial results' that makes up the data, if there is any.

For our examples, we need to be able to both see results for a district, and the partial results for the sub-districts.

[acrawford]

We are organizing results by Ballot Item (Tagged as Referendum or Election), but querying them with a combined e/Election-Season/Election-Event/District/Ballot-Item.html (to build the skeleton) or e/Election-Season/Election-Event/District/Ballot-Item.json (to query the data) call to the API.

Disambiguation: We are NOT looking for Example 1, correct?

Example 1 With "sub-districts"

<article>
  <h1>City of Burlington Mayor</h1>
  <table>(summary of results here)</table>
  <article>
    <h1>City of Burlington Mayor Sub-District Results</h1>
    <table>(detailed results here)</table>
  </article>
  <article>
   <h1>City of Burlington Mayor 2nd Sub-District Results</h1>
   <table>(detailed results here)</table>
  </article>
  ...
</article>
...

Example 2 At lowest District (the District with which there is no finer grained result available / the resolution of the data )

<article>
  <h1>Ward 1 City Councilor</h1>
  <table>(summary of results here)</table>
</article>

So to get the Example 1 format, we need to be able to produce the Example 2 in the HTML API and then nest those as displayed in the top example. I believe that is analogous to what we are currently doing nesting sub districts with the current skeleton. To me, this appears as a straight call to the API to return the HTML at a particular District / Ballot Item combination. I think we actually want this (from my notes...):

Example 3 With "sub-districts"

<article>
  <h1>City of Burlington Mayor</h1>
  <table>(summary of results here)</table>
  <article>
    <h1>City of Burlington Mayor All Sub-District Results in one table below</h1>
    <table>( All detailed sub-district results here)</table>
  </article>
</article>
...

Example 4:

Sub District breakdown:

  <article>
    <h1>Sub-District Results</h1>
    <table>( All detailed sub-district results here)</table>
  </article>

Then we definitely need a new API call to produce the "All detailed sub-district results here table". My understanding is that we are after Example 3. This means that we are calling the existing API for the HTML output in Example 2 for the "oldest parent"/ "closest to the root" District and Ballot Item combination. (determined through some as of yet unwritten function, or by finding and choosing the "topmost/root District" In the tree). We are then nesting the as of yet un-written API call that returns Example 4 HTML and are nesting it into Example 2 to get Example 3.

-OR-

We are building a function that returns Example 3 whenever you query a District/Ballot Item combination, and you just omit the nested

<article></article>

tags if there are no sub districts.

It seems like the way the results are serialized would need to be changed if we built the basic "atom" of the HTML output at the level of Example 3, as you are expecting the JSON to output just one District/Ballot Item combination for updating purposes. This seems like it would break the UI code.

Questions:

Bradley / Jason, for the data link to pull in updated info via the JSON API, everything is currently engineered to look at the data-link, one data link per

<article></article>

tag, correct?

Example from current page source:

<article id="-ward-1---school-commissioner" class="ballot-item-results " data-link="/e/town-meeting-season-2012/town-meeting-day-2012/city-of-burlington/ward-1---school-commissioner">
<h1 id="-ward-1---school-commissioner-h1">Ward 1 - School Commissioner</h1>
<table>
    <thead>
      <tr class="result">
        <th class="option "><span class="graph-swatch"></span>Options</th>
        <th class="votes">Votes</th><th class="percent">Percent</th>
      </tr>
    </thead>
    <tbody>
      <tr class="result winner complete ">
        <td class="option "><span class="graph-swatch"></span>Katharine_Chasan_*</td>
        <td class="votes"> 686</td>
        <td class="percent">100.00</td>
      </tr>
    </tbody>
</table>
<ol class="graph">
<li class="result " title="Katharine_Chasan_* : 686 votes, 100.00%" style="width: 100.00%"><span class="option">Katharine_Chasan_*</span> : <span class="votes">686</span> votes, <span class="percent">100.00</span>%</li>
</ol>
<footer>
<p class="complete">These are complete but unofficial results</p>
<p>Updated <span class="updated">Sep 11, 2012 10:28:25 PM</span></p>
</footer>
</article>

OK, sooo Burlington Mayor, in our new setup ( Example3 ), would theoretically look something like this:

<article id="-mayor" class="ballot-item-results " data-link="/e/town-meeting-season-2012/town-meeting-day-2012/city-of-burlington/mayor">
<h1 id="-mayor-h1">Mayor</h1> 
<table>
    <thead>
      <tr class="result">
        <th class="option "><span class="graph-swatch"></span>Options</th>
        <th class="votes">Votes</th><th class="percent">Percent</th>
      </tr>
    </thead>
    <tbody>
      <tr class="result  complete ">
        <td class="option "><span class="graph-swatch"></span>Wanda_Hines_(I)</td>
        <td class="votes"> 498</td>
        <td class="percent">4.96</td>
      </tr>
      <tr class="result  complete ">
        <td class="option "><span class="graph-swatch"></span>Kurt_Wright_(R)</td>
        <td class="votes"> 3746</td>
        <td class="percent">37.29</td>
      </tr>
      <tr class="result  complete ">
        <td class="option "><span class="graph-swatch"></span>Miro_Weinberger_(D)</td>
        <td class="votes"> 5801</td>
        <td class="percent">57.75</td>
      </tr>
    </tbody>
</table>
<ol class="graph">
<li class="result " title="Wanda_Hines_(I) : 498 votes, 4.96%" style="width: 4.96%"><span class="option">Wanda_Hines_(I)</span> : <span class="votes">498</span> votes, <span class="percent">4.96</span>%</li>
<li class="result " title="Kurt_Wright_(R) : 3746 votes, 37.29%" style="width: 37.29%"><span class="option">Kurt_Wright_(R)</span> : <span class="votes">3746</span> votes, <span class="percent">37.29</span>%</li>
<li class="result " title="Miro_Weinberger_(D) : 5801 votes, 57.75%" style="width: 57.75%"><span class="option">Miro_Weinberger_(D)</span> : <span class="votes">5801</span> votes, <span class="percent">57.75</span>%</li>
</ol>
<!--end summed results-->
<article id="city-of burlington-mayor-detail" class="ballot-item-results election" ><!-- data-link="/e/town-meeting-season-2012/town-meeting-day-2012/city-of-burlington/mayor"  get rid of this and have the data links on each <td> element?--> 
<h1 id="mayor-detail">Mayor Breakdown</h1>
<table>
    <thead>
      <tr class="result">
        <th class="option candidate"><span class="graph-swatch"></span>Candidates</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-1/mayor" class="votes">Ward 1 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-2/mayor" class="votes">Ward 2 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-3/mayor" class="votes">Ward 3 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-4/mayor" class="votes">Ward 4 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-5/mayor" class="votes">Ward 5 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-6/mayor" class="votes">Ward 6 Votes</th>
        <th data-link="/e/town-meeting-season-2012/town-meeting-day-2012/ward-7/mayor" class="votes">Ward 7 Votes</th>
      </tr>
    </thead>
    <tbody>
    <tr class="result ">
      <td class="option candidate"><span class="graph-swatch"></span>Miro Weinberger (D)</td>
      <td class="sub-district-result">602</td>
      <td class="sub-district-result">554</td>
      <td class="sub-district-result">846</td>
      <td class="sub-district-result">970</td>
      <td class="sub-district-result">1153</td>
      <td class="sub-district-result">868</td>
      <td class="sub-district-result">808</td>
    </tr>
    <tr class="result ">
      <td class="option candidate"><span class="graph-swatch"></span>Kurt Wright (R)</td>
      <td class="sub-district-result">233</td>
      <td class="sub-district-result">174</td>
      <td class="sub-district-result">313</td>
      <td class="sub-district-result">1113</td>
      <td class="sub-district-result">520</td>
      <td class="sub-district-result">396</td>
      <td class="sub-district-result">997</td>
    </tr>
    <tr class="result ">
      <td class="option candidate"><span class="graph-swatch"></span>Wanda Hines (I)</td>
      <td class="sub-district-result">49</td>
      <td class="sub-district-result">119</td>
      <td class="sub-district-result">140</td>
      <td class="sub-district-result">40</td>
      <td class="sub-district-result">61</td>
      <td class="sub-district-result">36</td>
      <td class="sub-district-result">53</td>
    </tr>
    </tbody>
</table>
<!-- show no graph? -->
<!-- show no footer? (partial and/or completeness message ? updated time ) -->
</article>
<!--end partial results-->
<footer>
  <p class="complete">These are complete but unofficial results</p>
  <p>Updated <span class="updated">Sep 11, 2012 10:28:25 PM</span></p>
  <p>(*) Signifies Incumbent</p> 
</footer>
</article>

Ok that was my first stab at it, Jason, Bradley, Geoff, Ideas?

[acrawford]

Here is Bradley and Jason's suggested nesting.

Jason and I talked about this and we've come up with a modified plan that (we think) will address all of the concerns you brought up. Instead of a nested table, let's go back to a set of nested sub-articles (one for each sub-district). Using CSS and/or JavaScript, we will hide the details and only show the summary by default. Then (also using CSS and/or JavaScript), we will show only one of the detail results when a user interacts with a specific element (probably a hyperlink) and only ever show one detail (i.e. sub-district) at a time. This way, the user can "navigate" between detail items without getting overwhelmed by seeing all of the detail at once. It's important to note that you will not see all sub-districts at the same time. You will always see the summary table and optionally one sub-district. This likely does not address LG's request for a view with all sub-district results simultaneously (so you may want to circle back with LG about this). Realistically, though, the table approach is not scalable to include all sub-districts.

The HTML might look like this:

<article>
  <h1>City of Burlington Mayor</h1>
  <table>(summary of results here)</table>
  <article>
    <h1>Wards</h1>
    <article>
      <h1>Ward 1</h1>
      <table>(Ward 1 Mayor results here)</table>
    </article>
    …
  </article>
</article>

If there are no sub-districts, then the nested article would not be displayed:

<article>
  <h1>Ward 1 City Councilor</h1>
  <table>(summary of results here)</table>
</article>

This addresses the following concerns/problems: The display will be scalable beyond a handful of sub-districts (i.e. the 20 Chittenden County Senate sub-districts). The data-link attribute would get added exactly like it does now. JavaScript/JSON API updates would work exactly the way they do now.

[acrawford]

I updated the API to output the basic

HTML as well as a fully formed updating page.

Article HTML output for a single ballot item - district combination is accessed as before:

e/election-season/election-event/district/ballot-item

e/general-election-2012/general-election-2012-election-night/chittenden-county/chittenden-state-senate

HTML page ouptut for a single ballot item - district combination is accessed by:

e/election-season/election-event/district/ballot-item.skl

e/general-election-2012/general-election-2012-election-night/chittenden-county/chittenden-state-senate.skl