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

[DOCS] Add extension documentation

parent e9979807
......@@ -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
Default Backend view (caption of the image)
In the send dialogue, you get a preview of the mail and you can use a testmail. To send out the mails, please use the button
"Send Invitations".
.. figure:: ../Images/UserManual/CircularSend.png
:width: 400px
:alt: Options
.. _user-faq:
Next step
Possible subsection: FAQ
:ref:`Individualize the extension <developer>`.
......@@ -5,7 +5,7 @@
<f:section name="LeftToolBar">
<f:link.action class="btn btn-default" action="edit" controller="BeElectionCircular"
<core:icon identifier="actions-edit-rename"/>
<core:icon identifier="actions-document-open"/>
<f:if condition="{isPluginInstalled}">
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment