[DOCS] Add extension documentation

Documentation/ChangeLog/Index.rst

@@ -7,6 +7,36 @@
 ChangeLog
 =========
 
-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:
+      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

Documentation/Configuration/Index.rst

@@ -7,112 +7,61 @@
 Configuration
 =============
 
-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 = someemail@domain.de
-      }
-   }
-
-.. _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 <https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/Hyperlinks.html>`
-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.
-
-
-Properties
-==========
-
-.. 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::
-      :local:
-      :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.
 
-allWrap
--------
+.. 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:
 
-subst_elementUid
-----------------
+.. 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
-JavaScript.
+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
 
-wrapItemAndSub
---------------
+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>`.
 
-FAQ
-===
 
-Possible subsection: FAQ

Documentation/Contribute/Index.rst

-.. include:: ../Includes.txt
-
-
-.. _contribute:
-
-==========
-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
-docs.typo3.org 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
-  <https://docs.typo3.org/typo3cms/CoreApiReference/CodingGuidelines/Index.html>`__
-* For commit messages, please follow the `TYPO3 Commit Message Rules
-  <https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/CommitMessage.html>`__
-
-
-Please see the general GitHub documentation for more information, for example
-`Creating a pull request <https://help.github.com/articles/creating-a-pull-request/>`__
-
-Donate
-======
-
-Here, you can add a link to how people can support you and donate for your extension.
\ No newline at end of file

Documentation/Developer/Index.rst

@@ -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:
-
-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:
-
-API
-===
-
-How to use the API...
-
-.. code-block:: php
-
-   $stuff = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
-      '\\Foo\\Bar\\Utility\\Stuff'
-   );
-   $stuff->do();
-
-or some other language:
-
-.. code-block:: javascript
-   :linenos:
-   :emphasize-lines: 2-4
-
-   $(document).ready(
-      function () {
-         doStuff();
-      }
-   );

Documentation/Index.rst

@@ -54,12 +54,11 @@ Extension Name
 
 
    Introduction/Index
-   User/Index
    Installation/Index
    Configuration/Index
+   User/Index
    Developer/Index
    KnownProblems/Index
-   ToDoList/Index
-   ChangeLog/Index
    Support/Index
+   ChangeLog/Index
    Links

Documentation/Installation/Index.rst

@@ -8,13 +8,32 @@
 Installation
 ============
 
-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>`.

Documentation/Introduction/Index.rst

@@ -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|`
-   substitution.
+   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.
 Screenshots
 ===========
 
-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.

Documentation/KnownProblems/Index.rst

@@ -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>`

Documentation/Links.rst

@@ -6,11 +6,6 @@
 Links
 -----
 
-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
-Settings.cfg.
-
 
 :TER:
    https://typo3.org/extensions/repository/view/election

Documentation/Settings.cfg

@@ -39,7 +39,7 @@ github_commit_hash   =
 github_repository    =
 github_revision_msg  =
 github_sphinx_locale =
-# project_contact    = documentation@typo3.org
+ project_contact     = info@typo3.org
 project_contact      = Stefan Busemann
 # project_discussions= http://...
 project_discussions  = https://typo3.slack.com/messages/C027Z3UGQ
@@ -74,7 +74,7 @@ use_opensearch       =
 # 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/
+# t3tsref       = https://docs.typo3.org/typo3cms/TyposcriptReference/
 # t3tssyntax    = https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/
 
 

Documentation/Support/Index.rst

@@ -7,5 +7,13 @@
 Support
 =======
 
-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: 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>`
+

Documentation/ToDoList/Index.rst

-.. 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)

Documentation/User/Index.rst

@@ -7,55 +7,136 @@
 Users Manual
 ============
 
-Target group: **Editors**
 
-Here should be described how to use the extension from the editor perspective.
+Overview
+========
 
-- 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.
+
+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
+===========
 
-  - 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.
+Elections
+=========
 
-.. 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 <http://demo.typo3.org/>`_
-as a neutral TYPO3 CMS instance.
 
-.. figure:: ../Images/UserManual/BackendView.png
-   :width: 500px
-   :alt: Backend view
+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.
+
+.. 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)
+- {elector.email}
+- {electionCircular.link} (clickable link to vote)
+
+.. important::
+
+   You must use the {electionCircular.link} 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
+