Commit 307b181a authored by Stefan Busemann's avatar Stefan Busemann

[DOCS] Add extension documentation

parent e9979807
......@@ -7,6 +7,36 @@
Providing a change log chapter is optional. You can also refer
users to the ChangeLog file inside the extension or to some repository's
commit listing.
.. t3-field-list-table::
:header-rows: 1
- :Version:
Release Date
Release Description
- :Version:
* [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:
* Initial Release
......@@ -7,112 +7,61 @@
Target group: **Developers, Integrators**
Target group: **Administrators**
How to configure the extension. Try to make it easy to configure the extension.
Give a minimal example or a typical example.
How to configure the extension.
Minimal Example
- Is it necessary to include a static template file?
- For example add a code snippet with comments
Minimal example of TypoScript:
.. code-block:: none
plugin.tx_myextension.settings {
# configure basic email settings
email {
subject = Some subject
from =
.. _configuration-typoscript:
TypoScript Reference
Configuration Module
Possible subsections: Reference of TypoScript options.
The construct below show the recommended structure for
TypoScript properties listing and description.
When detailing data types or standard TypoScript
features, don't hesitate to cross-link to the TypoScript
Reference as shown below.
See `Hyperlinks & Cross-Referencing <>`
for information about how to use cross-references.
See the :file:`Settings.cgf` file for the declaration of cross-linking keys.
You can add more keys besides tsref.
.. container:: ts-properties
=========================== ===================================== ======================= ====================
Property Data type :ref:`t3tsref:stdwrap` Default
=========================== ===================================== ======================= ====================
allWrap_ :ref:`t3tsref:data-type-wrap` yes :code:`<div>|</div>`
`subst\_elementUid`_ :ref:`t3tsref:data-type-boolean` no 0
wrapItemAndSub_ :ref:`t3tsref:data-type-wrap`
=========================== ===================================== ======================= ====================
Property details
.. only:: html
.. contents::
:depth: 1
.. _ts-plugin-tx-extensionkey-allwrap:
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
:typoscript:`plugin.tx_extensionkey.allWrap =` :ref:`t3tsref:data-type-wrap`
At the first call, you will receive a warning for an empty configuration.
Wraps the whole item.
.. figure:: ../Images/AdministratorManual/NewConfiguration.png
:width: 5008px
:alt: Backend Module
Click at the button "create a new configuration"
.. _ts-plugin-tx-extensionkey-substelementUid:
.. figure:: ../Images/AdministratorManual/Configuration.png
:width: 5008px
:alt: Backend Module
:typoscript:`plugin.tx_extensionkey.subst_elementUid =` :ref:`t3tsref:data-type-boolean`
- **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.
If set, all appearances of the string ``{elementUid}`` in the total
element html-code (after wrapped in allWrap_) are substituted with the
uid number of the menu item. This is useful if you want to insert an
identification code in the HTML in order to manipulate properties with
When you are ready, please choose "save and close" to proceed.
Page Plugin
.. _ts-plugin-tx-extensionkey-wrapitemandsub:
Choose now the page module and the election plugin, to the page, you added to the configuration
Edit Configuration
:typoscript:`plugin.tx_extensionkey.wrapItemAndSub =` :ref:`t3tsref:data-type-wrap`
.. figure:: ../Images/AdministratorManual/EditConfig.png
:width: 5008px
:alt: Backend Module
Wraps the whole item and any submenu concatenated to it.
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
.. _configuration-faq:
:ref:`Use the extension <user>`.
Possible subsection: FAQ
.. include:: ../Includes.txt
.. _contribute:
Do you want people to contribute to your extension?
Here, you can add information about conventions you use when developing.
You may want to base this on already existing conventions for the TYPO3
core and for TYPO3 documentation.
If your project is hosted on GitHub, it is a good idea to add a file:`CONTRIBUTING.rst`
file. This sample template manual has one. A link to that file will automatically
be displayed by GitHub if people enter the issues section of your project for the first time
or create an issue.
The file:`CONTRIBUTING.rst` will not be displayed, when your extension is rendered on though (because file:`CONTRIBUTING.rst` is outside of the scope of
the file:`Documentation` folder).
So, as not to create duplicate information, either use this file as main information
source about contributing and link to this page from file:`CONTRIBUTING.rst` or the other
way around.
**Sample text follows ...**
Contribution to this extension is very welcome.
If you wish to contribute, please follow these conventions:
Writing Issues
* If you find a problem in the extension, please write an issue.
* If you can fix the problem yourself, please submit a pull request. In this
case, it is not necessary to create an issue first.
Submitting a Pull Request
* Please adhere to `TYPO3 Coding Guidelines
* For commit messages, please follow the `TYPO3 Commit Message Rules
Please see the general GitHub documentation for more information, for example
`Creating a pull request <>`__
Here, you can add a link to how people can support you and donate for your extension.
\ No newline at end of file
......@@ -7,50 +7,14 @@
Developer Corner
Target group: **Developers**
- 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.
Use this section for *providing code examples* or any **useful** information code wise.
Next step
:ref:`Known problems <knownproblems>`.
.. _developer-hooks:
Possible hook examples. Input parameters are:
| Parameter | Data type | Description |
| $table | string | Name of the table |
| $field | string | Name of the field |
Use parameter :code:`$table` to retrieve the table name...
.. _developer-api:
How to use the API...
.. code-block:: php
$stuff = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
or some other language:
.. code-block:: javascript
:emphasize-lines: 2-4
function () {
......@@ -54,12 +54,11 @@ Extension Name
......@@ -8,13 +8,32 @@
Target group: **Administrators**
The extension can be installed via Extension Manager or composer.
- How should the extension be installed?
- Are there dependencies to resolved?
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>`.
\ No newline at end of file
:ref:`Configure extension <configuration>`.
......@@ -13,16 +13,12 @@ Introduction
What does it do?
This chapter should give a brief overview of the extension. What does it do? What problems does it solve?
Who is interested in this? Basically, this section includes everything people need to know to decide whether they
should go on with this extension or not.
This extension provides a voting system for persons and questions.
.. important::
Please don't forget to repeat your extension's version number in the
:file:`Settings.cfg` file, in the :code:`release` property. It will be
automatically picked up on the cover page by the :code:`|release|`
Please note, that this is an early version of this extension. You must create records in the right order, to get it work
.. _screenshots:
......@@ -30,13 +26,15 @@ should go on with this extension or not.
This chapter should help people figure how the extension works. Remove it
if not relevant.
.. figure:: ../Images/IntroductionPackage.png
:width: 500px
:alt: Introduction Package
:alt: Frontend Election View
A result view of an election.
Introduction Package just after installation (caption of the image)
.. figure:: ../Images/AdministratorManual/Dashboard.png
:width: 500px
:alt: Admin Dashboard
How the Frontend of the Introduction Package looks like just after installation (legend of the image)
All configuration is done via backend.
......@@ -7,5 +7,12 @@
Known Problems
Use this section for informing about any type of of problem
that are not necessarily named in the bug tracker such as performance issues, ...
* 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>`
......@@ -6,11 +6,6 @@
The links to issue and the GitHub repository are maintained in the Settings.cfg.
You may want to remove this file if all important links are already handled in
......@@ -39,7 +39,7 @@ github_commit_hash =
github_repository =
github_revision_msg =
github_sphinx_locale =
# project_contact =
project_contact =
project_contact = Stefan Busemann
# project_discussions= http://...
project_discussions =
......@@ -74,7 +74,7 @@ use_opensearch =
# t3templating =
# t3ts45 =
# t3tsconfig =
t3tsref =
# t3tsref =
# t3tssyntax =
......@@ -7,5 +7,13 @@
Do you give paid or unpaid support for your extension? Add information here how to get
support. Maybe there is a Slack channel for your extension. Mention it here.
Please report tickets at our issue tracker:
If you have questions, please ask them in our Slack channel:
Please note, that we do not provide professional support.
Next step
:ref:`Development history <Changelog>`
.. include:: ../Includes.txt
.. _todo:
To-Do list
The focus for the further development are:
* Stability: Add unit and behaviour tests (Version 0.3.x)
* Performance: Make the frontend faster (Version 0.4.x)
* Improve Adminstration: Archive Elections, Import options (Version 0.5.x)
......@@ -7,55 +7,136 @@
Users Manual
Target group: **Editors**
Here should be described how to use the extension from the editor perspective.
- How does it work?
In the election module, you will set up all elections.
- works well when doing this.
.. 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.
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).
- does not work so well when doing that
but we can live with it.
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.
- **mind indentation when nesting lists**.
It consists of:
- How to install the plugin on a web page?
- Title
- Electors
- What options are available?
Language should be non-technical, explaining, using small examples.
Don't use to many acronyms unless they have been explained.
Don't be confusing by putting information targeting administrators.
.. tip::
This view lists all nominees. A new election can be added manually by clicking at plus icon at top left.
Take a break from time to time.
.. figure:: ../Images/UserManual/ElectionEdit.png
:width: 400px
:alt: Options
Admonitions should be used to warn the users about potential
pitfalls, attract their attention to important elements
or just add some notes for for information (further reading,
for example).
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::
Remember to always say "please" when asking your software to
do something.
# of Votes: Must be greater 0 and should not be larger then the number of Nominees
Provide screenshots as needed for making things clear. When creating
screenshots, try using the `Introduction Package <>`_
as a neutral TYPO3 CMS instance.
.. figure:: ../Images/UserManual/BackendView.png
:width: 500px
:alt: Backend view
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.
The last step: Send out the voting tokens. An elector needs a voting token to vote.
.. figure:: ../Images/UserManual/CircularEdit.png
:width: 400px
:alt: Options
Subject: The subject of the mail, the elector receives
Body: Message of the voting mail. Please use the definded placeholders
Recipients: Choose an electorate. The members will receive the voting tokens.
**Available Marker: Available Marker:**
- {elector.salutation}(Mr.| Mrs.)
- {elector.firstName}
- {elector.middleName}
- {elector.lastName}
- {elector.fullName} (= FirstName + MiddleName + LastName)
- {}
- {} (clickable link to vote)
.. important::
You must use the {} marker, otherwise voting link will be in the mail
Once you have saved your circular, you can send it, by clicking at the "play" button.
.. figure:: ../Images/UserManual/Circular.png
:width: 400px
:alt: Options