diff --git a/README.md b/README.md index 9622ea0..554aa3b 100644 --- a/README.md +++ b/README.md @@ -1,173 +1,85 @@ # SYSTOPIA's Remote Event Extension - ## 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. - -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 -its REST API. The extension's API also has built in logic and actions to receive -and update registrations. - -Any external system can interact with the API and display event calendars, -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 -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). - -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. - -### Why this Extension? - -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 - 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 adds numerous features to CiviCRM's events. Specifically, it +allows you to: ++ Configure events in CiviCRM ++ Display and use that information in other remote systems ++ Submit registrations for those events back to CiviCRM + +The main idea is that your organization's staff can handle all relevant event +configurations in CiviCRM. CiviCRM then makes this information available via its +REST API. The extension's API also includes logic and actions to receive and +update registrations. + +Any external system can interact with the API to display event calendars, +detailed event information, registration forms, etc. This can be a remote system +or the CMS your CiviCRM runs on. It can also submit information entered by your +constituents back to CiviCRM. + +To use these features, you must set up an external system to act as a frontend +for your event listings, registration forms, etc. If you plan to build your +system on Drupal 10, consider using the +[CiviRemote Drupal module](https://github.com/systopia/civiremote) which +includes many pre-built features. + +Note that this extension can be used alongside regular CiviCRM event +registrations. You can choose for each event whether to use the remote features +or not. + +## Why this Extension? +There are several scenarios where you might not want or be able to use CiviCRM's +built-in forms, such as: ++ Your CiviCRM runs within a VPN for security reasons ++ The built-in forms and processing logic do not offer enough customization +options ++ You already have an external system for your constituents (e.g., a member area +on your website or a collaboration platform) that cannot be easily connected to +CiviCRM ## Features - -* Connect another (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 -* Allow participants to modify and/or cancel their own registrations -* Alternative approach for defining an event's location - -TODO: Complete Feature List ++ Connect a remote system to CiviCRM to handle highly customizable event +listings and registration features ++ Pre-defined registration profiles, including a "one-click registration" for +authenticated users ++ Use different registration profiles within the same event ++ Allow participants to modify or cancel their registrations ++ Alternative approach for defining an event's location ++ Event registration/update profiles configurable using a UI with the [Remote +Event Form Editor](https://github.com/systopia/remoteeventformeditor) extension ++ Manage sessions/workshops within your event ++ Register additional participants ++ Localize event registration profiles with a locale specified 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) -* 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) ++ PHP v7.0+ ++ CiviCRM 5.61 ++ Dependency on the CiviCRM Extension Remote Tools ++ Dependency on the CiviCRM Extension Extended Contact Matcher ++ A system to serve as your public interface, such as an external website + +## Extensions that Integrate with the Remote Event Extension ++ [Remote + Event Form Editor](https://github.com/systopia/remoteeventformeditor): +A drag-and-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 info@systopia.de to get an invoice or agree a different payment method. +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 invested a lot of work into it +(and continue to do so), much of it unpaid. 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 [info@systopia.de](mailto:info@systopia.de) to get an invoice or agree on +a different payment method. Thank you! + +This extension is licensed under +[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0). \ No newline at end of file diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..2fd30a2 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..3cf271e --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,65 @@ +## Configuration +After installing the extension, make sure your **Remote Tool settings** are +configured according to your needs (refer to the documentation provided in +[de.systopia.remotetools](https://github.com/systopia/de.systopia.remotetools)). +Then proceed with the general configuration: + +* Navigate to >>Administer >>CiviEvent >>Remote Events - General Configuration +(/civicrm/admin/remoteevent/settings). +* Define which participant status will block re-registration for your events +(e.g., rejected) and specify which roles you want to assign to speakers. +* Suppress workshop/session data if you do not use this feature. +* Select the activity type for changes in participation data. +* Configure the default matcher profile you would like to use (XCM-Extension). +If using registration updates, ensure the XCM profile has the *Match contacts by +contact ID* option activated to prevent duplicate contacts when updating event +registrations. +* Enter the URLs to be used for registrations, modifications, and cancellations, +depending on the external system you use. If you use the CiviRemote Drupal +module, you may use: + - `https://yourdomain.org/civiremote/event/update/{token}` + - `https://yourdomain.org/civiremote/event/cancel/{token}` + +After completing the general configuration, visit the new "Remote Online +Registration" tab within CiviCRM's event configuration UI. This tab provides +several options and settings under the "Online-Registration (CiviRemote)" and +"Workshops" sections. Notably, you can decide whether to use the remote event +features, disable native CiviCRM online registration, use alternative event +locations, or use external identification for your event. + +You will find two segments for registration profiles: one for initial +registration and another for editing registrations. The labels and help pop-ups +should provide sufficient information to understand your options. + +The "Registration Restrictions" section allows you to configure when +registration is available, whether a registration requires manual review, and if +participants can cancel or modify their own registrations. + +The "Additional Participants" feature allows you to add a group of people with a +single registration. This results in a form where the participant can add up to +9 additional participants using increase/decrease buttons. For these additional +participants, a separate form can be selected to collect only names and email +addresses, while the main participant provides more information. You can also +select a specific XCM configuration for contact matching. In the participation +overview, you can see who was added along with the main participant. + +The "Public Event Text Blocks" can be used by your external system to display +information at appropriate places during the registration process. How and when +this information is presented to your constituents depends on the design of your +external system. + +CiviCRM's other basic event settings still apply and may be used in your +external system, including title, descriptions, start and end dates, +maximum number of participants, waitlist settings, etc. + +### Alternative Event Location Settings +If the default event location feature is insufficient, you can choose to use the +alternative event location feature. If you do, CiviCRM's regular event location +tab will be hidden, and a custom tab will appear. In this custom tab, you can +choose a contact with the subtype "event location" (the subtype is created when +installing the extension). You can also provide specific information for the +event location, such as room number or travel instructions. + +The API will then make the chosen event location's basic data available, +including its name, address, geo data, and additional information for the event. +This information can be displayed and used by the external system. \ No newline at end of file diff --git a/docs/extensibility.md b/docs/extensibility.md new file mode 100644 index 0000000..910413a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 8181427..0430a5f 100644 --- a/mkdocs.yml +++ b/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