Demo

You will find a demonstration of the extension on https://t3oodle.com

Features

• Create and edit polls (and its options) in frontend

  • Two types are available: simple options and schedule (with date picker)

  • Each poll has various settings, like

    • Third option state (yes/no/maybe)
    • Expire date
    • Secret votings and/or participants or
    • Limit amount of votes per option
• Vote on existing polls
• The suggestion mode let your participants provide options, before voting

• Accessible for logged in frontend users and guests (configurable)

  • guests get a "userIdentifier" stored as cookie, when they create a poll or vote for it!
• Poll author can finish voting and select a final option
• Highly configurable (via TypoScript)
• Easy to extend, thanks to helpful signals and well structured templates

• Provided JavaScript functionality

  • is written in pure (vanilla) JS
  • ships and uses the date picker "flatpickr" (as only dependency)
  • runs in parallel with other JS frameworks, like Vue.js
• TYPO3 9 LTS and 10 LTS compatibility
• Complete documentation

With Composer

Just perform the following command on CLI:

$ composer req fgtclb/t3oodle

When composer is done, you need to enable the extension in the extension manager.

Without Composer

You can also fetch t3oodle from TER and install it the old-fashioned way.

Extension settings

t3oodle does not provide any extensions settings. Configuration is made in TypoScript setup.

TypoScript settings

Make sure to include the TypoScript t3oodle Main (required) to your template.

In Configuration chapter, you see all TypoScript settings and its defaults.

Because t3oodle is based on Bootstrap CSS framework v4, there is an optional TypoScript for this: t3oodle Custom Bootstrap Styles (optional)

General

Here you can define general information about the poll. A title, a description and a "more info" link.

In show action of a single poll, it looks like this:

The visibility controls if the poll is shown in list action or not. The author of the poll, still can see his/her own poll.

Also, when visibility is set to "Hide in lists", the slug generated for this poll, is not based on the entered title anymore.

Author

Here, every visitor of your website can enter his/her name and mail address. Both are mandatory fields.

The cookie is only used, to identify an author of a poll and participants, which voted for a poll.

Alternatively, you can disable creation of new polls and voting for polls, using TypoScript. Then, only logged in frontend users (fe_users) can interact with t3oodle. Guests (non-logged in visitors) can still see the polls.

Once the user has entered name and mail address, it get stored in local storage.

Options

Here you can define the options for your poll.

Simple poll	Scheduled poll
alt Add new options to a simple poll width 99%	alt Add new options to a scheduled poll width 99%

The date picker for scheduled polls only appear in new action. The text format which is being saved is:

2020-12-24 - 16:00-18:00

When you keep this syntax, t3oodle is able to treat the text content as DateTime, which is very useful for further features like ICS export (for e.g. Outlook support).

The time is optional. You can also use any text here.

Suggestion mode

Since t3oodle 0.8 you can enable the suggestion mode, which allows your participants to submit own options, before voting.

When it's enabled, and the poll author did not finish the suggestion mode yet, the poll looks like this:

The poll author can finish the suggestion mode in the administration box:

After the suggestion mode is finished, the voting begins.

Settings

Every poll have various settings, the poll author can change:

Publish

By default a poll is directly published. You can uncheck this box, then the poll is created but not publicly available. You can make changes, before publishing the poll.

Accept terms

By default this option is disabled. You can enable it in TypoScript and define a page, external URL or file to display when clicking the link.

When this option is enabled, the author of a new poll needs to accept the linked terms, before the poll is created.

With enabled suggestion mode

When the suggestion mode has been enabled and is not finished yet, you can finish the suggest mode:

Editing published polls

When you've already published a poll and edit its options or change an option related setting (like Yes, No, Maybe), all existing votes get removed!

The affected settings and the options section got a "Caution!" label set.

Finish voting

The poll author can finish a poll anytime he/she want, after the poll has been published, unless an expiration date has been set, in settings of the poll. Then, the finish action can only get triggered, when the expiration date is reached.

When finishing the poll, you need to select a final option.

Once a poll has been finished, the show action displays the final option, selected by poll author.

Draft

Finished

Opened for suggestions

Opened

Closed

1. Poll author creates poll

The first step in lifecycle of a poll is the form which allows frontend users to create new polls. Here the user can decide to publish the poll directly or keep it as draft.

