Commit 8bee914a authored by Stefan Busemann's avatar Stefan Busemann

Merge branch '2-add-documentation' into 'master'

Resolve "add documentation"

Closes #2

See merge request t3o/election!5
parents a4176f1b 307b181a
/Documentation-GENERATED-temp
0.2.5 First productive Release
\ No newline at end of file
# Changelog
| Version | Release | Type | Description |
| ------- | ---------- | ----- | --------------------------------------- |
| 0.1.0 | 15.03.2019 | Major | Alpha version |
| 0.2.5 | 19.03.2019 | Major | Beta version / first productive release |
| 0.2.6 | | Minor | Beta version / TER release |
# Contribution
## Information about contributing to this extenstion
Your contribution is welcome. Feel free to create issues. You can also create a
merge request. Please note, that we only review merge request
### Create Issues
* If you find something missing or something is wrong in this extension,
you are welcome to write an issue at https://git-t3o.typo3.org/t3o/election/issues/new that is describing the problem.
* If you can, please try to fix the problem yourself and create a merge reuest in this project (you need request group access first)
* For every change, it is necessary to create an issue first.
### Get help
* If you need help with contributing to this extension or If you want to get a maintainer of the extension, please contact: stefan.busemann@typo3.org
### requirments for merge requests
* if the coding guidelines are fullfilled
* acceptance criterias are described
* unit tests are running
If you want to get a maintainer of the extension, please contact:
stefan.busemann@typo3.org
\ No newline at end of file
......@@ -16,7 +16,6 @@ namespace TYPO3\Election\Controller;
use Doctrine\Common\Util\Debug;
use TYPO3\CMS\Core\Messaging\AbstractMessage;
use TYPO3\CMS\Extbase\Utility\DebuggerUtility;
use TYPO3\CMS\Extbase\Utility\LocalizationUtility;
/**
......@@ -71,7 +70,6 @@ abstract class AbstractProtectedBeController extends AbstractBeController
$this->request->setOriginalRequestMappingResults($this->arguments->getValidationResults());
$this->forward($referringRequest->getControllerActionName(), $referringRequest->getControllerName(), $referringRequest->getControllerExtensionName(), $referringRequest->getArguments());
}
DebuggerUtility::var_dump($this->request['nominee.image']);
$message = 'An error occurred while trying to call ' . get_class($this) . '->' . $this->actionMethodName . '().' . PHP_EOL;
return $message;
......
......@@ -14,7 +14,6 @@ namespace TYPO3\Election\Controller;
* The TYPO3 project - inspiring people to share!
*/
use TYPO3\CMS\Core\Messaging\AbstractMessage;
use TYPO3\CMS\Extbase\Utility\DebuggerUtility;
use TYPO3\CMS\Extbase\Utility\LocalizationUtility;
use TYPO3\Election\Domain\Repository\ElectionCircularRepository;
use TYPO3\Election\Domain\Repository\ElectorImportRepository;
......
.. include:: ../Includes.txt
.. _changelog:
=========
ChangeLog
=========
.. t3-field-list-table::
:header-rows: 1
- :Version:
Version
:Date:
Release Date
:Changes:
Release Description
- :Version:
0.2.5
:Date:
2019-05-29
:Changes:
* [FEATURE] Add custom controller error message
* [FEATURE] Improve list styling
* [TASK] Add URLs to nominees
* [BUGFIX] Correct some typos
* [BUGFIX] Remove obsolete charakters
* [BUGFIX] Show result status of an election
* [BUGFIX] Rename method to isGroupConfigComplete
* [BUGFIX] Add fallback configuration
* [BUGFIX] Use doctrine for plugin detection
- :Version:
0.1.0
:Date:
2019-03-15
:Changes:
* Initial Release
.. include:: ../Includes.txt
.. _configuration:
=============
Configuration
=============
Target group: **Administrators**
How to configure the extension.
Configuration Module
====================
Once the extension is installed, a new backend module gets visible. Most probably at bottom of your backend.
.. figure:: ../Images/AdministratorManual/BE-Module.png
:width: 400px
:alt: Backend Module
At the first call, you will receive a warning for an empty configuration.
.. figure:: ../Images/AdministratorManual/NewConfiguration.png
:width: 5008px
:alt: Backend Module
Click at the button "create a new configuration"
.. figure:: ../Images/AdministratorManual/Configuration.png
:width: 5008px
:alt: Backend Module
- **Administration backend user group**: Choose a backend user group, which is allowed to edit the configuration
- **Election manager backend user group**: Choose a backend user group, which is allowed to edit the election
- **Poll manager backend user group**: Choose a backend user group, which is allowed to edit polls
- **Plugin PID**: Page ID of the election plugin
- **Number of mails to send at once**: Set number of mails, which will send out in one request. In a normal environment 100 Mails should be possible
- **Email address of the sender**: Valid email, which is used to send out the mails.
- **Name of the sender**: Name of the sender, which is displayed in the mail
- **Debug mode (will send all invitations to the configured test mail, but creates only dummy tokens)**: Enables the debug mode
- **Debug test e-mail**: Mail which is used in debug mode.
When you are ready, please choose "save and close" to proceed.
Page Plugin
===========
Choose now the page module and the election plugin, to the page, you added to the configuration
Edit Configuration
==================
.. figure:: ../Images/AdministratorManual/EditConfig.png
:width: 5008px
:alt: Backend Module
If you want to edit an existing configuration (and you are member of the administration group), you can use the tool icon to edit the configuration.
Next step
=========
:ref:`Use the extension <user>`.
.. include:: ../Includes.txt
.. _developer:
================
Developer Corner
================
- Use your own templates: This is an option, what we plan to support in future. Due to the special setup, you are not able to
overwrite templates
- Reset configuration: If you into a missconfiguraion, please empty table tx_election_domain_model_configuration or delete the record with the
highest uid. A configuration record is written, each time the configuration is changed. The sytem uses always the configuration
record with highest uid.
Next step
=========
:ref:`Known problems <knownproblems>`.
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. This is 'Includes.txt'. It is included at the very top of each and
every ReST source file in this documentation project (= manual).
.. ==================================================
.. DEFINE SOME TEXT ROLES
.. --------------------------------------------------
.. role:: typoscript(code)
.. role:: ts(typoscript)
:class: typoscript
.. role:: php(code)
.. highlight:: php
.. include:: Includes.txt
.. Every manual should have a start label for cross-referencing to
.. start page. Do not remove this!
.. _start:
=============================================================
Extension Name
=============================================================
.. only:: html
:Classification:
election
:Version:
|release|
:Language:
en
:Description:
Manual covering TYPO3 extension election
:Keywords:
voting, election, poll
:Copyright:
2015-2019
:Author:
Oliver Eglseder, Stefan Busemann, Christoph Paschner
:Email:
info@typo3.org
:License:
This document is published under the Open Publication License
available from http://www.opencontent.org/openpub/
:Rendered:
|today|
The content of this document is related to TYPO3,
a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
**Table of Contents**
.. toctree::
:maxdepth: 3
Introduction/Index
Installation/Index
Configuration/Index
User/Index
Developer/Index
KnownProblems/Index
Support/Index
ChangeLog/Index
Links
.. include:: ../Includes.txt
.. _installation:
============
Installation
============
The extension can be installed via Extension Manager or composer.
Admin Groups
============
The extension behaves different then many other TYPO3 Extensions. It is designed,
to work without many configuration. The main configuration is done in the
Backend Module "Election". To prepare the configuration, make sure, that you have at least one
Backend User Group in your installation. To be most flexible, you should set up three usergroups:
* Administration backend user group
* Election manager backend user group
* Poll manager backend user group
.. important::
Create at least one backend usergroup, before starting the configuration in the Election module
Create a page for the plugin
============================
To prepare the configuration, please create a page, where you want to place the voting plugin. Remember the page id for
the next configuration step.
Next step
=========
:ref:`Configure extension <configuration>`.
.. include:: ../Includes.txt
.. _introduction:
============
Introduction
============
.. _what-it-does:
What does it do?
================
This extension provides a voting system for persons and questions.
.. important::
Please note, that this is an early version of this extension. You must create records in the right order, to get it work
.. _screenshots:
Screenshots
===========
.. figure:: ../Images/IntroductionPackage.png
:width: 500px
:alt: Frontend Election View
A result view of an election.
.. figure:: ../Images/AdministratorManual/Dashboard.png
:width: 500px
:alt: Admin Dashboard
All configuration is done via backend.
.. include:: ../Includes.txt
.. _known-problems:
==============
Known Problems
==============
* Error handling for empty objects. You need to create all objects in the right order, to get it work
* Performance: The performance is partly very poor.
* Archive. If an election is over, the data should get archived
* Use CronJobs to send invitations
Next step
=========
:ref:`Get support / contribute <support>`
.. include:: Includes.txt
.. _links:
Links
-----
:TER:
https://typo3.org/extensions/repository/view/election
:Issues:
https://git-t3o.typo3.org/t3o/election/issues
:Github Repository:
https://git-t3o.typo3.org/t3o/election
:Contact:
`typo3.org website team <https://typo3.slack.com/messages/C027Z3UGQ>`__
# coding: utf-8
# #####
#
# Settings.cfg - A TYPO3 Documentation Project's Configuration File
# Information about Settings.cfg:
# https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#settings-cfg
#
# About Syntax:
# See https://docs.python.org/2/library/configparser.html
#
# Attention:
# Only " ;" can start an inline comment.
# This is: blank PLUS semicolon!
#
# #####
[general]
; endless list of all of the general simple settings
; you can use in 'conf.py'
project = election
version = 0.2.6
release = 0.2.6
t3author = Stefan Busemann
copyright = since 2015 by Stefan Busemann
description = This extension provides a voting / polling option. You can create nominees, elections, circulars and import or create electors
[html_theme_options]
; for theme t3SphinxThemeRtd
# NOTE: Fill in YOUR values in the following!
github_branch = latest
github_commit_hash =
github_repository =
github_revision_msg =
github_sphinx_locale =
project_contact = info@typo3.org
project_contact = Stefan Busemann
# project_discussions= http://...
project_discussions = https://typo3.slack.com/messages/C027Z3UGQ
# project_home =
project_home =
# project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/issues
project_issues = https://git-t3o.typo3.org/t3o/election/issues/new
# project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual
project_repository = https://git-t3o.typo3.org/t3o/election
use_opensearch =
[intersphinx_mapping]
; Comment out what you don't use.
; Uncomment only what you actually use in crossreferencing!
# t3api = https://typo3.org/api/typo3cms/
# t3cgl = https://docs.typo3.org/typo3cms/CodingGuidelinesReference/
# t3coreapi = https://docs.typo3.org/typo3cms/CoreApiReference/
# t3editors = https://docs.typo3.org/typo3cms/EditorsTutorial/
# t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/
# t3fal = https://docs.typo3.org/typo3cms/FileAbstractionLayerReference/
# t3inside = https://docs.typo3.org/typo3cms/InsideTypo3Reference/
# t3install = https://docs.typo3.org/typo3cms/InstallationGuide/
# t3l10n = https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/
# t3security = https://docs.typo3.org/typo3cms/SecurityGuide/
# t3services = https://docs.typo3.org/typo3cms/Typo3ServicesReference/
# t3skinning = https://docs.typo3.org/typo3cms/SkinningReference/
# t3start = https://docs.typo3.org/typo3cms/GettingStartedTutorial/
# t3tca = https://docs.typo3.org/typo3cms/TCAReference/
# t3templating = https://docs.typo3.org/typo3cms/TemplatingTutorial/
# t3ts45 = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/
# t3tsconfig = https://docs.typo3.org/typo3cms/TSconfigReference/
# t3tsref = https://docs.typo3.org/typo3cms/TyposcriptReference/
# t3tssyntax = https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/
.. include:: ../Includes.txt
.. _support:
=======
Support
=======
Please report tickets at our issue tracker: https://git-t3o.typo3.org/t3o/election/issues/new
If you have questions, please ask them in our Slack channel: https://typo3.slack.com/messages/C027Z3UGQ
Please note, that we do not provide professional support.
Next step
=========
:ref:`Development history <Changelog>`
.. include:: ../Includes.txt
.. _user-manual:
============
Users Manual
============
Overview
========
In the election module, you will set up all elections.
.. figure:: ../Images/UserManual/Options.png
:width: 500px
:alt: Options
- Nominees: Create or update nominees
- Elections: The election itself
- Electorates: A collection of electors. An electorate elects the nominees in an election.
- Electors: List, edit, update the electors. An elector is the person who is allowed to vote.
- Circulars: Send out the voting tokens to the electors.
Nominees
========
This view lists all nominees. A new nominee can be added manually by clicking at plus icon at top left.
.. figure:: ../Images/UserManual/addNominee.png
:width: 400px
:alt: Options
The nominee is listed, if the checkbox “public” is set and if the nominee is added to an election (see elections below).
Electorates
===========
This view lists all Electorates. An electorate is a collection of electors. An electorate is used by an election, to identify
its electors. A new electorate can be added manually by clicking at plus icon at top left.
It consists of:
- Title
- Electors
Elections
=========
This view lists all nominees. A new election can be added manually by clicking at plus icon at top left.
.. figure:: ../Images/UserManual/ElectionEdit.png
:width: 400px
:alt: Options
The nominee is listed, if the checkbox “public” is set and if the nominee is added to an election (see elections below).
- Start date: The election will start after this date
- End date: The election will end at this date
- Electorate: The electorate, which contains the electors
- Nominees: The nominees, which can be elected in this election
- # of Votes/Elector: You can customize, how many votes an elector has for this vote.
.. important::
# of Votes: Must be greater 0 and should not be larger then the number of Nominees
Electors
========
This view lists all Electors. An elector is allowed to elect in an election. If you add an elector, the Email address is
mandatory, because the voting token is send by Email. The elector can be created manually
“Add elector” or imported (“import electors”).
.. figure:: ../Images/UserManual/Import.png
:width: 400px
:alt: Options.. figure:: ../Images/UserManual/Import.png
:width: 400px
:alt: Options
**Import format:**
- CSV Format
- Field delimter: “;”
- Encoding: UTF-8
- Columns
- firstName
- middleName
- lastName
- Gender
- email
You can export all electors and receive a csv file.
Circulars
=========
The last step: Send out the voting tokens. An elector needs a voting token to vote.