diff --git a/docs/basic-concept.md b/docs/basic-concept.md new file mode 100644 index 0000000000000000000000000000000000000000..ea3642d531096efeaa6b2e16638a98c453586dc0 --- /dev/null +++ b/docs/basic-concept.md @@ -0,0 +1,41 @@ +# Basic Concept of the Form Processor Extension + +The **Form Processor** extension allows you to specify the data that will be processed with a form on your public website. +In CiviCRM you specify what data you want to display on the form, if and what default values you want to load and what should happen with the data that is submitted with the form. + +For example: I want a form that allows me to enter my name and email address so I can sign up for the newsletter. +You can specify all that in the **Form Processor** and also specify that a new contact should be created if one can not be found with the email address, and that the contact found or created should be added to the newsletter group in CiviCRM. + +In this chapter we will briefly discuss the forms and screens you need to go through if you are specifying a form with the **Form Processor**. + +!!! Note "Techie stuff" + On a technical level: the extension actually generates an API action for the FormProcessor API entity. + +## Form Processors Page + +Once you installed the **Form Processor** extension you will have an additional option in the **Administer>Automation>Form processors** option which will lead you the the first view of all the form processors in your installation. +This will be empty if you just installed the extension. + + + +## New Form Processor - define form processor +On this page you can click on the **New Form Processor** button to create a new form processor. If you do this you will see a form like the one below: + + + +On the top of the form you can see that there are **two** tabs: + +1. the *Define form processor* tab, which you will see if you start. +On this tab you specify generic information about your form, the inputs on your form (with defaults values and/or validation if you want to) and what should happen in CiviCRM with the data from the form once it has been submitted. +1. the *Retrieval of defaults* tab. On this tab you can specify what defaults should be loaded in your form. We will discuss this in the next section. + +In this section we will deal with the *define form processor* tab. + + +## New Form Processor - retrieval of defaults + +If you click on the *Retrieval of defaults* tab in the **New Form Processor** form you will get a form like this: + + + + diff --git a/docs/create-your-own-introduction.md b/docs/create-your-own-introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..3e9ef1a554662ffd61bec836d0e3f37606558bff --- /dev/null +++ b/docs/create-your-own-introduction.md @@ -0,0 +1 @@ +# Create Your Own diff --git a/docs/email-preferences.md b/docs/email-preferences.md new file mode 100644 index 0000000000000000000000000000000000000000..34690b893807c3fad002e576d2138b08a3374572 --- /dev/null +++ b/docs/email-preferences.md @@ -0,0 +1,3 @@ +# Example of email preferences form + +This example includes developing specific *action* and *retrieval criteria*. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000000000000000000000000000000000..d4208724924f047f6ed83cf2cc781de88f292fc6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,54 @@ +# Introduction + +**[Form Processor][formprocessorrepo]** is an extension originally developed by [CiviCooP][civicoop], mainly funded by [Roparun][roparun], [Velt][velt], [Barnekreftforeningen][barnekreft] and CiviCooP themselves. + +The aim of the extension is to create a _framework_ to enable swift development (increasingly without coding) of forms that are used on the public website and communicate with CiviCRM. + +The configuration we had in mind when developing is a CiviCRM installation on a different server than the public website and communication with CiviCRM using the CiviMRF framework (see [the CiviMRF GitHub repo][cmrf-repo]). + +!!! Note "About CiviMRF" + **CiviMRF** is a framework that enables communication between a public website and CiviCRM on a separate server. It contains a generic core, a Drupal 7 specific implementation, a Wordpress specific implementation, a Drupal 8 specific implementation etc. + +This is not required, you can just as well use the **Form Processor** extension to communicate with a CiviCRM installation on the same server as the public website. + + +## Contents + +This guide is a first attempt to explain the basic concept of the **Form Processor** and a few examples on how to use the form processor. + +Actually we should mention here that it is the combination of the **Form Processor** extension _and_ the **Action Provider** extension (see [Action Provider extension][actionproviderrepo]) in combination that provide the framework. The **Action Provider** provides predefined *actions* that can be used to do stuff in CiviCRM with the data entered on the form, or *retrieval methods* to provide default data to the form. + +There are a few requirements to be able to get the full benefits of the **Form Processor** extension: + +- [Requirements](requirements.md) + +The basic concepts of the **Form Processor** are explained on: + +- [Basic Concepts](basic-concept.md) + +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) + +## 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. + +!!! Note + If you want the **Form Processor** updated to a newer version you can do so. Alternatively, if you want us to do it and have some funding, contact Jaap Jansma (<jaap.jansma@civicoop.org>) or Erik Hommel(<erik.hommel@civicoop.org>). You can also find them on the [CiviCRM Mattermost Channel][mattermost] using the handles **jaapjansma** or **ehommel**. + +## Screen prints + +In this guide you will find a number of screenshots. These were all taken from an installation with the [Shoreditch extension][shoreditch]. + +[civicoop]: http://www.civicoop.org/ +[roparun]:https://www.roparun.nl/en/ +[velt]:https://velt.be/ +[barnekreft]:https://www.barnekreftforeningen.no/ +[cmrf-repo]:https://github.com/CiviMRF +[actionproviderrepo]:https://lab.civicrm.org/extensions/action-provider +[formprocessorrepo]:https://lab.civicrm.org/extensions/form-processor +[mattermost]:https://chat.civicrm.org/civicrm/ +[shoreditch]:https://civicrm.org/extensions/shoreditch diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000000000000000000000000000000000000..751d4b682f549a682528fcfe0ebcbdae28b17dd5 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,58 @@ +# Requirements + +The **Form Processor** extension was developed with CiviCRM on a separate server than the public website in mind. + +There are some requirements on the CiviCRM side and some requirements on the public website side to be able to use the **Form Processor**. + +## Requirements on the CiviCRM side + +1. The **Form Processor** extension has to be active (see [Form Processor on Gitlab][formprocessorrepo]) +1. The **Action Provider** extension has to be active (see [Action Provider on Gitlab][actionproviderrepo]) + +## Requirements on the public website side + +As mentioned we assume that CiviCRM is on another server than the public website. + +The **CiviMRF** framework is used to communicate with CiviCRM from the public website. **CiviMRF** is a *CMS agnostic* framework that could be used on any CMS in theory. +In reality there are **CiviMRF** implementations for Drupal 7, Drupal 8 and Wordpress. +So at the time we are writing this documentation you can use the **Form Processor** in combination with a Wordpress, Drupal 7 or Drupal 8 public website sitting on another server. + +### Requirements for Drupal 7 + +This configuration has been used most at the moment of writing. + +1. The Webform module - [Webform][webform] +1. The CiviMRF Core and CiviMRF webform module - [CMRF core][cmrfcore] contains both +1. The CiviMRF Form Processor module - [CRMF Form Processor][cmrfformprocessor] + +## Requirements for Drupal 8 + +1. The Webform module - [Webform][webform] +1. The CiviMRF Core and CiviMRF webform module - [CMRF core][cmrfcore8] - this is still in development! + +!!! Note + The CiviMRF Form Processor is not available yet for Drupal 8. Feel free to develop this, or if you want to fund the development by [CiviCooP][civicoop], contact Jaap Jansma (<jaap.jansma@civicoop.org> or using the handle **jaapjansma** on the [CiviCRM Mattermost Channel][mattermost]). + +## Requirements for Wordpress + +1. The plugin Contact Form 7 - [Contact Form 7][contactform7] +1. The plugin Contact Form 7 CiviCRM Integration - [Contact Form 7 CiviCRM][contactform7civi] + +!!! Note + Mikey O'Toole (<mikey@mjco.uk>) has a fair amount of experience with using the **Form Processor** in combination with a Wordpress public website. You can find him on the [CiviCRM Mattermost Channel][mattermost] using the handle **mikeymjco**. + +## Any other CMS + +If you do want to use any other CMS for your public website you can certainly do so but if you want to use the Form Processor you would have to develop a CMS specific implementation of the CiviMRF framework. If you want to know more about this you can contact either [CiviCooP][civicoop] or [Systopia][systopia]. + +[actionproviderrepo]:https://lab.civicrm.org/extensions/action-provider +[formprocessorrepo]:https://lab.civicrm.org/extensions/form-processor +[civicoop]:https://civicoop.org/ +[systopia]:https://www.systopia.de/ +[webform]:https://www.drupal.org/project/webform +[cmrfcore]:https://github.com/CiviMRF/cmrf_core/releases +[cmrfformprocessor]:https://github.com/CiviMRF/cmrf_form_processor/releases +[cmrfcore8]:https://lab.civicrm.org/frontkom/cmrf_core_d8 +[contactform7]:https://wordpress.org/plugins/contact-form-7/ +[contactform7civi]:https://wordpress.org/plugins/contact-form-7-civicrm-integration/ +[mattermost]:https://chat.civicrm.org/civicrm/ diff --git a/docs/sign-up-newsletter.md b/docs/sign-up-newsletter.md new file mode 100644 index 0000000000000000000000000000000000000000..3681ec2e45263fb87e51236d345868f66461a5f2 --- /dev/null +++ b/docs/sign-up-newsletter.md @@ -0,0 +1 @@ +# Example of a basic form to sign up for a newsletter diff --git a/images/init-form.png b/images/init-form.png new file mode 100644 index 0000000000000000000000000000000000000000..10fa8585e60edb045f95210fc9891cf816ff2689 Binary files /dev/null and b/images/init-form.png differ diff --git a/images/new-processor.png b/images/new-processor.png new file mode 100644 index 0000000000000000000000000000000000000000..61775c9775c7c40b2b1492c2b0657ff10a665953 Binary files /dev/null and b/images/new-processor.png differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000000000000000000000000000000000..f62dc8eb51b455a1679837dc77ade7a6e031d0da --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,33 @@ +site_name: Form Processor +repo_url: https://lab.civicrm.org/extensions/form-processor +theme: material + +pages: +- Introduction: index.md +- Requirements: requirements.md +- Basic Concept: basic-concept.md +- How to make your own: + - Introduction: create-your-own-introduction.md + - Sign Up for Newsletter: sign-up-newsletter.md + - Your Email Preferences: email-preferences.md + +markdown_extensions: + - attr_list + - admonition + - def_list + - toc: + permalink: true + - pymdownx.highlight: + guess_lang: true + extend_pygments_lang: + - name: php + lang: php + options: + startinline: true + - pymdownx.superfences: + css_class: codehilite + - pymdownx.inlinehilite: + css_class: codehilite + - pymdownx.tilde + - pymdownx.betterem + - pymdownx.mark