When the user does not publish the poll, s/he (as poll author) and administrators only see the poll in list action:

2. Publishing the poll

Once the poll author is satisfied with his inputs, s/he can publish the poll. Then it becomes public and participants can vote for it.

If a poll appears in list view is also depending on the visibility setting, each poll has.

When visibility set to hide in list the poll will not get displayed in list action, even when published. Same as for draft polls, only the poll author and administrators can see the poll in list.

The publish date is recorded in poll record.

3a. Open for suggestions

During this phase, the participants can submit own option suggestions.

When the poll author finished the suggestion mode or the mode has not been enabled, the voting begins.

3b. Voting for the poll

Once a poll is published, participants can see poll details and vote for it.

During the poll (status) is opened or closed, participants can edit or delete their own vote.

Also, the poll author is able to reset all votes from poll. And votes get deleted, when the poll author makes changes to options or option related settings.

4. Editing the poll

Poll authors and administrators can edit their poll all the time, until the poll is finished.

When editing the poll after it has been published, you should know two things about:

1. When you update options or option related settings, all existing votes for this poll are getting removed! In edit form you get reminders for that.
2. When you change the visibility setting of the poll or its title, the slug gets updated! Then, you need to send the updated link to your participants manually.

5. Finishing the poll

The poll author can finish the poll at any time, unless the poll's expiration date is set. S/he have to select a final option for that.

When a poll is finished:

• Poll becomes sticky (not editable nor deletable (even without existing votes))
• No new votings possible
• Existing votes are sticky

The finish date and final option is recorded in poll record.

General

View related settings

Supported routes

The following routes are defined by t3oodle, you can define your own, if you want to:

https://domain.com/path/to/page

• List Action: / or /123 (when paginated)
• New Action: /create or /create-schedule or /erstellen or /erstellen-terminfindung
• Show Action: /{poll-slug}
• Edit Action: /{poll-slug}/edit or /{poll-slug}/bearbeiten
• Delete Action: /{poll-slug}/delete or /{poll-slug}/loeschen
• Reset Action: /{poll-slug}/reset or /{poll-slug}/zuruecksetzen
• Finish Action: /{poll-slug}/finish or /{poll-slug}/fertigstellen
• Finish Suggestion Mode Action: /{poll-slug}/finish-suggestion-mode or /{poll-slug}/vorschlagen-modus-beenden
• Add Suggestion Action: /{poll-slug}/add-suggestion or /{poll-slug}/vorschlag-erstellen

All static parts of routes are implemented by LocaleModifier aspect, to provide translations.

Existing signals

The following signals exist:

\FGTCLB\T3oodle\Controller\PollController

• list
• show
• vote
• deleteOwnVote
• resetVotes
• showFinish
• finish
• new
• createBefore
• createAfter
• publish
• edit
• updateBefore
• updateAfter
• delete
• finishSuggestionMode
• newSuggestion
• createSuggestionBefore
• createSuggestionAfter
• editSuggestion
• updateSuggestionBefore
• updateSuggestionAfter
• deleteSuggestion

\FGTCLB\T3oodle\Domain\Permission\PollPermission

• Also all permissions defined in PollPermission dispatch an own signal

\FGTCLB\T3oodle\Domain\Repository\PollRepository

• findPolls Allows you to modify query constraints

Register a slot

To register a slot, you just need to add the following PHP code in ext_localconf.php of a TYPO3 extension:

/** @var \TYPO3\CMS\Extbase\SignalSlot\Dispatcher $signalSlotDispatcher */
$signalSlotDispatcher = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Extbase\SignalSlot\Dispatcher::class);
$signalSlotDispatcher->connect(
    \FGTCLB\T3oodle\Controller\PollController::class,
    'vote',
    \Vendor\MyExt\Slots\MyCustomSlots::class,
    'vote'
);

Writing the slot

