Merge branch 'master' of lab.civicrm.org:extensions/form-processor

docs/create-your-own-introduction.md

 # Create Your Own
+
+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:
+* 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).
+
+* you need to develop a very specific action which is only meaningful for the organisation/project you are working with.
+In this case you will probably create your specific action in your own extension.
+
+!!! Note
+    The **Action Provider** is a separate extension rather than part of the **Form Processor** because it can also be used by other extensions (at the moment the [Data Processor extension][dataprocessor]).
+
+[dataprocessor]:https://civicrm.org/extensions/data-processor

docs/email-preferences.md

 # 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.
+
+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.
+This probably means you want to develop a new action in the **Action Provider** extension (with a pull request).
+
+* you need to develop a very specific action which is only meaningful for the organisation/project you are working with.
+In this case you will probably create your specific action in your own extension.
+
+!!! Note
+    The **Action Provider** is a separate extension rather than part of the **Form Processor** because it can also be used by other extensions (at the moment the [Data Processor extension][dataprocessor]).
+
 This example includes developing specific *action* and *retrieval criteria*.
+
+## What result do I want?
+
+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]).
+This link should lead to the form (prefilled if we know the person) which should look like this:
+
+![Mockup Form](/images/emailprefs-mockup.png)
+
+Once the person has ticked all their boxes the result should be processed into CiviCRM.
+
+In CiviCRM I will have a few groups:
+
+* a group called Monthly Newsletter
+* a group called Monthy Actions
+* a group called Yearly Summary
+
+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
+* if someone ticks the box *I would only like to receive the yearly summary* the contact should be removed (if a member) from the groups **Monthly Newsletter** and **Monthly Actions** and added (if not a member already) to the group **Yearly Summary**.
+* if someone ticks the box *I would only like to receive the monthy newsletter* the contact should be removed (if a member) from the groups **Monthly Actions** and **Yearly Summary** and added (if not a member already) to **Monthly Newsletter**
+* if someone ticks the box *I would like to receive the monthly newsletter and the monthly action summary* the contact should be removed (if a member) from the group **Yearly Summary** and added to (if not a member already) to the groups **Monthly Actions** and **Monthly Newsletter**
+
+The same rules apply when retrieving the current preferences.
+
+!!! Note
+    The assumption is that the form will be developed in such a way that I can not receive conflicting ticks!
+
+## What do I need to do?
+
+## Develop my action to retrieve the current email preferences
+
+## Develop my action to save the new email preferences
+
+## Add my actions to the Action Provider
+
+## Set up the form processor
+
+## Set up the form
+
+## Result!
+
+[dataprocessor]:https://civicrm.org/extensions/data-processor
+[aghchecksum]:https://aghstrategies.com/content/how-create-one-click-personalized-links-civicrm-emails

docs/index.md

@@ -29,9 +29,10 @@ The basic concepts of the **Form Processor** are explained on:
 In this guide you will also find an example to set up forms with the **Form Processor** without coding and an example how to develop your own *actions* and *retrieval criteria*, as well as an introduction on how to create your own:
 
 - [How to create a basic form to sign up for a newsletter](sign-up-newsletter.md)
-- [Introduction to creating your own](create-your-own-introduction.md)
 - [How to create a form for your email preferences](email-preferences.md)
 
+The latter How To will give you an example of how to develop your own actions!
+
 ## CiviCRM versions
 
 The **Form Processor** extension has initially been developed with CiviCRM 4.7.4 and has been tested with CiviCRM 5.x on various sites.

docs/sign-up-newsletter.md

 # Example of a basic form to sign up for a newsletter
