diff --git a/docs/create-your-own-introduction.md b/docs/create-your-own-introduction.md index 3e9ef1a554662ffd61bec836d0e3f37606558bff..57882f9b5be98c21e7a57f9c72734b192bfea33c 100644 --- a/docs/create-your-own-introduction.md +++ b/docs/create-your-own-introduction.md @@ -1 +1,15 @@ # 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 diff --git a/docs/email-preferences.md b/docs/email-preferences.md index 34690b893807c3fad002e576d2138b08a3374572..b32310b76398a489b376aabf482453df0bfde00d 100644 --- a/docs/email-preferences.md +++ b/docs/email-preferences.md @@ -1,3 +1,61 @@ # 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: + + + +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 diff --git a/docs/index.md b/docs/index.md index 458ed5b4d6c0c8d09bd525983b7b5e3f432c6928..5fb6f2ec63c183d82886e984e31002c1ed453c03 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/sign-up-newsletter.md b/docs/sign-up-newsletter.md index 3681ec2e45263fb87e51236d345868f66461a5f2..d6cdfedf8ebba966a7ba27d71e53bc4f145c8029 100644 --- a/docs/sign-up-newsletter.md +++ b/docs/sign-up-newsletter.md @@ -1 +1,116 @@ # 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: + + + +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?). + + + +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: + + + +The action to find or create the contact has been specified so: + + + +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. + + + +## 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: + + + +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): + + + +Once I have installed the CiviMRF modules I can specify a so called CMRF Profile from the Drupal Configuration menu: + +. + +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]). + + + +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: + + + +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: + + + +### 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: + + + +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. + + + +### 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 :-): + + + +## Result! + +If I now enter data in my form as you can see here: + + + +The result in CiviCRM will be that a contact is created and he is added to the newsletter group: + + + + + +[sitekey]:https://docs.civicrm.org/sysadmin/en/latest/setup/site-key/ +[apikey]:https://civicrm.stackexchange.com/questions/31092/where-is-the-api-key diff --git a/images/emailprefs-mockup.png b/images/emailprefs-mockup.png new file mode 100644 index 0000000000000000000000000000000000000000..767711f51ec6781a4933548f2ade260fca7d44ad Binary files /dev/null and b/images/emailprefs-mockup.png differ diff --git a/images/newsletter-actions-fp.png b/images/newsletter-actions-fp.png new file mode 100644 index 0000000000000000000000000000000000000000..5c17ab849b53375ba19ac0ceb4296a457543eda8 Binary files /dev/null and b/images/newsletter-actions-fp.png differ diff --git a/images/newsletter-api-test.png b/images/newsletter-api-test.png new file mode 100644 index 0000000000000000000000000000000000000000..7b4290875f6b1c2eb9965ae48dbefa565e367928 Binary files /dev/null and b/images/newsletter-api-test.png differ diff --git a/images/newsletter-cmrf-menu.png b/images/newsletter-cmrf-menu.png new file mode 100644 index 0000000000000000000000000000000000000000..b211bee04f5e36fa36f6fa6c1d296d2fe69dab1e Binary files /dev/null and b/images/newsletter-cmrf-menu.png differ diff --git a/images/newsletter-cmrf-modules.png b/images/newsletter-cmrf-modules.png new file mode 100644 index 0000000000000000000000000000000000000000..01bccc9ce8a42618cbd4c0a48eec53f62620a349 Binary files /dev/null and b/images/newsletter-cmrf-modules.png differ diff --git a/images/newsletter-cmrf-profile.png b/images/newsletter-cmrf-profile.png new file mode 100644 index 0000000000000000000000000000000000000000..d755e25e34f08515e35629832c93fa5c119725c3 Binary files /dev/null and b/images/newsletter-cmrf-profile.png differ diff --git a/images/newsletter-empty-form.png b/images/newsletter-empty-form.png new file mode 100644 index 0000000000000000000000000000000000000000..1f6c2de4571e50443ae56dd6d4e56e495e470d27 Binary files /dev/null and b/images/newsletter-empty-form.png differ diff --git a/images/newsletter-find-action.png b/images/newsletter-find-action.png new file mode 100644 index 0000000000000000000000000000000000000000..fd4c587088319c618d2a0c0d30fd8d2b93b01374 Binary files /dev/null and b/images/newsletter-find-action.png differ diff --git a/images/newsletter-form-cmrf-part.png b/images/newsletter-form-cmrf-part.png new file mode 100644 index 0000000000000000000000000000000000000000..e61e63f4632359f7163df8769fd5af47934dba9d Binary files /dev/null and b/images/newsletter-form-cmrf-part.png differ diff --git a/images/newsletter-form-components.png b/images/newsletter-form-components.png new file mode 100644 index 0000000000000000000000000000000000000000..61f4acc9846e98bce04e6baf7195c08e2a4cf5cf Binary files /dev/null and b/images/newsletter-form-components.png differ diff --git a/images/newsletter-form-fields-message.png b/images/newsletter-form-fields-message.png new file mode 100644 index 0000000000000000000000000000000000000000..ceea49bc8e4e6be1a0cff315fc97afab859ce073 Binary files /dev/null and b/images/newsletter-form-fields-message.png differ diff --git a/images/newsletter-form.png b/images/newsletter-form.png new file mode 100644 index 0000000000000000000000000000000000000000..00e0448041c4d3e697d1e5f049b4b155ec92b3b4 Binary files /dev/null and b/images/newsletter-form.png differ diff --git a/images/newsletter-general-fp.png b/images/newsletter-general-fp.png new file mode 100644 index 0000000000000000000000000000000000000000..8734e31dd8f9959a5f3a71367fa5fed07f509575 Binary files /dev/null and b/images/newsletter-general-fp.png differ diff --git a/images/newsletter-group-action.png b/images/newsletter-group-action.png new file mode 100644 index 0000000000000000000000000000000000000000..466bf2e12dca876dc09e2a95c21bbce83e3bf7f9 Binary files /dev/null and b/images/newsletter-group-action.png differ diff --git a/images/newsletter-inputs-fp.png b/images/newsletter-inputs-fp.png new file mode 100644 index 0000000000000000000000000000000000000000..c283832c591c8a0d5edf4a317e34997ad325343f Binary files /dev/null and b/images/newsletter-inputs-fp.png differ diff --git a/images/newsletter-jd-civi1.png b/images/newsletter-jd-civi1.png new file mode 100644 index 0000000000000000000000000000000000000000..e0ef6cd952060e2615b5496e70290bd0980cec42 Binary files /dev/null and b/images/newsletter-jd-civi1.png differ diff --git a/images/newsletter-jd-civi2.png b/images/newsletter-jd-civi2.png new file mode 100644 index 0000000000000000000000000000000000000000..3148619c325d3ac92e0c77256b1bc4aee93f327d Binary files /dev/null and b/images/newsletter-jd-civi2.png differ diff --git a/images/newsletter-jd-form.png b/images/newsletter-jd-form.png new file mode 100644 index 0000000000000000000000000000000000000000..ede2802cf833be3b88ae98e3b774f2c546399646 Binary files /dev/null and b/images/newsletter-jd-form.png differ diff --git a/images/output-handler.png b/images/output-handler.png index f33be24589c82f3c7c61de166afd10431bea489b..07a7cc297b3d0a0fdda83faa117167fbc115ea8f 100644 Binary files a/images/output-handler.png and b/images/output-handler.png differ