The method you define as slot requires all arguments, passed by dispatcher. To identify the correct arguments, search in t3oodle code for ->dispatch(__CLASS__.

For example the arguments passed to vote action slot are:

[
    'vote' => $vote,
    'isNew' => !$vote->getUid(),
    'settings' => $this->settings,
    'continue' => true,
    'caller' => $this
]

So, this is how the slot method signature must look like:

use FGTCLB\T3oodle\Domain\Model\Vote;

final class MyCustomSlots
{
    public function vote(\FGTCLB\T3oodle\Domain\Model\Vote $vote, bool $isNew, array $settings, bool $continue, PollPermission $caller): array
    {
        // TODO: implement me
        return [
            'vote' => $vote,
            'isNew' => $isNew,
            'settings' => $settings,
            'continue' => $continue,
            'caller' => $caller,
        ];
    }
}

Also, the slot needs to return the arguments in same order, with keys prefixed!

Permission ViewHelper

<f:if condition="{t3oodle:permission(action:'newSimplePoll')}">
    // show new button
</f:if>

The action is passed without trailing is and Allowed.

When a permission requires poll or vote argument, you can call it like this:

<f:if condition="{poll -> t3oodle:permission(action:'delete')}">
    // show delete button, for this poll
</f:if>

Modifying permissions

Every permission can get changed programmatically, by using Signal/Slots.

First register your slot in ext_localconf.php:

/** @var \TYPO3\CMS\Extbase\SignalSlot\Dispatcher $signalSlotDispatcher */
$signalSlotDispatcher = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Extbase\SignalSlot\Dispatcher::class);
$signalSlotDispatcher->connect(
    \FGTCLB\T3oodle\Domain\Permission\PollPermission::class,
    'isNewSimplePollAllowed',
    \Vendor\MyExt\Slots\PollPermissionSlots::class,
    'isNewSimplePollAllowed'
);

The PollPermissionSlots class looks like this:

final class PollPermissionSlots
{
    public function isNewSimplePollAllowed(bool $currentStatus, array $arguments, PollPermission $caller): array
    {
        $newStatus = false; // TODO: implement me
        return [
            'currentStatus' => $newStatus,
            'arguments' => $arguments,
            'caller' => $caller,
        ];
    }
}

Good to know

• When listing setting of poll gets updated during edit, also the slug gets updated.
• t3oodle uses a slot for this, registered with createAfter and updateBefore signal of PollController. See Signal/Slots for further info.
• When a slug wouldn't be unique, the poll uid is appended.

Templates

• List Displays a list of polls.
• Show Displays details of a single poll. Here, participants can vote.
• New Form to create a new poll.
• Edit Form to update an existing poll.
• Finish Displays form to select final option, to finish poll.
• NewSuggestion Displays form to submit new suggestion.
• EditSuggestion Displays form to edit suggestion.

All other actions (create, update, delete) redirect to list or show action, by default.

Partials

• FormFieldErrors.html Inline validation/error messages for form inputs.

• Poll/

  • New/, Edit/ and Finish/ Each action has dedicated partials.

    • Header.html
    • Form.html

  • Show/

    • Header.html
    • Info.html
    • NoticeExpireDate.html
    • NoticeSecretVoting.html

    • Administration.html Box with poll actions. Just visible for the poll author and administrators.

      • Buttons.html
      • LabelPublishStatus.html
      • NoticeVotingDisabled.html
      • WhoYouAre.html
  • AuthorInfo.html Username/Mail of poll author.
  • FormFields.html All form fields a poll has.

  • FormFields/ All form fields a poll has.

    • General.html
    • Author.html
    • Settings.html

    • Options/

      • Header.html Used in both types.

      • Type/

        • Simple.html Options section for simple poll.
        • Schedule.html Options section (with date picker) for scheduled poll.

  • SuggestionMode/

    • Overview.html Displayed in show action of poll, when suggest mode is active.

    • Form/

      • Creator.html
      • Suggestion.html The actual suggestion (supporting date picker for scheduled polls)

  • List/

    • Header.html
    • Totals.html

    • Table.html

      • Row.html
    • NewButton.html
  • Voting.html Voting entrance point. Contains poll notes, the vote form and table.

  • Voting/

    • Box.html A single checkbox in voting row.
    • ParticipantInfo.html Username/Mail of participant.
    • Row.html A single row in voting table.

    • Summary.html Shows submit button for voting or displays final option, when poll is finished.

      • PollFinished.html
      • PollNotFinished.html

    • Table.html

      • Head.html
      • YourVote.html

Stylesheets

All custom styles are located in Resources/Public/Stylesheets/t3oodle.css. This file get included in TypoScript setup of t3oodle.

Also you can include an optional TypoScript template, which includes a custom build of Bootstrap itself. You don't need to include this optional styles, when you already use Bootstrap in your frontend.

JavaScripts

All JavaScript provided by t3oodle are based on vanilla JS. The used date picker is flatpickr, which is also written in vanilla JS. No frameworks are required.

If frameworks are in use, they do not affect t3oodle's functionality.

Migrate old "One option only" setting

In t3oodle 0.6 the poll setting "oneOptionOnly" has been changed to "maxVotesPerParticipant". This update wizard checks "tx_t3oodle_domain_model_poll" table for old setting set and migrates it to new option.

Migrate old poll types

Since t3oodle 0.9 the poll types are using Single Table Inheritance. In order to make this pattern to work in Extbase, the type field must contain the FQCN of the entity model to be used. This migration, converts "simple" and "schedule" to corresponding class names.

How to provide new poll type?

1. Create a new Extbase model extending from \FGTCLB\T3oodle\Domain\Model\BasePoll
2. Overwrite the property protected $typeName = 'Whatever'; with an UpperCamelCase identifier (used in templates and localization identifiers)

3. Create new TCA override (EXT:your_ext/Configuration/TCA/Overrides/tx_t3oodle_domain_model_poll.php);

   $GLOBALS['TCA']['tx_t3oodle_domain_model_poll']['types'][\Vendor\YourExt\Domain\Model\WhateverPoll::class] = [
       'showitem' => $GLOBALS['TCA']['tx_t3oodle_domain_model_poll']['types'][\FGTCLB\T3oodle\Domain\Model\SimplePoll::class]['showitem']
   ];
   
   $GLOBALS['TCA']['tx_t3oodle_domain_model_poll']['columns']['type']['config']['items'][] = [
       'Whatever Poll',
       \Vendor\YourExt\Domain\Model\WhateverPoll::class
   ];

   Copied!

4. Extend Extbase mapping:

   config.tx_extbase {
       persistence {
           classes {
               FGTCLB\T3oodle\Domain\Model\BasePoll {
                   subclasses {
                       \Vendor\YourExt\Domain\Model\WhateverPoll = Vendor\YourExt\Domain\Model\WhateverPoll
                   }
               }
               Vendor\YourExt\Domain\Model\WhateverPoll {
                   mapping {
                       tableName = tx_t3oodle_domain_model_poll
                       recordType = Vendor\YourExt\Domain\Model\WhateverPoll
                   }
               }
           }
       }
   }
   
   

   Copied!

   Note

   This example is for TYPO3 v9, written in TypoScript. In v10 you should use PHP syntax instead.

5. When you use Routing Enhancer, you need to add the new poll type, to routing aspect poll-type map and localeMap
6. Add a partial for the new typeName e.g. EXT:your_ext/Resources/Private/Partials/Poll/FormFields/Options/Type/Whatever.html, keep in mind that you also need to register the partial path in t3oodle's TypoScript

7. There are also several translation keys (in locallang.xlf), which have the typeName appended:

   • header.new.
   • header.edit.
   • header.show.
   • poll.type.

8. To provide validation for your new poll object, you just need to provide an Extbase validator matching this naming convention:

   • \Vendor\YourExt\Domain\Model\WhateverPoll <- when this is your poll entity
   • \Vendor\YourExt\Domain\Validator\WhateverPollValidator <- this is the validator to be expected

   Important

   If the validator is not existing, validation for this poll entity is disabled!

Issues

If you experienced issues with this extension or if you have a feature request, please visit the issue tracker on Github: https://github.com/fgtclb/t3oodle/issues

0.10.0

• [TASK] Make t3oodle compatible with TYPO3 v11
• [TASK] remove old setup scripts
• [TASK] add rector
• [TASK] remove slots and add events

0.9.2

• [BUGFIX] Always use string comparison to identify "simple" and "schedule" polls

0.9.1

• [BUGFIX] Do not check for FQCN when including _calendarLocale

0.9.0

• [BUGFIX] Check for vote argument, before using a non-existing one
• [TASK] Provide new signal, to modify "findPolls" query constraints
• [TASK][!!!] Replace PollType enumeration with Single Table Inheritance
• [FEATURE] New poll setting "settingMinVotesPerParticipant"

