draft version of introduction, requirements adn basic concept documentation

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:
+
 ![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. 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.
 
-![Input fields](/images/new_inputs.png)
+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:
+
+![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, 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:
+
+![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.
+
+## 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.
+