collective.polls 2.0b1
A content type, workflow, and portlet for conducting online polls, for anonymous and logged-in users.
Keywords: plone dexterity polls

****************
collective.polls
****************

.. contents:: Table of Contents

Life, the Universe, and Everything
----------------------------------

A content type, workflow and portlet for conducting online polls, for
anonymous and logged-in users.

Mostly Harmless
---------------

.. image:: http://img.shields.io/pypi/v/collective.polls.svg
   :target: https://pypi.python.org/pypi/collective.polls

.. image:: https://img.shields.io/travis/collective/collective.polls/master.svg
    :target: http://travis-ci.org/collective/collective.polls

.. image:: https://img.shields.io/coveralls/collective/collective.polls/master.svg
    :target: https://coveralls.io/r/collective/collective.polls

Got an idea? Found a bug? Let us know by `opening a support ticket <https://github.com/collective/collective.polls/issues>`_.

Known issues
^^^^^^^^^^^^

* `Can't add a portlet under Plone 5 <https://github.com/collective/collective.polls/issues/106>`_.

See the `complete list of bugs on GitHub <https://github.com/collective/collective.polls/labels/bug>`_.

Don't Panic
-----------

Installation
^^^^^^^^^^^^

To enable this product in a buildout-based installation:

#. Edit your buildout.cfg and add ``collective.polls`` to the list of eggs to
   install::

    [buildout]
    ...
    eggs =
        collective.polls

#. If you are using Plone 4.2 you need to add the following also::

    [versions]
    ...
    collective.js.jqueryui = 1.8.16.9

After updating the configuration you need to run ''bin/buildout'', which will
take care of updating your system.

Go to the 'Site Setup' page in a Plone site and click on the 'Add-ons' link.

Check the box next to ''collective.polls'' and click the 'Activate' button.

.. Note::
    You may have to empty your browser cache and save your resource registries
    in order to see the effects of the product installation.

Features
^^^^^^^^

- Polls can be opened for anonymous users to vote
- If an open poll is allowed for anonymous but is inside a private folder,
  nobody can vote. Therefore the poll's parent folder needs to be published
  before opening the poll in order for this field to take effect
- Voting can take place either in the object or in a voting portlet;
- The voting portlet can show the latest open poll or ab specific open poll
  and closed polls
- Users can see partial results of the poll
- Results can be shown using a bar chart, a pie chart, or just by number of
  votes
- Polls can have relations with other content in the site

Workflow description
^^^^^^^^^^^^^^^^^^^^

The workflow associated with polls has the following states: 'Private',
'Pending review', 'Open' and 'Closed'.

- Polls are created in 'Private' state; only Owner, Manager, Editor or Site
  Administrator roles can modify them.

- When a poll is in 'Private' state it can be sent to 'Pending review' or
  directly to 'Open' state, if the user has the proper role (Reviewer, Manager
  or Site Administrator).

- When a poll is in 'Pending review' state it can be edited by Manager,
  Editor, Reviewer or Site Administrator roles.

- A poll in 'Pending review' state can be sent to 'Open' state, with "Review
  portal content" permission, or to Private, with "Request review" permission.

- When the poll is 'Open' users can only vote; nobody can modify the poll in
  any way.

- An 'Open' poll can be sent to 'Private' or 'Closed' state by Reviewer,
  Manager or Site Administrator roles.

- When an 'Open' poll is sent to 'Private', all votes are removed to avoid
  data manipulation.

- When a poll is in 'Closed' state nobody can modify it, nor can anyone vote
  on it; a closed poll can always be reopened by usera with proper
  permissions.

Not entirely unlike
-------------------

`Plone PoPoll`_
    A very old an unmaintained product, PoPoll includes a poll tool that
    allows member or anonymous to vote for one or more answers. A portlet is
    provided. It can be configured to display the last poll, or the first poll
    of a folder. After the vote statistics screens are shown.

.. _`Plone PoPoll`: http://plone.org/products/plonepopoll

Share and Enjoy
---------------

``collective.polls`` would not have been possible without the contribution of
the following people:

- Franco Pellegrini
- Héctor Velarde
- Érico Andrei
- Rafahela Bazzanella
- Silvestre Huens
- Elio Schmutz
- Timon Tschanz
- Maurits van Rees
- Jean-Michel FRANCOIS
- Rodrigo Ferreira de Souza
- Víctor Fernández de Alba
- `WebDesignerDepot`_ (icon)

You can find an updated list of package contributors on `GitHub`_.

Development sponsored by Open Multimedia and `Simples Consultoria`_.

.. _`WebDesignerDepot`: http://www.webdesignerdepot.com/
.. _`GitHub`: https://github.com/collective/collective.polls/contributors
.. _`Simples Consultoria`: http://www.simplesconsultoria.com.br/

Changelog
---------

There's a frood who really knows where his towel is.

2.0b1 (2018-07-23)
^^^^^^^^^^^^^^^^^^^

.. Warning::
    This release removes code for old upgrade steps;
    upgrading from a version below 1.8 is no longer supported.
    This version removes tile registration/removal;
    you must depend on plone.app.tiles >= 3.0.0 to avoid issues with ``collective.polls`` tile.