0.8.0

• [TASK][!] Rename "findByPollAndParticipantIdent" to "findOneByPollAndParticipantIdent"
• [DEVOPS] Add and apply phpstan (fixes)
• [DEVOPS] Add and apply php-cs-fixer
• [DEVOPS] Provide local .Build and add .editorconfig
• [DEVOPS] Fix deprecated "composer init" usage in DDEV install commands

• [FEATURE][!!!] Suggestion mode

  • added new actions for suggestion mode to PollController
  • added new PollStatus value "openedForSuggestions"
  • added "sorting" to option model and use in TCA and repo as default ordering
  • make options sortable using drag&drop (using new js library "html5sortable")

  • add new poll permissions:

    • isFinishSuggestionModeAllowed
    • isSuggestNewOptionsAllowed
  • provide JS drag & drop to reorder options
  • provide toggle-display JS functionality
  • bugfixes and markup improvements
• [TASK] Add "Poll/FormFields/Options/Header.html" partial
• [TASK] Allow polls with just one option
• [BUGFIX] Fixed typo

0.7.3

• [BUGFIX] Fix small typos in German translations

0.7.2

• [BUGFIX] Fix typo in Fluid template which prevents output of poll type classname
• [BUGFIX] Show "Reset votes" button also when poll status is "closed"
• [TASK] Respect current user's voting when displaying the amount of left votes
• [BUGFIX] Do not disable voting for users which have already voted

0.7.1

• [TASK] Add wrap for poll form fields
• [BUGFIX] Fix wrong partial references

0.7.0

• [TASK] Refactor all Fluid partials
• [TASK] Move finish note inside the administration box
• [TASK] Do not show empty voting rows
• [DEVOPS] Set composer to version 2 in DDEV container
• [FEATURE] Display amount of votes left in voting box
• [FEATURE] Add new options "show.showOwnVoteAtTop" and "show.showAdministrationBoxAboveVotes"

0.6.2

• [BUGFIX] Prevent participant from adding more than one vote per poll
• [BUGFIX] Remove "hidden" field of "option", "optionvalue" and "vote"
• [BUGFIX] Allow voting expire dates (in DB) to be signed

0.6.1

• [BUGFIX] Add min-width to option titles in voting table
• [TASK] Make validation issues during voting more visible

0.6.0

• [FEATURE] Change "settingOneOptionOnly" to "settingMaxVotesPerParticipant"
• [FEATURE] Add update wizard to migrate old "oneOptionOnly" setting
• [BUGFIX] Add missing label for flash messages, when own vote has been deleted

0.5.1

• [BUGFIX] Do not display administration box for all users

0.5.0

• [BUGFIX] Allow poll author to see votings, when finishing poll
• [BUGFIX] Remove "settingVotingExpiresDate" from query used in list action
• [DOCS] Improve images in documentation
• [TASK] Replace "deleteVote" with "resetVotes" action
• [TASK] When changing "secret" settings, remove existing votes
• [TASK] Do not allow finishing polls, when expiration date is set and not reached yet
• [FEATURE] Add new poll setting "Super Secret Mode"
• [BUGFIX] Fix typo in "min" input parameter (HTML)

0.4.3

• [BUGFIX] Fix error when finish action is submitted without final option set

0.4.2

• [BUGFIX] When editing simple options, after validation has been triggered no exception (PropertyMapper) is thrown anymore

0.4.1

• [BUGFIX] Rename model validators
• [BUGFIX] Remove empty "__identity" argument

0.4.0

First TER Release

• [BUGFIX] Add translations for displayed text, when poll is finished
• [TASK] Improve routes
• [BUGFIX] Add missing validate annotation for Extbase controller actions
• [DOCS] Add "Poll Lifecycle" and "Missing Features" to documentation
• [FEATURE] Initial Documentation
• [BUGFIX] Allow polls to be created from backend
• [TASK] Improve translations
• [DEVOPS] Fix old DDEV configuration
• [BUGFIX] Fix missing "checked" attribute for f:form.checkbox and f:form.radio
• [TASK] Rename "showReturnToListLink" to "showReturnLink" in TypoScript configuration
• Revert "[FEATURE] Add pluralization support for XLIFF"

