Commit 653a5998 authored by ErikHommel's avatar ErikHommel

wip documentation email prefs

parent a2586e5d
# Example of email preferences form # Example of Email Preferences form
As the combination of the **Form Processor** extension and the **Action Provider** extension really is a framework it is relatively easy to develop your own actions. As the combination of the **Form Processor** extension and the **Action Provider** extension really is a framework it is relatively easy to develop your own actions.
This could be necessary because: This could be necessary because:
* the current set of actions is limited to what we needed initially and it could well be that you need an action that is not there but will be very useful to others as well. * the current set of actions is limited to what we needed initially and it could well be that you need an action that is not there but will be very useful to others as well.
This probably means you want to develop a new action in the **Action Provider** extension (with a pull request). This probably means you want to develop a new action in the **Action Provider** extension (with a pull request).
...@@ -18,7 +19,7 @@ This example includes developing specific *action* and *retrieval criteria*. ...@@ -18,7 +19,7 @@ This example includes developing specific *action* and *retrieval criteria*.
I would like to have a form on my website where a contact can specify his or her email preferences. I would like to have a form on my website where a contact can specify his or her email preferences.
The idea is that we include a link in each mailing or mail we send out with a checksum (see the wonderful [AGH Strategies Email Link Guide][aghcheckusm]). The idea is that we include a link in each mailing or mail we send out with a checksum (see the wonderful [AGH Strategies Email Link Guide][aghchecksum]).
This link should lead to the form (prefilled if we know the person) which should look like this: This link should lead to the form (prefilled if we know the person) which should look like this:
![Mockup Form](/images/emailprefs-mockup.png) ![Mockup Form](/images/emailprefs-mockup.png)
...@@ -45,7 +46,119 @@ The same rules apply when retrieving the current preferences. ...@@ -45,7 +46,119 @@ The same rules apply when retrieving the current preferences.
## What do I need to do? ## What do I need to do?
## Develop my action to retrieve the current email preferences Linking the tick boxes on the form to the group memberships in CiviCRM is a very specific thing. It is unlikely that exactly the same set up will be used by more organizations, so in this case I have elected to create a new specific extension for these actions, which can then be used by the **Form Processor** on this specific CiviCRM installation.
In this extension I will develop:
1. An action to retrieve the current group membership and translate that into defaults for my yes/no fields on my form processor
1. An action to process the submitted yes/no fields on the form processor into group membership in CiviCRM.
I can then specify a form processor for this form using my new actions, and create a form.
## Create the extension, folders and info.xml
I have created the extension myemailprefs. In this extension I will now add a folder *Civi* and within that folder the folder *Action*.
This is not required, but it reflects the structure of CiviCRM and the structure of the **Action Provider** extension and I like to adhere to those :-)
In the *Action* folder I can add my actions if I only expect to have a couple, or add a folder for each entity and then add my actions in there.
Because this extension for now will only hold 2 actions I will put them in the *Action* folder.
![Extension folders](/images/emailprefs-folders.png)
Next I have updated my info.xml, most of the information is not too important for this example but the <**classloader**> tag is!
This is required for an extension that creates *actions* for the **Action Provider**.
On top of that the <**required**> tag also makes sense in this context as the extension will not work without the **Action Provider** extension and the relevant classes that we are using will not be present.
```xml
<?xml version="1.0"?>
<extension key="myemailprefs" type="module">
<file>myemailprefs</file>
<name>My Email Preferences - CiviCRM specific actions (Action Provider)</name>
<description>CiviCRM extension for documentation purposes - example actions</description>
<license>AGPL-3.0</license>
<maintainer>
<author>Erik Hommel (CiviCooP)</author>
<email>erik.hommel@civicoop.org</email>
</maintainer>
<urls>
<url desc="Main Extension Page">https://lab.civicrm.org/partners/civicoop/myemailprefs</url>
<url desc="Documentation">https://lab.civicrm.org/partners/civicoop/myemailprefs</url>
<url desc="Support">https://civicoop.org</url>
<url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
</urls>
<releaseDate>2020-01-08</releaseDate>
<version>1.0</version>
<develStage>beta</develStage>
<compatibility>
<ver>5.19</ver>
</compatibility>
<requires>
<ext>action-provider</ext>
</requires>
<classloader>
<psr4 prefix="Civi\" path="Civi" />
</classloader>
<comments>Extension is for documentation purposes</comments>
<civix>
<namespace>CRM/Myemailprefs</namespace>
</civix>
</extension>
```
##Develop my action to retrieve the current email preferences
Next step is to develop my action that will retrieve the current email preferences.
In this action I expect to receive a contact ID, and I will then collect the group membership for the contact and set the yes/no fields accordingly.
The first step is create a class in my extension extending the *AbstractAction* class from the **Action Provider**. This will initially have to look like this:
````php
<?php
namespace Civi\Myemailprefs\Action;
use \Civi\ActionProvider\Action\AbstractAction;
use \Civi\ActionProvider\Parameter\ParameterBagInterface;
use \Civi\ActionProvider\Parameter\SpecificationBag;
use \Civi\ActionProvider\Parameter\Specification;
use CRM_Myemailprefs_ExtensionUtil as E;
class GetEmailPrefs extends AbstractAction {
}
````
Next step is to specify the required methods *getParameterSpecification*, *getConfigurationSpecification* and *doAction*.
The method *getParameterSpecification* determines the parameters I will be able to specify in my action form. For example, if I use the *Find or Create Contact by Email* action, I can (and have to) specify the contact type. This is a parameter.
In this case I do not need any parameters so I simply add this to my class:
```php
/**
* @return SpecificationBag
*/
public function getParameterSpecification() {
return new SpecificationBag();
}
```
If I would need a parameter, like say *email*, *first_name* and *last_name* it would like like this:
```php
/**
* Returns the specification of the parameters of the actual action.
*
* @return SpecificationBag
*/
public function getParameterSpecification() {
return new SpecificationBag([
new Specification('email', 'String', E::ts('E-mail'), TRUE),
new Specification('first_name', 'String', E::ts('First Name'), TRUE),
new Specification('last_name', 'String', E::ts('Last Name'), TRUE),
]);
}
```
## Develop my action to save the new email preferences ## Develop my action to save the new email preferences
......
...@@ -30,6 +30,8 @@ The action to find or create the contact has been specified so: ...@@ -30,6 +30,8 @@ The action to find or create the contact has been specified so:
![Action to Find or Create Contact](/images/newsletter-find-action.png) ![Action to Find or Create Contact](/images/newsletter-find-action.png)
So this action tries to find a contact with the email provided. If no contact with the email can be found, it uses the email and the first/last name to create a contact.
Finally in the action to add the contact to the group I have selected the group the contact should be added to and specified that the contact ID found in the find action should be used. Finally in the action to add the contact to the group I have selected the group the contact should be added to and specified that the contact ID found in the find action should be used.
![Action to Add to Group](/images/newsletter-group-action.png) ![Action to Add to Group](/images/newsletter-group-action.png)
......
...@@ -7,7 +7,6 @@ pages: ...@@ -7,7 +7,6 @@ pages:
- Requirements: requirements.md - Requirements: requirements.md
- Basic Concept: basic-concept.md - Basic Concept: basic-concept.md
- How to make your own: - How to make your own:
- Introduction: create-your-own-introduction.md
- Sign Up for Newsletter: sign-up-newsletter.md - Sign Up for Newsletter: sign-up-newsletter.md
- Your Email Preferences: email-preferences.md - Your Email Preferences: email-preferences.md
......
Markdown is supported
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