Using the Election Widget

by
Categorized in: Product development, Time-savers | Comments not allowed
   
       

Using the Election WidgetElectionsOnline makes available an election widget you may place on your own website as one option for displaying current election information and including a link to the ballot. The widget, demonstrated at this location, amounts to a snippet of code (included below) you place on your website at the point where you wish for the widget to display. There is virtually no technical skill required to do this, as it simply amounts to a copy and paste, but it does require having access to the code of the page where the widget is to appear. It will then display:

  • The election name
  • The election start date
  • The election end date
  • A link to the ballot (only displays for elections that are currently running)

Why use the widget?

Admittedly, for clients who conduct only one or two elections a year, it will be simpler to just type a link onto their website that links to the ballot as discussed in 3 Tips for Linking to the Ballot. This widget could be a time saver though for clients running multiple elections concurrently. When that’s the case, manually adding and removing election details from your website when there are multiple elections being juggled around could create an administrative headache and a strong likelihood of human error. In this case, the widget could keep track of all that for you, only showing information for upcoming elections, and only include a link to the ballot when voting is open.

Placing the widget on your website

  1. Get your account’s token. To do this:
    1. Log in to your account.
    2. Click My Info.
    3. Click Account profile.
    4. Your token, which appears near the top of your profile, will need to be supplied to the code snippet in step two. There are two tokens, an API token and a widget token. Take care to select the widget token for this purpose.
       
  2. Paste the code below onto your site where you wish the widget to appear, taking care to replace the string of Xs as the value for token with the actual value you acquired in step one.

    <link href="https://www.electionsonline.com/widgets/styles.css" rel="stylesheet" type="text/css">
    <script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
    <script>var queryString = {token:"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",destination:"www.electionsonline.com/vote/login.cfm"};</script>
    <script src="https://www.electionsonline.com/widgets/elections.js"></script>
    <div id="getelections"></div>

That’s all there is to it. The widget will begin immediately displaying the upcoming election information associated with your account. But there’s much more that can be done to affect its behavior and style as explained below.

The widget and jQuery

The widget relies on jQuery running on the web page where it’s placed since it uses jQuery’s ajax method. The line in the snippet containing jquery.min.js includes a reference to jquery, so using that complete snippet ensures everything that’s needed will be included in the snippet. However, if you already have jquery running on the page where you wish to place the snippet, you should omit the reference to jQuery from the snippet above.

Setting the link destination

The widget’s default behavior is to create a link to the ballot on the ElectionsOnline website found at www.electionsonline.com/vote/login.cfm. However, if you’re using a single sign-on solution, the login page will be somewhere on your site and the link should point to that. To overwrite the default link to ElectionsOnline with one on your own site, find the following line of code in the snippet:

<script>var queryString = {token:"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",destination:"www.electionsonline.com/vote/login.cfm"};</script>

and change the value of the destination to your own ballot login page so it would look something like:

<script>var queryString = {token:"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",destination:"www.yourdomain.com"};</script>

In this example, the text that changed is shown in italics. Replace the text in italics with the destination of the ballot on your own site.

Sizing and positioning the widget

The widget fills 100% of the width of its containing element. If you wish to control that width, one approach could be to place the widget inside a wrapper by placing the entire snippet above inside a pair of <div> tags. You may then apply whatever width and height settings you wish to that wrapper. You may also use CSS to position the wrapper with exacting precision so that it appears right where you want on your web page. This approach is being used on the sample widget on this site. If you wish to see that, visit www.electionsonline.com/widgets and view the source of that page for the spot where the widget appears.

Styling the widget

Usually with any widget, you have no ability to apply any styling of your own to make the widget match the look and feel of your own site. That is not the case with the election widget. Every element in the widget has its own CSS (Cascading Style Sheet) class assigned to it, and those classes reference a style sheet attached to the widget. However, you may remove that attachment, thereby removing the default styles, then apply your own custom style to the classes to give the widget exactly the look and feel you want. This does require knowing how to write your own CSS, but for those who do, you may:

  1. Simply remove the following line of code from the widget’s code snippet. <link href="https://www.electionsonline.com/widgets/styles.css" rel="stylesheet" type="text/css">
     
  2. Now create your own CSS styles for the classes and include them on the page where the widget appears. You may include them in an external style sheet, or use an embedded style sheet directly in the <HEAD> section of the page(s) where the widget appears, but you will need to know the class names to get started. The easiest way to do this is to use the style sheet attached to the widget by default as a starter template, then generate your own CSS rules from that. The address for the default styles is https://www.electionsonline.com/widgets/styles.css.

Responsive widget behavior

A couple things make the widget responsive so that it adjusts in response to the dimensions of the viewport being used to view it from across a range of devices. Those things are:

  1. The width is not hard coded. Its default behavior is to fill 100% of the width of its containing element. This is not so much true responsive design as much as it is simply a flexible width to ensure text wraps nicely.
     
  2. The widget displays content in two columns. The left column contains a graphic. If you wish to either not include this graphic in the widget at all, or have it disappear when the width of a viewport is less than some fixed amount, you may simply set a CSS rule like the following: .voteicon {display:none} That makes the vote graphic disappear and the content in the right column will shift to the left to fill its space.

Bonus widget capabilities

By default, this widget returns content ready for output in HTML format, but you can call the URL passed into the widget to get election data in other formats by adding the format variable to the URL and setting its value to one of the three following:

  • xml
  • json
  • list (using a semi-colon as the delimiting character)

Using xml as an example, the URL would look like:

https://www.electionsonline.com/widgets/getelections.cfm?token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx&format=xml.

When doing this, you’re not actually using the widget in the same sense as has been discussed throughout this article. More simply, you’re just treating the URL passed into the widget as a REST-ful web service. You would not place the entire widget’s code snippet onto a page for output when doing this. You would make an http get request from your server for the URL as shown in the example above. The response from that request then comes back in either xml, json or as a list format which additional processing could parse over and do whatever you wish.

Conclusion

When just placing a link on your website’s homepage will do, that’s probably the simplest, quickest thing. But when elections are an ongoing part of an organization’s operations, this widget can offer a set-it-and-forget-it approach to keeping timely links and information about those elections on your site without the headache of ongoing, manual administration.

   
       
Powered by...
Mango Blog