diff --git a/docs/basic-concept.md b/docs/basic-concept.md index 8b2ce72653cef09413d89b2f7f9e3b2dea87220c..b87932ac6799f5ce88ebe29af47ad57f4e65f579 100644 --- a/docs/basic-concept.md +++ b/docs/basic-concept.md @@ -37,27 +37,88 @@ 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! + * 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: +  ### 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. Let's for example take the first name, last name and emailaddress: +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. -!!! Note - A *name* can not contain any spaces! +Adding the input field for the *email* will probably have to look like this: + + + +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: + + + +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: + + +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, 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 this guide: + * [Introduction to creating your own][create-your-own-introduction.md] + * [Example of Email Preferences][email-preferences.md] + +In this example we have a first step: find the contact with the data from the form: + + + +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: + + ## 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: + + + +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. + +## 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: + + + +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. + diff --git a/images/action-add-to-group.png b/images/action-add-to-group.png new file mode 100644 index 0000000000000000000000000000000000000000..42949eab16d9bcb1e7a04a38932a06a93eb98b60 Binary files /dev/null and b/images/action-add-to-group.png differ diff --git a/images/action-find-contact.png b/images/action-find-contact.png new file mode 100644 index 0000000000000000000000000000000000000000..8f4b7a4c5c7cc5b84483430054fb14f7d689f2b5 Binary files /dev/null and b/images/action-find-contact.png differ diff --git a/images/api-to-be-used.png b/images/api-to-be-used.png new file mode 100644 index 0000000000000000000000000000000000000000..0dccd3eee833b321c3cf1b9dc8535b68114132f3 Binary files /dev/null and b/images/api-to-be-used.png differ diff --git a/images/new-action-part.png b/images/new-action-part.png new file mode 100644 index 0000000000000000000000000000000000000000..82a19d042d08eaba04641dfd28dfa0c6a7cbefe9 Binary files /dev/null and b/images/new-action-part.png differ diff --git a/images/new-input-email.png b/images/new-input-email.png new file mode 100644 index 0000000000000000000000000000000000000000..d998541a4929712b856739a51bf81c458055eec6 Binary files /dev/null and b/images/new-input-email.png differ diff --git a/images/new-list-input-fields.png b/images/new-list-input-fields.png new file mode 100644 index 0000000000000000000000000000000000000000..3eaa5b4f7b46f0e9d5ab9ed1be4166e9e50d2afe Binary files /dev/null and b/images/new-list-input-fields.png differ diff --git a/images/new-retrieval.png b/images/new-retrieval.png new file mode 100644 index 0000000000000000000000000000000000000000..cee31d4b075686899f58bed68b0c0bda96c10668 Binary files /dev/null and b/images/new-retrieval.png differ