- Add dependency on z3c.caching to implement automatic purging on poll modified, moved, renamed or removed.
  [hvelarde]

- Update i18n, Brazilian Portuguese and Spanish translations.
  [hvelarde]

- Fix HTTP caching headers on ``update-poll`` browser view (fixes `#117 <https://github.com/collective/collective.polls/issues/117>`_);
  a poll now updates its modification date on every vote.
  [hvelarde]

- Upgrade steps 2, 3 and 4 were removed.
  [hvelarde]

- Remove needless tile registration/removal when using plone.app.tiles >= 3.0.0.
  [hvelarde]

- Fix removal of portlet definition.
  [hvelarde]

- Manage deprecation of CMFQuickInstallerTool on Plone >= 5.1;
  [hvelarde]

- Fix dependencies inclussion.
  [hvelarde]

- Move ``IPolls`` utility to the ``utility`` module.
  [hvelarde]

- Move ``View`` class to the ``browser`` module.
  [hvelarde]

- Remove unused ``poll_portlet_render`` view and empty ``poll.xml`` model.
  [hvelarde]

- Translation support with LinguaPlone for poll fixed.
  [SyZn]

- Drop support for Plone 4.2 and Plone 5.0.
  [hvelarde]


1.10b1 (2017-06-16)
^^^^^^^^^^^^^^^^^^^

.. Warning::
    This release removes collective.z3cform.widgets from the list of dependencies;
    so, it would be a good idea to add this package on the `eggs` part of your buildout configuration before upgrading to avoid ending with a broken dependency.
    After running the upgrade step you can safely uninstall collective.z3cform.widgets and remove it from your buildout configuration if you don't have any other add-on depending on it.

- Remove ExplorerCanvas script;
  this will break compatibility with IE8 and below but... who cares?
  [hvelarde]

- Remove dependency on collective.z3cform.widgets.
  [sneridagh, hvelarde]

- Add Catalan translation.
  [sneridagh]

- Remove hard dependency on five.grok.
  [rodfersou, puittenbroek, hvelarde]

- Remove soft dependency on zope.formlib under Plone 5 (HT @ale-rt).
  [hvelarde]

- Do not fail while adding a portlet under Plone 5 (closes `#106`_).
  [hvelarde]


1.9b1 (2016-09-29)
^^^^^^^^^^^^^^^^^^

.. Warning::
    This release removes some packages from the list of dependencies.
    Be sure to read the whole changelog and apply the related changes to your buildout configuration while upgrading.
    Also, note that this is the first release marked as compatible with Plone 5;
    it still has some issues and must not be used in production with that version.

- Package is now compatible with Plone 5.0 and Plone 5.1.
  [hvelarde]

- Remove hard dependency on plone.app.referenceablebehavior as Archetypes is no longer the default framework in Plone 5.
  Under Plone < 5.0 you should now explicitly add it to the `eggs` part of your buildout configuration to avoid issues while upgrading.
  [hvelarde]

- Get rid of the ``uid_for_poll`` function.
  [hvelarde]

- Wrap poll choices with label-tag for easier option selection.
  [datakurre]

- Add Finnish translation.
  [datakurre]

- Add Traditional Chinese translation.
  [l34marr]


1.8.1 (2015-12-11)
^^^^^^^^^^^^^^^^^^

- The display of poll results was refactored to avoid issues with reverse proxies like Varnish;
  updates are now handled client-side using AJAX calls (closes `#96`_).
  [rodfersou]


1.8 (2015-11-24)
^^^^^^^^^^^^^^^^

- Add link to show partial results of an open poll (closes `#93`_).
  [rodfersou]

- Poll tile now displays the results of the poll after a vote has been cast (closes `#90`_).
  [rodfersou]


1.7 (2015-08-25)
^^^^^^^^^^^^^^^^^^

- Add Poll tile for collective.cover.
  [hvelarde]


1.6.2 (2015-03-11)
^^^^^^^^^^^^^^^^^^

- Add upgrade step to remove missing resource from JS registry (fixes `#83`_).
  [hvelarde]

- Update German translation.
  [mbaechtold]

- Added Czech translation
  [naro]


1.6.1 (2014-08-19)
^^^^^^^^^^^^^^^^^^

- Remove ``@@legendothers_translation.js`` because it is not used anywhere.
  [rafaelbco]


1.6 (2014-05-01)
^^^^^^^^^^^^^^^^

- Add a default value to the voting portlet ``poll`` parameter. This fixes an
  issue happening when importing ``portlets.xml`` assignments.
  [ericof]

- Remove unnecesary code in portlet (closes `#73`_).
  [nueces]

- In portlet link back to poll page (closes `#47`_).
  [marcosfromero]


1.5 (2013-12-17)
^^^^^^^^^^^^^^^^

- Make the add-on aware of subsites (INavigationRoot) [rafaelbco]

- Implement show_total for the portlet (closes `#64`_). [marcosfromero]

- Depend on plone.api.
  [hvelarde]

- Remove dependency on unittest2; package is not going to be tested under
  Python 2.6 anymore.
  [hvelarde]

