Polls Module

From ActionApps Documentation
Jump to: navigation, search

Polls Module

Polls module - main settings

Polls is a module in ActionApps which can be used for managing polls on your web pages.

Generally it works similarly as a normal slice - you create the polls module instance (see AA menu) - just like normal slice. Then you can put there as many polls as you want - just like items in your slice.

The polls in the polls module then can expire, they can be pending, you can move them in Holding bin or ever trash them.

If you went to display the poll, you just include the polls module in the page and you will see the first poll (in most cases). However, as you already know, each poll could expire, so next time you can see different poll on the page.

You can display the poll inside shtml page, as well as in pages designed by Site Module.

Each poll can use its own design. There are set of predefined designs of polls, but you can define your own. Then you just assign the design to the poll. You can change the assigned design of the poll any time you want, since the poll data and designs are independent. You can also change the predefined design by an url parameter, so you can for example browse all polls with design not allowing to click on the answers.

Add Poll

Form for adding a new poll

At this form you can edit name of the new poll, possible answers, publishing and expiring date and designs (before and after vote) of the poll.

The same form is used for editing already existing polls.

You can also change following parameters (most of them are predefined at Polls admin form):

Poll is locked

If checked no votes are counted.

Use logging

If checked all votes are logged in the database table polls_log. IP address, timestamp and the voted answer is logged. These data are supposed to be accessible via ActionApps in the future.

Use IP locking

If checked it can be voted only once from every IP address.

IP Locking timeout

After this time it is possible to vote again from the same IP adress. 0 (zero) means new vote at this poll from the same IP address will be never possible.

Use cookies

If checked it can be voted only once from every browser.

Parameters

In this field you can type any text. This text can be showed in poll design or used for filtering displayed polls etc.

Displaying Polls

Polls can be displayed on your web pages by the SSI include command:

<!--#include virtual="/apc-aa/modules/polls/poll.php3?pid=module_id"-->

where module_id is identification of your polls module.

Example:

<!--#include virtual="/apc-aa/modules/polls/poll.php3?pid=35d5d95a490b385ac7d03650e7aa496d"-->

You can also include the poll in the site which uses Site Module using {polls:module_id}

Example:

{polls:35d5d95a490b385ac7d03650e7aa496d}

The display form can be modified by Url Parameters (see bellow).

Different IDs Types

Before we will describe the url parameters, it is quite important to understand different types ids used in polls module:

module_id - the id of whole polls module - similar to slice_id. Each polls module contain as many polls as you want. This id you will use as pid parameter when you are including polls module in the page (see above)

poll_id - the id of one poll inside the polls module - similar to item_id in slice. One poll_id represents one question (with many answers, of course)

answer_id - the id of one answer inside one poll. Also the answer have its own properties, like id, text, number of votes for the answer... You will work with answers when you will specify the design of the poll


URL Parameters

URL parameters are used in the same way as url paramaters for slice.php3 script, see Slice parameters. Following parameters are avalaible:

  • poll_id
  • listlen
  • design_id
  • conds[]
  • sort[]

poll_id

This parameter allows you to display one particular poll defined by its id. Id of the poll can be found in Polls manager.

Example:

poll_id=37eb9bbe53a2d46476ea4ec4b134e60c

listlen

This parameter defines maximal number of viewed items. Default value is 1 so you must use this parameter to browse more than one poll.

Example:

listlen=5

design_id

This parameter allows to redefine design of displayed polls. Id of the requested design can be found at Polls admin - design.

Example:

design_id=ece606be289bfac692f840f85a7fce4f

conds[]

Conditions can be used for filtering displayed polls. You can use two types of syntax as shown in example. For more information on conditions see Slice parameters.

Examples:

conds[0][headline]=ActionApps&conds[1][params]=test
conds[0][operator]=RLIKE&conds[0][value]=ActionApps&conds[0][headline]=1&conds[1][operator]=LIKE&conds[1][value]=test&conds[1][params]=1

sort[]

