Clone this wiki locally
Chapter 4: polls definition
As explained in chapter 2, a poll is a set of files. In particular, a poll is composed by a form class and some templates and actions.
apostrophePollPlugin provides default templates and actions for rendering the form and to confirm a successful submission. Thanks to the symfony architecture, these files can be customized via configuration parameters, to fit the specific requirement of each poll.
The poll configuration parameters are based on a cascade architecture. When looking for a parameter, the plugin will look at:
- Poll's parameters
- Global parameters
- Plugin default parameters
So, one can define global parameters, valid for all polls published on the website and then override them with specific values for each poll. If nothing is defined for a given parameter, apostrophePollPlugin will provide a default value.
Global and poll-specific parameters are defined in
The plugin already provides an
aPoll.yml file in
plugins/apostrophePollPlugin/config. You can add additional parameters or override some of the existing ones by creating a new
Notice that the file is loaded with a cascading strategy and is environment-aware, as explained in the symfony reference book.
This section presents the global parameters. Values displayed in the example code are the default values provided by the plugin.
view field defines parameters related to the form display and submission.
# apps/frontend/config/aPoll.yml all: settings: view: default_template: aPollSlot/default_form_view default_submit_action: '@a_poll_slot_submit_form' default_submit_success_template: aPollSlot/default_submit_success default_heading_tag: h3
default_template: defines the partial template that renders the form.
default_submit_action: defines the action that handles the form submission. Can be defined as module/action or as a route name.
default_submit_success_template: defines the default template rendered when the poll submission is successful. This template is only called by the default submit action. If a custom action is defined, the user must create a new template.
default_heading_tag: defined the tag that renders the form heading.
This section defines if a poll may be submitted several consecutive times by the same user.
# apps/frontend/config/aPoll.yml all: settings: submissions: allow_multiple: false cookie_name: aPoll_submissions cookie_lifetime: 86400
allow_multiple: if set to
true, the poll is displayed every time the user reloads the page. If set to
false, the poll is not displayed for a given time delay (see next parameters).
cookie_name: a cookie is created in order to register user submissions. This parameter defines the name of the cookie.
cookie_lifetime: defines the time delay between two consecutive poll submissions, when
allow_multipleis set to false. This parameter is defined in seconds.
To avoid spamming and unwanted submissions, it is often useful to display a security mechanism. Captchas are a common solution. apostrophePollPlugin provides support for displaying reCaptcha. A strategy to replace reCaptcha with another widget is explained below.
# apps/frontend/config/aPoll.yml all: settings: captcha: do_display: true
do_display: defines if a captcha shall be displayed with the form.
To display reCaptcha, the plugin requires the installation of sfFormExtraPlugin. apostrophePollPlugin extends the widget provided by sfFormExtraPlugin in order to enable reCaptcha display in Ajax-driven partials, which is the case for the aPollSlot.
To use another captcha or any other security technique, it is possible to override the
getCaptchaValidator() functions provided by
PluginaPollBaseForm. This can be done by customizing
aPollBaseForm, if you want to replace reCaptcha in all polls, or directly in the poll's form class, to use a specific captcha for that particular case.
After a poll has been successfully submitted, it is possible to send an email notification to a give address, in order for the site administrator (or someone else) to know that something happens on the website.
# apps/frontend/config/aPoll.yml all: settings: notifications: do_send: true to: admin from: admin title_partial: aPollSlot/email_title body_partial: aPollSlot/email_body stylesheets: apostrophePollPlugin/css/aPoll_email.css
do_send: defines if a notification shall be sent after a successful poll submission.
to: defines the email address or the username of the person who shall receive the notification.
from: defines the email address or the username of the person actually sending the notification.
title_partial: defines the partial rendering the email title.
body_partial: defines the partial rendering the email body.
stylesheets: string or array defining which stylesheets are used to decorate the emails. The path to provide is relative to
Listing available polls
In order to let apostrophePollPlugin know that a poll is available, the user has to declare it in the
This declaration represents a poll template, that might be used several times in the website. Read more about poll publishing in chapter 5.
The following code must be used to declare the poll:
# apps/frontend/config/aPoll.yml all: settings: available_polls: ... contact: name: Contact form form: aPollContactForm ...
available_pollsis the placeholder for listing all available polls.
contactis the identifier of a poll. It must be unique.
nameis the name of a poll, which will be shown in a dropdown menu in the polls administration module.
formis the form class associated to the poll.
form are required to define a poll. Other parameters allowing one to customize the form submissions and rendering, are described in the next section.
Poll customization parameters
The following code shows the complete set of parameters defining the poll rendering and the form handling. The values displayed are the default values set by apostrophePollPlugin.
# apps/frontend/config/aPoll.yml all: settings: available_polls: contact: name: (required, no default value) form: (required, no default value) view_template: aPollSlot/default_form_view submit_action: '@a_poll_slot_submit_form' submit_success_template: aPollSlot/default_submit_success heading_tag: h3 send_notification: true send_to: admin send_from: admin email_title_partial: aPollSlot/email_title email_body_partial: aPollSlot/email_body email_stylesheets: apostrophePollPlugin/css/aPoll_email.css captcha_do_display: true reports: ~
name: Name of the poll
form: name of the form to display. The form must extend aPollBaseForm (see chap. 4) and must be placed in a lib directory in order to be found by symfony
view_template: defines the partial used to render the form.
submit_action: defines the action that handles the form submission.
submit_success_template: partial rendering the poll submission success message.
heading_tag: tag rendering the form heading
send_notification: defines if a notification must be sent to an email address when someone submits an answer.
send_to: email address or registered user (username) who will receive the email notification.
send_from: defines the sender (email or user) of the notification.
email_title_partial: name of the partial rendering the title of the email.
email_body_partial: name of the partial rendering the body of the email.
email_stylesheets: array defining the stylesheets decoratint the notification email.
captcha_do_display: shall a captcha be displayed in order to protect form submissions from spam?
reports: list of available reports for this poll (see chapter 6). To define them, use the keywords defined in
app_aPoll_reports. To enable all generic reports, use "
~". You can also add poll-specific reports. Ex.:
[~, myReport, anotherReport].
Adding polls from other plugins
Thanks to the cascading configuration technique, it is possible to build the configuration of apostrophePollPlugin from multiple sources. This is particularly interesting for the definition of available polls. Indeed, this list may be built from multiple plugins and from the local project.
Addind new poll templates is as simple as defining the required form class and templates and by creating a
aPoll.yml configuration file in the plugin or in the app config folder.
A major advantage of the use of the
aPoll.yml configuration file is that this allows to increase the number of poll templates shared with the community without needing to update the plugin content. This will speed up the release cycle of new polls and reduce the plugin's maintenance.