wip email prefs documentation

docs/email-preferences.md

@@ -32,6 +32,8 @@ In CiviCRM I will have a few groups:
 * a group called Monthy Actions
 * a group called Yearly Summary
 
+![Groups in CiviCRM](/images/emailprefs-groups.png)
+
 The email preferences should reflect this group membership:
 
 * if someone ticks the box *I do not want any general mails* the contact should be removed from all three groups
@@ -131,34 +133,61 @@ The first step is create a class in my extension extending the *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:
+The method *getParameterSpecification* determines the parameters I expect to receive in my class. This is the data that will be sent to my action from my form processor or from one of the previous actions.
+In this example I expect to get a contact ID as a parameter:
 
 ```php
-  /**
-   * @return SpecificationBag
-   */
-  public function getParameterSpecification() {
-    return new SpecificationBag();
-  }
+/**
+ * @return SpecificationBag
+ */
+public function getParameterSpecification() {
+  return new SpecificationBag([
+    new Specification('contact_id', 'Integer', E::ts('Contact ID'), TRUE)
+  ]);
+}
 ```
+The method *getConfigurationSpecification* determines what data I will output in my action.
+In this case this will be the flags that correspond to my group memberships and the fields on my form processor:
 
-If I would need a parameter, like say *email*, *first_name* and *last_name* it would like like this:
+```php
+/**
+ * @return SpecificationBag
+ */
+public function getConfigurationSpecification() {
+  return new SpecificationBag([
+    new Specification('newsletter_and_action', 'Boolean', E::ts('Monthly Newsletter and Monthly Action'), FALSE),
+    new Specification('newsletter_only', 'Boolean', E::ts('Monthly Newsletter Only'), FALSE),
+    new Specification('yearly_summary', 'Boolean', E::ts('Yearly Summary Only'), FALSE),
+    new Specification('no_general_mail', 'Boolean', E::ts('No General Mails'), FALSE),
+  ]);
+}
+```
+The method *doAction* actually performs my action, so in this case use the contact_id to retrieve the group memberships and set my booleans reflecting 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),
-		]);
-	}
+/**
+ * @param ParameterBagInterface $parameters
+ * @param ParameterBagInterface $output
+ * @throws InvalidParameterException
+ */
+public function doAction(ParameterBagInterface $parameters, ParameterBagInterface $output) {
+  $contactId = (int) $parameters->getParameter(['contact_id']);
+  if ($contactId) {
+    $contactGroups = $this->retrieveContactGroups($contactId);
+    $outputValues = $this->calculateOutputValues($contactGroups);
+    foreach ($outputValues as $key => $value) {
+      $output->setParameter($key, $value);
+    }
+  }
+  else {
+    throw new InvalidParameterException(E::ts("Could not find mandatory parameter contact_id"));
+  }
+}
 ```
+This is all that is needed for my action to get the email preferences.
+
+!!! Note "I want the rest too"
+    If you want to also see what the methods *retrieveContactGroups* and *calculateOutputValues* do, check the code on [My Email Prefs Code on Gitlab][myemailprefs]
 
 ## Develop my action to save the new email preferences
 
@@ -172,3 +201,4 @@ If I would need a parameter, like say *email*, *first_name* and *last_name* it w
 
 [dataprocessor]:https://civicrm.org/extensions/data-processor
 [aghchecksum]:https://aghstrategies.com/content/how-create-one-click-personalized-links-civicrm-emails
+[myemailprefs]:https://lab.civicrm.org/partners/civicoop/myemailprefs