Polling Module

The Sitekit Polling module can be used to integrate a simple voting form on your website that any visitor can use.

The simplest type of poll is a form with a yes/no option. The results of the vote are typically shown alongside the form with a percentage value.

Your web site needs to have access rights to the Sitekit CMS Forms API and XML consumer API.

You also need to know how to

create and style Sitekit embedded forms, and work with XML/ XSL data islands.
The elements needed to integrate this feature are:

The actual polling form which is embedded on the web page
The XML feed from the form results aggregation web service
The XSL transform document which converts the XML into HTML
The Sitekit CMS Data Island which applies the XSL transform to the XML, outputting the HTML
The CSS needed to style the polling form and poll results

The form element itself is a standard Sitekit CMS form which can be embedded in a template, variable block or page using the ENQUIRYFORM xml sniplet:

You can find the FORMID value once you have created the form, by going to the Forms panel in Sitekit CMS. Next to “Click to get form summaries” click “List” and you will get a list of all the forms on your site, along with their ID’s which is what should be used for the “FORMID”.

More information on embedded forms can be found in the Sitekit CMS help.

Key Notes

When setting up the form in Sitekit CMS, it is critical to tick the “Aggregate results from form” box so that the poll results are aggregated and displayed correctly.
The form field containing the poll question should be set up as a single “Option (vertical)” or “Option (horizontal)” field.
The Yes/No options are set up in stage 2 of the form configuration as the Data Entry Option and Display values.

These are the only special requirements to set up the form. You can customize these options as appropriate, but otherwise it is the same as setting up a regular embedded form.

Working with the results

The results are separate, and driven by the forms web service:

http://secure2.sitekit.net/admin/ws/Forms.asmx?op=GetAggSubmissions

The “GetAggSubmissions” operation which is used aggregates all results from a form into an XML feed which can then be processed via an XSL transform in Sitekit CMS. The XML and XSL are combined in a Sitekit data island, for example:

As form results are usually only displayed securely, this web service requires a username and password. The user needs to be set up in Sitekit CMS with access to form configurations and results. It can be added in as an administrator or in a separate user group with these user rights.

Once you have created the user and the form, we can now provide the 4 fields needed to extract the aggregated results using the GetAggSubmissions operation.

The domain can be any live domain on your site, usually the master domain, i.e. “www.sitekit.net”

The “formModuleID” is the ID of the poll form you created earlier. You can find the ID by going to the Forms panel in Sitekit CMS. Next to “Click to get form summaries” click “List” and you will get a list of all the forms on your site, along with their ID’s which is what should be used for the “formModuleID” field.

Once you have these four pieces of information you can construct the XML address to be used in the data island:

http://secure2.sitekit.net/admin/ws/Forms.asmx/GetAggSubmissions?username=polluser&password=pollresult&domain=www.yourdomain.co.uk&formModuleID=0123

Remember to check which server your site is using, i.e. secure.sitekit.net, secure2.sitekit.net or otherwise.

Working with the XSLT

When it comes to writing the XSL, you will be writing for an XML feed that looks something like this:

<?xml version="1.0" encoding="utf-8"?>
<SurveyResults responses="553">
  <Questions>
    <Question>
      <QuestionText>Do you like our new website?</QuestionText>
      <QuestionID>1</QuestionID>
      <AnswerOptions>
        <AnswerOption>
          <Label>Yes</Label>
          <Count>447</Count>
          <Percentage>80</Percentage>
        </AnswerOption>
        <AnswerOption>
          <Label>No</Label>
          <Count>106</Count>
          <Percentage>19</Percentage>
        </AnswerOption>
      </AnswerOptions>
    </Question>
</Questions>
</SurveyResults>

The XML output calculates the <Percentage> value for you. You will notice that the values do not add up to 100% - usually they will add up to 99%. This is due to a rounding problem, as the web service always rounds decimal numbers down - if it was to round up, and there were two “.5” values, you would get a total percentage of “101%”.

Your XSL will look something like the example below. Once you have written the XSL, it should be submitted to the XSL approval procedure and uploaded by a member of Sitekit staff to a location with XSL upload rights, usually xsl.sitekit.net.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1">
       <xsl:output method="html" />
       <xsl:template match="Question">
              <xsl:for-each select="AnswerOptions/AnswerOption">
              <xsl:if test="Label='Yes' or Label='yes' or Label='YES'">
              <div class="pollRes"><div class="pollResInner" style="width:{Percentage}px;"></div></div>
              <div class="pollResVal"><span><xsl:value-of select="Percentage" />%</span></div>
              </xsl:if>
              </xsl:for-each>
              <xsl:for-each select="AnswerOptions/AnswerOption">
              <xsl:if test="Label='No' or Label='no' or Label='NO'">
              <div class="pollRes"><div class="pollResInner" style="width:{Percentage}px;"></div></div>
              <div class="pollResVal"><span><xsl:value-of select="Percentage" />%</span></div>
              </xsl:if>
              </xsl:for-each>
       </xsl:template>
</xsl:stylesheet>

Once the XSL is written and the XML address is constructed, the Sitekit CMS Data Island can be embedded in the page or template, usually next to the embedded form.

This will output HTML similar to the following:

<div class="pollRes">
<div class="pollResInner" style="width:80px;"></div>
</div>
<div class="pollResVal"><span>80%</span></div>
<div class="pollRes">
<div class="pollResInner" style="width:19px;"></div>
</div>
<div class="pollResVal"><span>19%</span></div>

This HTML output and the form can then be styled with CSS in the style sheet attached to your page.

Additional Notes

As a caution, you should make sure that no elements of the polling form are changed in the future, as this may reset the results and also break the XML/XSL transform.

Knowledgebase

Polling Module

Key Notes

Working with the results

Working with the XSLT

Additional Notes

Related questions

Menu