Commit 20331e23 authored by ErikHommel's avatar ErikHommel 🏘
Browse files

wip documentation

parent 644ebf9a
# 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.
![Form Processors Page](/images/init-form.png)
## 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:
![New Form Processor](/images/new-processor.png)
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.
### General form processor information
In the top part of the form you can enter the general form processor information:
* have to specify a *title* for the form processor
* a *name* will be suggested based on the *title* but can be changed if you click on the lock behind the field first!
!!! Note
A *name* can not contain any spaces! And should be unique!
* you can specify a detailed description (and it makes sense to do so if you expect to build a few forms!)
* you can tick if the form processor should be enabled (on by default)
* you can select what permissions are required to be able to process the form. For example you could decide you can only send your address details if you have the *CiviCRM:edit my contact* permission.
It will look something like this:
![Top part of the form](/images/new_first.png)
### Input fields on your form processor
In the next part under the heading **Inputs** you can specify the input fields that should be on your form.
For each field you can select the type of field (short text, numeric no decimal, date, yes/no, option group etc.), specify a title for the input file and add validation if that is required. Let's for example take the first name, last name and email.
Adding the input field for the *email* will probably have to look like this:
![Input field for email](/images/new-input-email.png)
Once I have added all the fields (and as you can see I have added the validation that first and last name should at least have 3 characters) the list will look like this:
![List of input fields](/images/new-list-input-fields.png)
What I have done now is specify that I expect my form to show 3 fields for the website visitor to enter: First Name, Last Name and Email.
### Actions on your form processor
In the final part of the specification of a form processor you can specify what needs to happen once CiviCRM receives the data from the form.
We do that by adding *actions* to the form processor.
So in our example, we should find a contact by the email. Next the contact found should be added to the newsletter group.
Initially the part of the form where we can specify actions will look like this:
![Action part of the form](/images/new-action-part.png)
If you click on the action select box you will get a list of actions that are already available because some of the funding organizations needed that action.
As time goes by and more people start using and enhancing the [**Action Provider** extension][actionproviderrepo], the list will grow.
!!! Note "Create your own"
It is possible to develop your own specific actions, or indeed generic ones that others can use too! Check the relevant sections in [Example of Email Preferences](email-preferences.md)
In this example we have a first step: find the contact with the data from the form.
![Find contact action](/images/action-find-contact.png)
Once I have found the contact it should be added to the newsletter group.
If I select the *add to group* action I can select the group and specify that I want to use the contact ID found in the previous action:
![Add to newsletter group action](/images/action-add-to-group.png)
## New Form Processor - retrieval of defaults
With the **Form Processor** extension it is possible to pre-load your form with default data, for example for a *My Address Data* form.
We could pass a parameter (a checksum for example) in the URL of the form and based on that retrieve the current values from CiviCRM and prepopulate the form with this data.
This can be specified in the *Retrieval of defaults* tab. Once I have ticked the *Enable default data retrieval?* option I will see a form like this:
![New retrieval of defaults](/images/new-retrieval.png)
As you can see the input fields from my form processor have already been loaded.
I can specify here what criteria I want to use, in this example I have specified a short text named *checksum*.
At the *retrieval methods* part I can select how I want to retrieve my data.
Here I would like an action called *Find contact with checksum*. Unfortunately that is not available yet because it has not been developed yet, but you get the gist.
And it will be developed in the section [Email Preferences](email-preferences.md).
For each of my input fields I can finally specify what data should be loaded here, which should come from the result of my action.
!!! Note "Techie stuff"
On a technical level: If you have enabled default data retrieval it actually generates an API action for the FormProcessorDefaults API entity.
## Output Handler
At the bottom of the form where you edit or create your form processor there is also a bit about an *output handler*:
![Output Handler](/images/output-handler.png)
This gives you the option to manipulate the output that is sent back to the public website once all the actions have been executed.
If you do not specify anything, the default value of *send everything* then all the data involved is sent back (inputs, output from actions etc.).
If you decide for example you only want to send the ID of the contact back you can select the *decide what to send* and specify what from all the available data should be send back and how it is called.
## That's it!
If you click on the *Retrieval of defaults* tab in the **New Form Processor** form you will get a form like this:
And that is all! A form to be used without coding. Once I saved the form processor I can see at the top of the form what API action I can use:
![API to be used](/images/api-to-be-used.png)
So far the basic concept. Obviously the public website part needs to be done too, check the [Example Sign Up Newsletter](sign-up-newsletter.md) section for that part, this section just covers the basis principles.
[actionproviderrepo]:https://lab.civicrm.org/extensions/action-provider
# Introduction
**[Data Processor][dataprocessorrepo]** is an extension originally developed by [CiviCooP][civicoop], mainly funded by [Velt][velt], [Barnekreftforeningen][barnekreft], [NIHR BioResource][bioresource], [Civiservice.de][civiservice] and CiviCooP themselves.
The aim of the extension is to create an engine to quickly create data overviews without coding that can be used within CiviCRM but also outside of CiviCRM, like on the public website.
And without the requirement of having CiviCRM installed on the same server. So I could have my public website on server A and CiviCRM installed on server B and still show data from CiviCRM on my public website using the Data Processor extension.
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 **Data Processor** extension to communicate with a CiviCRM installation on the same server as the public website.
## Contents
This guide is an attempts to explain the basic concept of the **Data Processor** and a few examples on how to use the data processor.
In some examples other related extensions are required as well, we will mention that in the examples.
There are a few requirements to be able to get the full benefits of the **Data Processor** extension:
- [Requirements](requirements.md)
The basic concepts of the **Data Processor** are explained on:
- [Basic Concepts](basic-concept.md)
This guide also contains a few examples of use cases:
- [How to publish a list of contact name, country and website on the public website (Drupal 8 website)](usecase1.md)
## CiviCRM versions
The **Data Processor** extension has initially been developed with CiviCRM 4.7 and has been tested with CiviCRM 5.x on various sites.
!!! Note
If you want the **Data 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 theme][shoreditch].
[civicoop]: http://www.civicoop.org/
[velt]:https://velt.be/
[barnekreft]:https://www.barnekreftforeningen.no/
[civiservice]:https://civiservice.de/
[bioresource]:https://bioresource.nihr.ac.uk/
[cmrf-repo]:https://github.com/CiviMRF
[dataprocessorrepo]:https://lab.civicrm.org/extensions/dataprocessor
[mattermost]:https://chat.civicrm.org/civicrm/
[shoreditch]:https://civicrm.org/extensions/shoreditch
# 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/
site_name: Data Processor
repo_url: https://lab.civicrm.org/extensions/dataprocessor
theme:
name: material
nav:
- Introduction: index.md
- Requirements: requirements.md
- Basic Concept: basic-concept.md
- How to create:
- Website overview of contact, country and website from CiviCRM: usecase1.md
- Blabla: usercase2.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
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