If you display more polls you can sort them by using this parameter. For more information on sorting see Slice parameters.

Examples:

sort[0][headline]=a

Polls Design

Polls designs is defined on Polls admin - Designs. You can define any number of designs. Every poll can have only one design before vote and another design (or the same) after vote (or you can use different design using design_id url parameter). The designs are assigned to each poll in the Add poll form.

Field and aliases

Concerning the whole poll
Alias Content
_#QUESTION Prints poll question
_#PUB_DATE Poll publish date in dd/mm/yyyy format. see {poll:poll_id:publish_date} for timestamp
_#EXP_DATE Poll expiry date in dd/mm/yyyy format. see {poll:poll_id:expiry_date} for timestamp
_#PARAMS__ Additional poll parameter used for anything at your will
_#MODULEID Poll module ID (32 characters long hexadecimal number)

Remember there are three types of ids used in polls module - module_id, poll_id and answer_id - see the description above.

_#POLL_ID_ Poll id (32 characters long hexadecimal number - the same for all answers)
_#ANS_SUM_ Sum of all votes for the poll. You can use also {poll_sum}.


Concerning answers (returns different values for each answer)
_#ANS_NO__ Answer number - counted from 1 to number_of_answers in the poll
_#ANS_VOTE Number of votes for this answer
_#ANSWER__ Text of that answer
_#ANS_ID__ ID of answer (32 characters hexadecimal number)
_#ANS_PERC Votes for this answer in percent (0-100). See also {poll_share} bellow for more options.


Instead of aliases there is curly brackets syntax possible:

{poll_sum}

Displays the number of all votes in the poll. The same as _#ANS_SUM_


{poll_share[:<max>]}

Displays number representing current share of the votes for the answer. By default it is in scale of 0-100, so without parameter - {poll_share} - it could be used as percent value (and is equal to _#ANS_PERC alias). You can specify the max parameter, so the values could be from 0 to max which could be used as image width, for example.

Example:

<div style="height:10px; width:{poll_share:500}px;background-color:#f00"> </div>


{poll:<poll_ids>:<aa_expression>}

where:

  • poll_id is the id of the poll (not poll module, but poll as one question).
  • aa_expression - field from 'polls' table or any other AA expression

Examples:

{poll:425a6b7b5989b77e7a98e654e6e4e56e:_#ANSWER__ - _#PARAMS__}
{poll:425a6b7b5989b77e7a98e654e6e4e56e:publish_date}

The possible fields from polls table are: id, module_id, status_code, headline, publish_date, expiry_date, locked, logging, ip_locking, ip_lock_timeout, set_cookies, cookies_prefix, design_id, aftervote_design_id, params

AJAX Polls Design

You can also use AJAX for sending the Polls, so only the Poll is reloaded, not whole page. The example of such poll design:

Top HTML

 <form id="anketa_#POLL_ID_" name="form1" method="post" action="/apc-aa/modules/polls/poll.php3">
 <div>
   <h4>_#QUESTION</h4>
   <table border="0" cellspacing="0" cellpadding="0">

Answer HTML

     <tr>
       <td><input type="radio" name="vote_id" value="_#ANS_ID__"></td>
       <td><div style="width:{poll_share:200}px;" class="indicator"> </div> /  _#ANS_VOTE <label>_#ANSWER__</label></td>
     </tr>

Bottom HTML

    </table>
    <div style="text-align: right;">
     <input type="hidden" name="poll_id" value="_#POLL_ID_">
     <input type="hidden" name="convertfrom" value="windows-1250">  <!-- not necessary for 8859-1 or utf pages -->
     <input type="button" onclick="AA_AjaxSendForm('anketa_#POLL_ID_');return false;" name="button2" id="button2" value="Vote" class="button">
   </div>
 </div>
 </form>

You have to include /apc-aa/javascript/aajslib.php3 in your pages - just like:

 <script src="/apc-aa/javascript/aajslib.php3" type="text/javascript"></script>