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

[DOCS] Add extension documentation

parent e9979807
...@@ -7,6 +7,36 @@ ...@@ -7,6 +7,36 @@
ChangeLog ChangeLog
========= =========
Providing a change log chapter is optional. You can also refer .. t3-field-list-table::
users to the ChangeLog file inside the extension or to some repository's :header-rows: 1
commit listing.
- :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
...@@ -7,112 +7,61 @@ ...@@ -7,112 +7,61 @@
Configuration Configuration
============= =============
Target group: **Developers, Integrators** Target group: **Administrators**
How to configure the extension. Try to make it easy to configure the extension. How to configure the extension.
Give a minimal example or a typical example.
Configuration Module
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
==================== ====================
Possible subsections: Reference of TypoScript options. Once the extension is installed, a new backend module gets visible. Most probably at bottom of your backend.
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:
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 When you are ready, please choose "save and close" to proceed.
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.
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
.. 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
...@@ -7,50 +7,14 @@ ...@@ -7,50 +7,14 @@
Developer Corner 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();
}
);
...@@ -54,12 +54,11 @@ Extension Name ...@@ -54,12 +54,11 @@ Extension Name
Introduction/Index Introduction/Index
User/Index
Installation/Index Installation/Index
Configuration/Index Configuration/Index
User/Index
Developer/Index Developer/Index
KnownProblems/Index KnownProblems/Index
ToDoList/Index
ChangeLog/Index
Support/Index Support/Index
ChangeLog/Index
Links Links
...@@ -8,13 +8,32 @@ ...@@ -8,13 +8,32 @@
Installation Installation
============ ============
Target group: **Administrators** The extension can be installed via Extension Manager or composer.
- How should the extension be installed? Admin Groups
- Are there dependencies to resolved? ============
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 Next step
========= =========
:ref:`Configure extension <configuration>`. :ref:`Configure extension <configuration>`.
\ No newline at end of file
...@@ -13,16 +13,12 @@ Introduction ...@@ -13,16 +13,12 @@ Introduction
What does it do? What does it do?
================ ================
This chapter should give a brief overview of the extension. What does it do? What problems does it solve? This extension provides a voting system for persons and questions.
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.
.. important:: .. important::
Please don't forget to repeat your extension's version number in the Please note, that this is an early version of this extension. You must create records in the right order, to get it work
:file:`Settings.cfg` file, in the :code:`release` property. It will be
automatically picked up on the cover page by the :code:`|release|`
substitution.
.. _screenshots: .. _screenshots:
...@@ -30,13 +26,15 @@ should go on with this extension or not. ...@@ -30,13 +26,15 @@ should go on with this extension or not.
Screenshots Screenshots
=========== ===========
This chapter should help people figure how the extension works. Remove it
if not relevant.
.. figure:: ../Images/IntroductionPackage.png .. figure:: ../Images/IntroductionPackage.png
:width: 500px :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 @@ ...@@ -7,5 +7,12 @@
Known Problems Known Problems
============== ==============
Use this section for informing about any type of of problem * Error handling for empty objects. You need to create all objects in the right order, to get it work
that are not necessarily named in the bug tracker such as performance issues, ... * 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 @@ ...@@ -6,11 +6,6 @@
Links 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: :TER:
https://typo3.org/extensions/repository/view/election https://typo3.org/extensions/repository/view/election
......
...@@ -39,7 +39,7 @@ github_commit_hash = ...@@ -39,7 +39,7 @@ github_commit_hash =
github_repository = github_repository =
github_revision_msg = github_revision_msg =
github_sphinx_locale = github_sphinx_locale =
# project_contact = documentation@typo3.org project_contact = info@typo3.org
project_contact = Stefan Busemann project_contact = Stefan Busemann
# project_discussions= http://... # project_discussions= http://...
project_discussions = https://typo3.slack.com/messages/C027Z3UGQ project_discussions = https://typo3.slack.com/messages/C027Z3UGQ
...@@ -74,7 +74,7 @@ use_opensearch = ...@@ -74,7 +74,7 @@ use_opensearch =
# t3templating = https://docs.typo3.org/typo3cms/TemplatingTutorial/ # t3templating = https://docs.typo3.org/typo3cms/TemplatingTutorial/
# t3ts45 = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/ # t3ts45 = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/
# t3tsconfig = https://docs.typo3.org/typo3cms/TSconfigReference/ # 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/ # t3tssyntax = https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/
...@@ -7,5 +7,13 @@ ...@@ -7,5 +7,13 @@
Support Support
======= =======
Do you give paid or unpaid support for your extension? Add information here how to get Please report tickets at our issue tracker: https://git-t3o.typo3.org/t3o/election/issues/new
support. Maybe there is a Slack channel for your extension. Mention it here.
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
.. _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 @@ ...@@ -7,55 +7,136 @@
Users Manual 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 This view lists all Electorates. An electorate is a collection of electors. An electorate is used by an election, to identify
but we can live with it. 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. Elections
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 The nominee is listed, if the checkbox “public” is set and if the nominee is added to an election (see elections below).
pitfalls, attract their attention to important elements
or just add some notes for for information (further reading, - Start date: The election will start after this date
for example). - 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:: .. important::
Remember to always say "please" when asking your software to # of Votes: Must be greater 0 and should not be larger then the number of Nominees
do something.
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 Electors
: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.
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
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:
FAQ Next step
=== =========
Possible subsection: FAQ :ref:`Individualize the extension <developer>`.
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
<f:section name="LeftToolBar"> <f:section name="LeftToolBar">
<f:link.action class="btn btn-default" action="edit" controller="BeElectionCircular" <f:link.action class="btn btn-default" action="edit" controller="BeElectionCircular"
arguments="{electionCircular:electionCircular}"> arguments="{electionCircular:electionCircular}">
<core:icon identifier="actions-edit-rename"/> <core:icon identifier="actions-document-open"/>
</f:link.action> </f:link.action>
<f:if condition="{isPluginInstalled}"> <f:if condition="{isPluginInstalled}">
<f:then> <f:then>
......