- Drop support for Plone 4.1. [hvelarde]

- Add French translation. [toutpt]


1.4 (2013-04-10)
^^^^^^^^^^^^^^^^^^

- Tested for Plone 4.3 compatibility. [ericof, hvelarde]

- Anonymous voters can now vote again on a reopened poll (fixes `#35`_).
  [ericof]

- Remove cmf.ManagePortal permission when editing the portlets. [flecox]


1.3.1 (2013-03-27)
^^^^^^^^^^^^^^^^^^

- Fix refreshing the portlet.  Previously no html would be returned
  when the portlet was defined on a default page.  The refresh would
  fail with a ComponentLookupError when used inside a panel of
  collective.panels.
  [maurits]

- Fixing jQuery bug when doing AJAX call in portlet. [flecox]


1.3 (2013-01-14)
^^^^^^^^^^^^^^^^

- Test compatibility with Plone 4.3. [hvelarde]

- Bump up version of collective.z3cform.widgets dependency to 1.0b3.
  [hvelarde]

- Declare Pillow as a package dependency. [hvelarde]

- Add Dutch translation. [fredvd]

- Fixed permissions checks for anonymous users when a poll is at the
  root level of the site (fixes `#61`_). [vincentpsarga]


1.2 (2012-09-16)
^^^^^^^^^^^^^^^^

- EnhancedTextLinesFieldWidget widget was updated; new features (like inline
  editing and reordering) are now available. [hvelarde]

- Added the 'open' transition to the 'closed' state, that way, polls can be
  re-opened after they were closed (closes `#53`_). [frapell]


1.1 (2012-08-14)
^^^^^^^^^^^^^^^^^^

- Multiple poll charts can be rendered in one page. [Quimera]

- Multiple poll portlets can be rendered in one page. [Quimera]

- Updated Brazilian Portuguese translation. [rafahela]

- Add translation functionality for the 'Others' string and translate it to
  German. [eschmutz]

- Fixed translation strings for actions on poll workflow; updated Spanish and
  Brazilian Portuguese translations. [hvelarde]

- Update German translations. [tschanzt]

- allow_anonymous field is always shown (fixes `#51`_). [hvelarde]

- Some refactoring on tests was done; we now test for CSS installation and
  removal. [hvelarde]

- DataGridField widget was replaced with EnhancedTextLinesFieldWidget.
  [flecox, hvelarde]


1.0.1 (2012-05-08)
^^^^^^^^^^^^^^^^^^

- Fix UnicodeDecodeError in PossiblePolls vocabulary when we have a
  poll with umlauts in the title. [elioschmutz]

- Add German translation. [elioschmutz]


1.0 (2012-05-02)
^^^^^^^^^^^^^^^^

- Tested for Plone 4.2 compatibility. [hvelarde]

- Updated Dexterity version requirement (we want to use latest version to
  avoid any issues). [hvelarde]

- Added a nice hack to include both README.txt and README.rst in the package
  declaration. [hvelarde]

- Pie chart is now shown when all votes go to one option (issue #27). [flecox]


1.0rc2 (2012-02-20)
^^^^^^^^^^^^^^^^^^^

- Ajax load of partial results on portlet (issue #37). [Quimera]

- Updated Brazilian Portuguese translation. [ericof]

- Added option to control if portlet shows closed polls when no open ones are
  available (issue #32). [ericof]

- Added validation for Poll options (issue #31). [ericof]

- Add a subscriber to erase votes when poll is sent back to revision (issue
  #33). [ericof]

- Fix Anonymous permissions to View and Vote on polls. [ericof]

- Modify workflows and permissions to be consistent with the ones used in
  Plone. [ericof]

- Fixed MANIFEST.in file. [nueces]

- Renamed the workflow state to 'Opened' instead of 'Published' (issue #26).
  [frapell]

- Updated tests and translations. [frapell]

- Added the pieChart to the portlet (issue #23). [frapell]

- Made the poll redirect to the place where the vote was casted (issue #22).
  [frapell]

- Updated Spanish translation. [hvelarde]

- Fixed permissions on private and pending states (issue #20). [hvelarde]

- Fixed javascript registry uninstall and tests. [hvelarde]


1.0rc1 (2012-01-10)
^^^^^^^^^^^^^^^^^^^

- Initial release.

.. _`#35`: https://github.com/collective/collective.polls/issues/35
.. _`#47`: https://github.com/collective/collective.polls/issues/47
.. _`#51`: https://github.com/collective/collective.polls/issues/51
.. _`#53`: https://github.com/collective/collective.polls/issues/53
.. _`#61`: https://github.com/collective/collective.polls/issues/61
.. _`#64`: https://github.com/collective/collective.polls/issues/64
.. _`#73`: https://github.com/collective/collective.polls/issues/73
.. _`#83`: https://github.com/collective/collective.polls/issues/83
.. _`#90`: https://github.com/collective/collective.polls/issues/90
.. _`#93`: https://github.com/collective/collective.polls/issues/93
.. _`#96`: https://github.com/collective/collective.polls/issues/96
.. _`#106`: https://github.com/collective/collective.polls/issues/106