+
+This example details how to create a form on my public website where a visitor can enter *first name, last name and email* and click to sign up for our monhtly newsletter.
+The **Form Processor** extension will make sure this is processed in the CiviCRM backend.
+
+The public website is on another server than CiviCRM and I am using Drupal 7 on my public website example.
+
+## Defining the form processor
+
+The general information for my form processor looks like this:
+
+![Form Processor General](/images/newsletter-general-fp.png)
+
+On my form processor I will accept 3 inputs: first name, last name and email.
+The email will be validated (is it a valid email?).
+
+![Form Processor Inputs](/images/newsletter-inputs-fp.png)
+
+Once the form is sent from the public website I would like the following to happen:
+
+* check if we already have a contact with the email entered and if so, use that contact
+* if there is no contact with the email yet, create a new contact with the email, first and last name from the form
+* add the found or created contact to our newsletter group
+
+So here is what the actions look like:
+
+![Form Processor Actions](/images/newsletter-actions-fp.png)
+
+The action to find or create the contact has been specified so:
+
+![Action to Find or Create Contact](/images/newsletter-find-action.png)
+
+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)
+
+## Testing the form processor with the api explorer
+
+Once I have specified my form processor I can test if it works as I would expect.
+The form processor generates an API action for the API entity FormProcessor so I can use the API Explorer (Support>Developer>Api Explorer v3) to test if it works.
+
+In this case this is what I will enter:
+
+![Test with API Explorer](/images/newsletter-api-test.png)
+
+And if I then click on **Execute** it should actually add or find the contact and add him/her to the newsletter group.
+
+## Defining the form in Drupal 7
+
+I now need to design a form on my public website that communicates with my form processor. In this example I use Drupal 7.
+
+### CiviMRF profile
+
+To be able to communicate with a CiviCRM installation on another server the **CMRF core** module is installed, and I have also enabled the **CRMF Webform** module and the **CMRF Form Processor** module (see the [Requirements](requirements.md) section):
+
+![CiviMRF modules](/images/newsletter-cmrf-modules.png)
+
+Once I have installed the CiviMRF modules I can specify a so called CMRF Profile from the Drupal Configuration menu:
+
+![CiviMRF Profile Menu](/images/newsletter-cmrf-menu.png).
+
+From this menu I can edit or add a CiviMRF profile. In this profile I specify if my connection with CiviCRM is remote (on another server) or local (the same server).
+In this example it is remote, I have specified the URL to the REST interface of CiviCRM and added the site and API keys.
+
+!!! Note "Site and API keys"
+    (for background information check [System Administrator Guide on Site Key][sitekey] and [StackExchange on API key][apikey]).
+
+![CiviMRF Profile](/images/newsletter-cmrf-profile.png)
+
+Once I have done this I have configured how this profile connects to my CiviCRM installation.
+
+!!! Note
+    Expect to have a profile for each CiviCRM installation you want to connect to. This is probably only one in most cases.
+
+### CiviMRF for the form
+
+I am now going to create my form in Drupal by clicking *Add content*, then select *Webform* and finally add a name for my webform and hit the *Save* button.
+Once I have done this I will see my new form like this:
+
+![New empty form](/images/newsletter-empty-form.png)
+
+To specify that I am going to use the CiviMRF profile with this form so it can communicate with the **Form Processor** I will now click on the **CiviMRF** tab and select *Submit to CiviCRM Form Processor*.
+In the form I can select what *CiviMRF profile* I want to use and what *Form Processor* I want to use:
+
+![CiviMRF part of the form](/images/newsletter-form-cmrf-part.png)
+
+### Adding the fields on the form
+
+Once I have hit *Save* I will go back to the *Form components* tab but I will now see a message warning me that I have not yet included fields from the Form Processor:
+
+![Form components message](/images/newsletter-form-fields-message.png)
+
+Next step is to add all the fields I want to be on my form. In my example I have only included the ones from my form processor but you could add whatever you want additionally, just remember this will not be sent to CiviCRM.
+
+![Form components](/images/newsletter-form-components.png)
+
+### The end result of the form
+
+I have also updated the text for my submit button, and the resulting form will look like this (I am not a styling guru :-):
+
+![Resulting form](/images/newsletter-form.png)
+
+## Result!
+
+If I now enter data in my form as you can see here:
+
+![Form for John Doe](/images/newsletter-jd-form.png)
+
+The result in CiviCRM will be that a contact is created and he is added to the newsletter group:
+
+![CiviCRM John Doe](/images/newsletter-jd-civi1.png)
+
+![CiviCRM John Doe](/images/newsletter-jd-civi2.png)
+
+[sitekey]:https://docs.civicrm.org/sysadmin/en/latest/setup/site-key/
+[apikey]:https://civicrm.stackexchange.com/questions/31092/where-is-the-api-key