Improve documentation

README.md

@@ -3,9 +3,10 @@
 ## Scope
 
 This extension provides a lot of additional features to CiviCRM's events. In
-particular, you will be able to configure events in CiviCRM, display/use that
-information in other remote systems and submit registrations for those events
-back to CiviCRM.
+particular, you will be able to 
++ configure events in CiviCRM
++ display/use that information in other remote systems and
++ submit registrations for those events back to CiviCRM.
 
 The general idea is that your organization's staff can do all relevant event
 configurations in CiviCRM. CiviCRM will then make this information available via
@@ -17,157 +18,75 @@ detailed event information, registration forms etc. (this could be a remote
 system or the CMS your CiviCRM runs on) and also submit information entered by
 your constituents back to CiviCRM.
 
-All of this requires that you have or set up an external system to act as a
+All of this requires that you set up an external system to act as a
 frontend for your event listings, registration forms etc. In case you would like
-to build your system based on Drupal 8 you will most likely want to have a look
-and/or use the CiviRemote Drupal module which includes a lot of pre-built
-features (https://github.com/systopia/civiremote).
+to build your system based on Drupal 10 you will most likely want to have a look
+and/or use the **CiviRemote Drupal module** [which includes a lot of pre-built
+features](https://github.com/systopia/civiremote).
 
 Note that this extension may be used alongside regular CiviCRM event
-registrations - you can choose whether you would like to use the remote features
-or not for each event.
+registrations - you can choose for each event whether you would like to use the 
+remote features or not.
 
 ### Why this Extension?
 
-In many cases you may not want or be able to use CiviCRM's built in forms e.g.:
+In many cases you may not want or be able to use CiviCRM's built-in forms e.g.:
 
 * For security reasons your CiviCRM runs within a VPN
-* The built in forms and processing logic do not provide enough options to be
+* The builtin forms and processing logic do not provide enough options to be
   customized to your needs
 * You may already have an external system for your constituents (such as a
   member area on your website or a collaboration platform) which cannot easily
   be connected to CiviCRM
 
-This extension is licensed
-under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0).
+This extension is licensed under 
+[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0).
 
 ## Features
 
-* Connect another (remote) system to CiviCRM that can handle highly customizable
+* Connect a (remote) system to CiviCRM that can handle highly customizable
   event listings and registration features
 * Pre-defined registration profiles including a "one click registration" for
-  authenticated users (additional profiles can be added fairly easy)
-* Use different registration profiles withn the same event
+  authenticated users
+* Use different registration profiles within the same event
 * Allow participants to modify and/or cancel their own registrations
 * Alternative approach for defining an event's location
-
-TODO: Complete Feature List
+* Event registration/update profiles to be configured using an UI with the 
+[Remote Event Form Editor](https://github.com/systopia/remoteeventformeditor) 
+extension
+* Have Sessions/Workshops within your event
+* Registering additional participants (coming)
+* Localizing event registration profiles with a locale given in the get_form 
+request (e.g. the current language of the frontend)
 
 ## Requirements
 
 * PHP v7.0+
 * CiviCRM 5.61
-* Dependency on CiviCRM Extension "Remote Tools" (de.systopia.remotetools)
-* Dependency on CiviCRM Extension "Extended Contact Matcher" (de.systopia.xcm)
+* Dependency on CiviCRM Extension 
+**[Remote Tools](https://github.com/systopia/de.systopia.remotetools)**
+* Dependency on CiviCRM Extension 
+**[Extended Contact Matcher](https://github.com/systopia/de.systopia.xcm)**
 * A system that will serve as your public system such as an external website
 
-TODO: List extensions that integrate with Remote Event Extensions
-
-## Configuration
-
-After installing the extension, make sure your Remote Tool settings are
-according to your needs (refer to docmunentation provided in
-de.systopia.remotetools). Then head on to the general configuration:
-
-* Navigate to >>Administer >>Remote Events - General Configuration.
-* Define which participant statuses will block a re-registration to your
-  events (e.g. rejected) and which roles you would like to assign to speakers.
-* Configure which default matcher profile you would like to use (XCM-Extension).
-  If using registration updates, make sure the XCM profile has the *Match
-  contacts by contact ID* activated, as otherwise duplicate contacts might be
-  created when updating event registrations.
-* Enter the urls to be used for registrations, modifications of registrations
-  and cancellations which will depend on the external system you use. In case
-  you use the CiviRemote Drupal module you may
-  use https://yourdomain.org/d8civiremote/,
-  https://yourdomain.org/d8civiremote/modify/,
-  https://yourdomain.org/d8civiremote/cancel/
-
-After general configuration visit the new tab "Remote Online Registration"
-within CiviCRM's event configuration UI. It will provide you with several
-options and settings, most noteably if you would like to use the remote event
-features, if you would like to disable native CiviCRM online registration and
-which registration profiles to use.
-
-The "Registration Restrictions" allow you configurations regarding when
-registration is available, if a registration requires manual review and if
-participants can cancel or modify their own registrations.
-
-The "Public Event Text Blocks" may be used by your external system to display
-the information at the appropriate places during the registration process. How
-and when this information is presented to your constituents will depend on the
-design of your external system.
-
-CiviCRM's other basic event settings still apply and may be used in your
-external system, e.g. it's title, descriptions, start and end dates, max. number
-of participants, waitlist settings etc..
-
-### Alternative Event Location Settings
-
-As the the default event location feature is somewhat limited you can choose to
-use a feature for alternative event locations. If you do so CiviCRM's regular
-event location tab will be hidden and a custom tab will appear in which you can
-choose a contact that has the subtype "event location" (the subtype is created
-when installing the extension). Also, you can provide information on the event
-location that applies for that particular event (such as the room number or
-travel instructions).
-
-The API will then make the choosen event locations basic data availabe,
-including it's name, address, geodata and the additional information for this
-event. This information can be displayed and used in other ways by the external
-system.
-
-## Remote Event API
-
-The extension exposes a new API to remote event listings or registration
-systems:
-
-1. ``RemoteEvent.get`` allows querying for remotely available events in the same
-   way ``Event.get`` would
-1. ``RemoteEvent.create`` allows creating remotely available events in the same
-   way ``Event.create`` would
-1. ``RemoteParticipant.get_form`` returns a default specification fo the
-   registration form required for signing up/cancel/update
-1. ``RemoteParticipant.create`` sign somebody up for an event by providing the
-   necessary form data (as requested by ``RemoteParticipant``)
-1. ``RemoteRegistration.validate`` ask the system for validating the given
-   signup data before the actual registration
-1. ``RemoteRegistration.cancel`` cancel an existing registration, identified by
-   remote_contact_id or token
-1. ``RemoteRegistration.update`` update an existing registration, identified by
-   remote_contact_id or token
-
-Please note that all these API actions come with an independent set of
-permissions.
-
-## Extensibility and Interoperability
-
-This extension uses a series of Symfony events to extend and customise the
-behaviour of these calls:
-
-1. ``civi.remoteevent.get.params`` modify / restrict query parameters to event
-   information
-1. ``civi.remoteevent.get.result`` modify / extend event information
-1. ``civi.remoteevent.spawn.params`` modify / extend parameters for creating or
-   updating a remote event
-1. ``civi.remoteevent.registration.validate`` modify / extend signup data
-1. ``civi.remoteevent.registration.submit``modify / extend signup process
-1. ``civi.remoteevent.registration.cancel``modify / extend cancellation process
-1. ``civi.remoteevent.registration.getform``modify / extend registration form
-1. ``civi.remoteevent.cancellation.getform``modify / extend cancellation form
-1. ``civi.remoteevent.registration_update.getform``modify / extend update form
-1. ``civi.remoteevent.label`` modify or override certain labels (e.g. workshop
-   groups)
+## extensions that integrate with the Remote Event Extensions
+* [Remote Event Form Editor](https://github.com/systopia/remoteeventformeditor)  
+A drag&drop form editor for event-registration
+* [Event Invitations](https://github.com/systopia/de.systopia.eventinvitation)
+* [Custom Event Communication](https://github.com/systopia/de.systopia.eventmessages)
+* [Event-Checkin](https://github.com/systopia/de.systopia.eventcheckin)
 
 ## Documentation
 - EN: https://docs.civicrm.org/remoteevent/en/latest (automatic publishing)
 
 ## We need your support
-This CiviCRM extension is provided as Free and Open Source Software,
-and we are happy if you find it useful. However, we have put a lot of work into it
-(and continue to do so), much of it unpaid for. So if you benefit from our software,
-please consider making a financial contribution so we can continue to maintain and develop it further.
-
-If you are willing to support us in developing this CiviCRM extension,
-please send an email to [email protected] to get an invoice or agree a different payment method.
-Thank you!
+This CiviCRM extension is provided as Free and Open Source Software, and we are 
+happy if you find it useful. However, we have put a lot of work into it (and 
+continue to do so), much of it unpaid for. So if you benefit from our software,
+please consider making a financial contribution, so we can continue to maintain 
+and develop it further.
+
+If you are willing to support us in developing this CiviCRM extension, please 
+email to [info\@systopia.de](mailto:[email protected]?subject=supportSYSTOPIA) 
+to get an invoice or agree a different payment method.
+Thank you!

docs/api.md

@@ -0,0 +1,22 @@
+## Remote Event API
+
+The extension exposes a new API to remote event listings or registration 
+systems:
+
++ ``RemoteEvent.get`` allows querying for remotely available events in the same
+   way ``Event.get`` would
++ ``RemoteEvent.create`` allows creating remotely available events in the same
+   way ``Event.create`` would
++ ``RemoteParticipant.get_form`` returns a default specification fo the
+   registration form required for signing up/cancel/update
++ ``RemoteParticipant.create`` sign somebody up for an event by providing the
+   necessary form data (as requested by ``RemoteParticipant``)
++ ``RemoteRegistration.validate`` ask the system for validating the given
+   signup data before the actual registration
++ ``RemoteRegistration.cancel`` cancel an existing registration, identified by
+   remote_contact_id or token
++ ``RemoteRegistration.update`` update an existing registration, identified by
+   remote_contact_id or token
+
+Please note that all these API actions come with an independent set of
+permissions.

docs/configuration.md

@@ -0,0 +1,66 @@
+## Configuration
+
+After installing the extension, make sure your **Remote Tool settings** are
+according to your needs (refer to documentation provided in
+[de.systopia.remotetools](https://github.com/systopia/de.systopia.remotetools)). 
+Then head on to the general configuration:
+
+* Navigate to >>Administer >>CiviEvent >>Remote Events - General Configuration
+  (/civicrm/admin/remoteevent/settings).
+* Define which participant status will block a re-registration to your
+  events (e.g. rejected) and which roles you would like to assign to speakers.
+* Suppress workshop/session data if you do not use this feature
+* Select activity-type for changes in participation data
+* Configure which default matcher profile you would like to use (XCM-Extension).
+  If using registration updates, make sure the XCM profile has the *Match
+  contacts by contact ID* activated, as otherwise duplicate contacts might be
+  created when updating event registrations.
+* Enter the urls to be used for registrations, modifications of registrations
+  and cancellations which will depend on the external system you use. In case
+  you use the CiviRemote Drupal module you may
+  use https://yourdomain.org/civiremote/event/update/{token},
+  https://yourdomain.org/civiremote/event/cancel/{token}
+
+After general configuration visit the new tab "Remote Online Registration"
+within CiviCRM's event configuration UI. It will provide you with several
+options and settings, under the tabs "Online-Registration (CiviRemote)" and 
+"Workshops". Most notably if you would like to use the remote event features at 
+all, or to disable native CiviCRM online registration, use alternative 
+event-locations or external identification to your event.
+
+Beneath you find two segments for registration profiles. One for the initial 
+registration and the other for editing registrations. We think that the labels 
+and help-pop-ups are telling you enough to understand your options.
+
+The "Registration Restrictions" allow you configurations regarding when
+registration is available, if a registration requires manual review and if
+participants can cancel or modify their own registrations.
+
+The section "Additional Participants" is a new feature, that allows you to add a
+ group of people by just one single registration. Resulting in a form, where the
+participant is able to multiply the desired registration-information until a 
+maximum of up to 9 further participants using increase/decrease buttons.
+
+The "Public Event Text Blocks" may be used by your external system to display
+the information at the appropriate places during the registration process. How
+and when this information is presented to your constituents will depend on the
+design of your external system.
+
+CiviCRM's other basic event settings still apply and may be used in your
+external system, e.g. it's title, descriptions, start and end dates, max. number
+of participants, waitlist settings etc...
+
+### Alternative Event Location Settings
+
+As the default event location feature is somewhat limited you can choose to
+use a feature for alternative event locations. If you do so CiviCRM's regular
+event location tab will be hidden and a custom tab will appear in which you can
+choose a contact that has the subtype "event location" (the subtype is created
+when installing the extension). Also, you can provide information on the event
+location that applies for that particular event (such as the room number or
+travel instructions).
+
+The API will then make the chosen event locations basic data available,
+including its name, address, geo data and the additional information for this
+event. This information can be displayed and used in other ways by the external
+system.

docs/extensibility.md

@@ -0,0 +1,18 @@
+## Extensibility and Interoperability
+
+This extension uses a series of Symfony events to extend and customise the
+behaviour of these calls:
+
++ ``civi.remoteevent.get.params`` modify / restrict query parameters to event
+   information
++ ``civi.remoteevent.get.result`` modify / extend event information
++ ``civi.remoteevent.spawn.params`` modify / extend parameters for creating or
+   updating a remote event
++ ``civi.remoteevent.registration.validate`` modify / extend signup data
++ ``civi.remoteevent.registration.submit``modify / extend signup process
++ ``civi.remoteevent.registration.cancel``modify / extend cancellation process
++ ``civi.remoteevent.registration.getform``modify / extend registration form
++ ``civi.remoteevent.cancellation.getform``modify / extend cancellation form
++ ``civi.remoteevent.registration_update.getform``modify / extend update form
++ ``civi.remoteevent.label`` modify or override certain labels (e.g. workshop
+   groups)

mkdocs.yml

@@ -6,7 +6,10 @@ theme:
   name: material
 
 nav:
-  - 'Home': index.md
+  - 'Introduction': index.md
+  - 'Configuration': configuration.md
+  - 'API': api.md
+  - 'Extensibility': extensibility.md
 
 markdown_extensions:
   - attr_list