0.3.0

• [TASK] Use "poll-{uid}" as slug, when sanitized title is empty (e.g. Emojis only)
• [BUGFIX] Fix updated namespace in ext_localconf.php
• [FEATURE] Add "requireAcceptedTerms" and "termsToAccept" options
• [!!!][TASK] Update vendor name in PHP classes
• [DOCS] Add credits to README and documentation index page
• [TASK] Update package name from "t3/t3oodle" to "fgtclb/t3oodle"
• [DOCS] Improvements
• [FEATURE] Add pluralization support for XLIFF
• [TASK] Remove typoscript settings "list.opened" and "list.closed"
• [BUGFIX] Do not allow to delete votes, when poll is finished
• [TASK] Disable "outputGuestNotice" by default
• [FEATURE] Respect available options (when settingMaxVotesPerOption is set)
• [BUGFIX] Fix wrong parameter in deleteVoteAction

0.2.2

• [BUGFIX] Fix missing argument in Fluid section
• [FEATURE] Refactor PollPermissions and add Signals to each permission
• [TASK] Add license to composer.json
• [BUGFIX] Move allowTableOnStandardPages from TCA to ext_tables.php

0.2.1

• [FEATURE] Add "_dynamic" setting
• [TASK] Add "getContentObjectRow" method to PollController
• [TASK] Pass "view" to all action signals with templates existing
• [TASK] Do not pass items to asynchronous loaded function calls

0.2.0

• [TASK] Apply copyrights
• [TASK] Apply PSR-2 code style
• [TASK] Add "UpdatePollSlug" Slot
• [FEATURE] Add Signals to PollController
• [TASK] Show notice when current user already voted for a poll
• [FEATURE] Add option "enableFlashMessages"
• [BUGFIX] Fix wrong fieldname for validation messages of "settingMaxVotesPerOption"
• [FEATURE] Add translations for flash & validation messages and exceptions
• [TASK] Improve conditional inputs
• [FEATURE] Add option "countMaybeVotes"
• [TASK] Make columns in list view configurable (via TypoScript)
• [FEATURE] Add translations and improvements for show view
• [FEATURE] Add translations and improvements for new and edit view
• [FEATURE] Add translations and improvements for list view
• [BUGFIX] Fix PollValidator to not check "null" in preg_match
• [BUGFIX] Fix missing default value for "poll-type" aspect
• [BUGFIX] Do not add empty option when editing schedule poll
• [FEATURE] Add extension icon
• [TASK] Prepare FlexForm plugin settings
• [TASK] Added locale to Routing Enhancer
• [BUGFIX] Show selected options, when validation fails (vote action)
• [TASK] Make properties accessible for debugging tools
• [FEATURE] Provide custom bootstrap build
• [BUGFIX] Fix voting box querySelector
• [TASK] Introduce ScheduleOptionUtility
• [BUGFIX] Fix missing "publishDirectly" variable in Fluid section
• [FEATURE] Add poll type "schedule"
• [TASK] Refactor PollValidator
• [BUGFIX] Stop event propagation, when clicking on voting box image
• [TASK] Show if current user author if poll (in list action)
• [TASK] Apply click listener to voting box' parentNode (e.g. <td>)
• [FEATURE] Enable radio-like behaviour, when setting "OneOptionOnly" is set
• [TASK] Refactor fluid templates
• [TASK] Lock username and mail input, when userIdent cookie exists
• [TASK] Add class to voting box parent node
• [TASK] Refactor fluid partials
• [TASK] Small improvements
• [TASK] Add "pollType" argument to new action
• [BUGFIX] Fix selector in options-simple module
• [TASK] Refactor javascript

0.1.*

• [TASK] Clean up TCA
• [BUGFIX] Use ParticipantInfo partial everywhere
• [TASK] Add Routing Enhancer Configuration for pagination widget
• [TASK] Refactor fluid templates
• [TASK] Introduce SVG view helper & icons
• [FEATURE] Add configurable classes
• [BUGFIX] Fix wrong variable in template and do not iterate over null
• [FEATURE] Add "DynamicUserProperties" trait

0.1.0

• Very first release of t3oodle, for testing purposes. Many open (cleanup) tasks, left.