[Snippet/Module] EasyPoll 0.3, released!#

Important update: EasyPoll can now be found in the MODx Resource Repository.
The following documentation is outdated. Please consider reading the Documentation that comes with the EasyPoll Download or read it online.
Please post feedback, error-reports or suggestions in the support thread: http://modxcms.com/forums/index.php/topic,22981.0.html

---

Hello all

Some of you might have seen my thread in the Module, Plugin & Snippet Forum. I started to develop a new Poll Module for MODx. First based on the Poll Module by garryn, this has turned into a full rewrite.

Now the first release is up for you to grab and test. It would be awesome if some of you would take the time to install and test! Everything worked just fine here, but you never know how it runs on another box.

Attention: This modules requires at least PHP 5 and MySQL 4.1. Do not attempt to run it when you do not meet these requirements
Please note that there are currently only lang files for German and English (these are most likely not perfect, since English is not my native language). New: Dutch translation by peterruiter, thanks a lot

Installation instructions:

[list]
• Grab EasyPoll 0.3. Unzip to a directory of your choice

• You should see two folders, modules and snippets (plus maybe some mac garbage, sorry for that )

• Copy the EasyPoll Folder from modules to your modx modules directory. Copy the EasyPoll Folder from snippets to your modx snippets directory

• Create a new Snippet called "EasyPoll" and copy/paste the contents from snippet.php (to be found in the snippets/EasyPoll folder) into it.

• Create a new Module called "EasyPoll" and copy/paste the contents from module.php (modules/EasyPoll) into it (don't forget to remove the <?php ?> Tags)

• Still in "Manage Modules", click on the icon on the left of the newly created "EasyPoll" Module and select "Run module"

[/list]

You should now see something like this:

[list]
• Click the install button to create the needed tables. If this completes successfully, you might want to delete the setup.sql file (it was used to create the db tables)

• You should now see several Tabs. First go to "Languages"

• Create the Languages you would like to create Polls for. Even on a 1 language site, you have to at least create one language.

[/list]

Here is how it looks with 4 languages:

[list]
• You can now move on to create your polls. Switch to the "Polls" tab and create a new Poll by filling the fields

• Start-date and End-date are optional. You can specify a start and/or end date for your poll here. If you don't set the Start-Date, it will be set to the current date. This allows you to change your polls appearance on your site (by changing the start-date).

• The "Active" checkbox determines weather or not this Poll is currently active. Poll that are NOT active won't be shown on your Site!

• After creating a poll, you may click the "Edit choices" Button to add/edit or remove Poll choices

[/list]

Here are two screenshots of the Poll editing process:

Continue to create more polls and choices...

Snippet usage Basically a call like [!EasyPoll!] will work. This won't fit your needs in most of the cases though. You need some parameters:

&pollid Poll ID to be used. If not set, the snippet will choose the most recent Poll (must be active and fully translated)! You are encouraged to omit this parameter, since it opens the possibility for you to administrate polls in the manager and have them automatically updated on your site. (defaults to false)
&lang the language to use for snippet translations (defaults to 'en').
Currently available Languages: de, en, nl
&easylang the language for poll questions and answers (as set up in manager). defaults to the &lang param
&onevote Boolean indicating if a user is allowed to vote just once (defaults to false)
&useip Boolean indicating if we should log the users ip to allow just one vote (defaults to false)
&ovtime Cookie expiration time (defaults to one week)
&css Additional stylesheet to load (defaults to none/false)
&accuracy accuracy of percentage rounding. this specifies the number of digits after the decimal point (defaults to 1)
&tplVoteOuter Outer container template for votes.
Default:

&tplVote Template for a single voting option
Default:

&tplResultOuter Outer container template for results
Default:

&tplResult Template for a single result
Default:

&tplError Template that is used to display a error message
Default:

&identifier the element identifier that is used for the js commands. change this to something unique every time
if you plan to use multiple polls on one page. Eg. easypoll1, easypoll2, etc. (defaults to "easypoll")
&nojs Boolean. Suppress inclusion of mootools. Use this if mootools is already included (defaults to false)
&customjs include a custom javascript code (eg. your custom callback function definiton). This can be a path to a JS File or a script wrapped in <script> tags. You can specify a chunk as well, use @CHUNK:<chunkname> for this purpose. (defaults to none)
&jscallback jscallback can be any javascript function name. It will be called first when the ajax loading starts and a second time when loading is complete.
You'll get 2 parameters for that function. The first one is the response. The response is FALSE when loading has just started and contains the loaded HTML if loading is done.
The second parameter is the id of the poll element. This is the same as specified in &identifier and will help you to route the responses to the correct poll if you're using multiple polls on one page. (defaults to "EasyPoll_DefaultCallback" which will be written into the HTML Code by the snippet)
&showexception If set to true, even "invisible" exceptions like the one occuring if no poll was found will be shown!
This is useful for testing, should not be used in production environment though. (defaults to false)
Template Placeholders Please note that the tplVoteOuter template is always wrapped in a div withi]<&identifier>[/i] and! Since the results are loaded via AJAX and injected into this element (unless you specify your own callback function), this element should only serve as a container and not used for general styling (because it won't persist if you call the snippet the "non-Ajax" way).
The tplVoteOuter will also be wrapped in a form element.
This is done to ensure functionality of the poll snippet (form and ajax).

tplVoteOuter [+question+] = the title/question of the poll
[+choices+] = the vote options/choices
[+submit+] = the submit button will be injected there. don't forget this or the user won't be able to vote
[+results+] = button to show results. not mandatory, since results will be shown upon voting

tplResultOuter [+question+] = the title/question of the poll
[+totalvotes+] = the total amount of votes that were cast for this poll
[+totaltext+] = the text.. eg. "Total votes" for english
[+choices+] = the choice results

tplVote [+select+] = the radio button. don't forget this or the user won't be able to vote at all
[+answer+] = the answer. don't forget this. please
tplResult [+answer+] = the answer
[+percent+] = the percent value of this result (without %, accuracy according to &accuracy param)
[+percent_int+] = integer value of the percentage. can be used for css styling. eg. width:[+percent_int+]%;
[+votes+] = the number of votes that went in for this question/option

tplError [+message+] = The error message

Usage examples This is how you should probably start. Specify a poll id (as seen in the EasyPoll Module) and set the showexception flag to 1. This allows you to test the poll output and see exceptions if they occur. Do not use this on a live environment.


This is a call, how it could be used on the MODx Demo Site. User may only vote once (we're using a cookie and log the ip to assure this). We disable the inclusion of mootools (since it is included by another script) and use our own stylesheet (we're using the simple stylesheet i provided with the snippet)


The following screenshots show a simple poll integrated into the MODx Demo Site: Voting:

Results:

So far so good.
Any input is highly appreciated! It would be awesome if i could find some testers on this board
Thanks for reading
-- banal

Edit (2008-02-05)
There is currently a Bug when using the "MODxGreen" theme in the manager. Some Buttons have a invisible label. Please use either MODx or MODxLight theme until this is fixed.

Edit (2008-02-05)
Fixed the above Bug. The Manager should now be usable with all 3 MODx Manager Themes. I have a small suggestions to the MODx developers here: would it be possible to have a "common" Icon set that is not bound to themes? It would be useful for Module developers so they don't have to ship their own icons and are not bound to a theme? Just a sidenote though, maybe somebody picks this up.

I changed some small things when it comes to chunk templates and styleshees. The way i built v. 0.1 wasn't very practical for styling when using multiple polls on the same page (although this might happen rarely). The poll.css file and the Templates reflect that change, thus we're at Version 0.1.1

Edit (2008-02-06)
Found a small Bug when it comes to sorting and deletion of Choices. Just a nuisance.. but will be fixed in the next release

Edit (2008-02-11)
Version 0.2 released!
This document has been updated to reflect the changes in Version 0.2
DB Structure wasn't changed, so if you're already running a older version, a simple File-replacement and update of the Module and the Snippet will do.

Edit (2008-02-15)
Version 0.2.1 released.
A dutch translation is now available, thanks to peterruiter.
Output of a poll archive is now implemented in the snippet code. Documentation currently only in the snippet, will soon post a updated documentation.

Looks superb - I will be testing this later today!

This looks fantastic! I'll be needing this when I make the move to PHP5.

Great job here, this looks great and super complete and lots of documentation. And having build in multi-language features is fantastic! I can't wait to test this as soon as I get a chance.

Really good job. Unfortunately I don't have any 'test'-installation for these kind of purposes.

Hello
Thanks for the positive feedback to all who replied!

I'm currently thinking about extending the snippet so that it can be used to generate a "archive" of past polls... now that i think about it, i see several problems with my current implementation of timed polls and addressing the polls in general.

The "prefered" way to do it was to specify the poll id as parameter for the snippet. Which is ok if you have just one poll, but becomes very unhandy if you automatically want to display the most recent poll in a container without constantly changing the snippet parameter.
You could of course call the snippet without the pollid parameter but then you'll have to make sure that only 1 poll is active at a time in the Manager.

Another issue: When does a poll without end-date time-out? Where to put this poll in the Archive (since this should be sorted chronologically).

I'm currently thinking about dumping the whole start- end-date stuff on a poll basis and create a new pane in the manager. Something like a "Release Manager" that will allow you to exactly time your polls. If there are multiple polls that could be possibly active, the topmost poll in the release manager will be shown (you can change that by sorting).
That way i'll have a nice history for the archive and i get rid of the pollid parameter!

Please tell me what you think about that approach.
Cheers -- banal

Edit As soon as i had the idea i canceled it again The "release manager" thing would not really work for people that want multiple polls on their website.
I'm going to leave it as it is, but only change the start-date to the current date by default (if not set explicitly). That way i'll have a sorting for the history and people can change the poll order by changing the start-date manually.
The end-date will only be effective if no new poll is ready (and thus, no poll will be displayed on the website).
This should do until somebody comes up with a brilliant solution as of how to organize polls

Small Update 2008-02-08
The Snippet is coming along nicely. It'll hit productive state pretty soon.
Currently i'm running Tests with multiple Polls on one Page and ironing out Bugs.
I simplified the process of adding a own JavaScript Callback too. Documentation soon to be updated.

My plan is to integrate the Poll Module in a live Site on monday.

Version 0.2 is out. I wasn't able to put a version online today, because i need some translations to be done first. I'll provide a french and italian Translation for the Snippet (since i need these), but for the Manager Part i'll need some help.
Will soon post this under the MODx Resources, since it's pretty much stable and complete. Will provide some examples as well (especially for the JavaScript Callback part, which is probably not that easy to grasp).

I'll help you out with the dutch translation.

Quote from: peterruiter at Feb 15, 2008, 03:41 AM

I'll help you out with the dutch translation.

Cool, thank you so much.
You'll have to translate 2 files (one is rather extensive, the other one should be a peace of cake). The lang file for the Module can be found in modules/EasyPoll/lang. You can have a look at the german.inc.php or english.inc.php. For your translation you'll have to stick with the naming convention of MODx. For dutch this would be "nederlands" -> nederlands.inc.php

The Language file for the Snippet is located in snippets/EasyPoll/lang and is should currently be named like this:
lang.<ISO 639-1 Code>.php
Which would result in lang.nl.php for a dutch translation.

Feel free to PM me if you got a translation done, i'll happily integrate it into the next release.

Edit: If you don't feel like translating the Module part, the Snippet part would be nice to have, even without the module translation!