Forms # Creating a form

1. Introduction
2. form.json
3. Form Patterns
4. confirmation.twig
5. provider.mail.twig & submitter.mail.twig

##Introduction

All Contact forms are using Twig and organized in the template directory of the Contact extension:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template

by default Contact will access the default templates from the /default directory:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default

all forms are subdirectories of the /form directory:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default/form

the name of a form subdirectory is also the name of the template:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default/form/sample_contact

is the directory of the form with the name sample_contact.

You can execute this form with a kitCommand from any WYSIWYG section:

~~ Contact action[form] form[sample_contact] ~~

will show you the sample_contact form:

Contact comes with a couple of samples for forms in the /Template/default/form/ directory, have a look to them.

You should never change anything within the /Template/default directories - these directories will be overwritten every time an extension update is processed and your changes will get lost.

Always create your own Template directory, i.e. /foo:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/foo

add a form directory:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/foo/form

and now a subdirectory /example for your first form with the name example:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/foo/form/example

The easiest way is copy an existing form into your new form directory.

Copy the files:

confirmation.twig
form.json
form.twig
provider.mail.twig
submitter.mail.twig

from

../Template/default/form/sample_contact

into

../Template/foo/form/example

To execute the form example from the template directory foo you must change the kitCommand within the WYSIWYG section:

~~ Contact action[form] form[example] template[foo] ~~

With parameter template[] you advice Contact to use the /foo directory as preferred path. If the needed files does not exists in /foo the program will try to load it from the /default directory. For this reason

~~ Contact action[form] form[sample_contact] template[foo] ~~

will show you the form sample_contact from the /Template/default/form directory. But:

~~ Contact action[form] form[example] ~~

will prompt an error message, because the form example does not exists in /Template/default/form. Therefore we are switching back to:

~~ Contact action[form] form[example] template[foo] ~~

At the moment the form example is identical with the form sample_contact.

##form.json

The fields and the behaviour of a form is defined in the form.json. Open the file:

../Template/foo/form/example/form.json

and have a look at it:

{
  "fields":{
    "gender":{
      "type":"person_gender",
      "required":false
    },
    "vorname":{
      "type":"person_first_name",
      "required":false
    },
    "nachname":{
      "type":"person_last_name"
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true
    }
  }
}

Within the fields section you see the definition for the field types of this form:

• person_gender
• person_first_name
• person_last_name
• communication_email
• textarea

Now we want to check that the new form is really working. Let's say, we need only the fields nachname, mail and message and remove all other fields:

{
  "fields":{
    "nachname":{
      "type":"person_last_name"
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true
    }
  }
}

In addition we want that the field nachname is no longer a required field:

{
  "fields":{
    "nachname":{
      "type":"person_last_name",
      "required":false
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true
    }
  }
}

Save the form and have a look at it:

You see, it's easy.

Let's say we want to use this form as a feedback form, so we need:

• a short introduction ("Please leave ...")
• a field for a nickname
• a field for the email address
• a textarea for the the feedback

First we add a panel with the introduction text to the form:

{
  "panel":{
    "text":"Do you even like our website? Please leave a comment!"
  },    
  "fields":{
    "nachname":{
      "type":"person_last_name",
      "required":false
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true
    }
  }
} 

Now we are changing the field nachname to a required nickname field:

{
  "panel":{
    "text":"Do you even like our website? Please leave a comment!"
  },    
  "fields":{
    "nickname":{
      "type":"person_nick_name"
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true
    }
  }
}

At least we change the label of the message field to "Your comment":

{
  "panel":{
    "text":"Do you even like our website? Please leave a comment!"
  },    
  "fields":{
    "nickname":{
      "type":"person_nick_name"
    },
    "mail":{
      "type":"communication_email"
    },
    "message":{
      "type":"textarea",
      "name":"message",
      "required":true,
      "label":"Your comment"
    }
  }
}  

Save the file and have a look to the generated form:

##Form Patterns

If you have a look into the form.twig of your form template, you will see that this file is including a form pattern:

{% include '@phpManufaktur/Contact/Template/default/pattern/form/horizontal/form.twig' %}

This pattern generate a horizontal form using Bootstrap 3.

As long as this form fits to your needs, you must not dive into the form generating with the Symfony Form Factory and formatting with Twig and Bootstrap.

If you want to change the form layout you should have a look into the sample form sample_customize, this form will show you the first steps to change the form.twig layout:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default/form/sample_customize

In all other cases (recommend) you should simply include the form.twig pattern:

{% include '@phpManufaktur/Contact/Template/default/pattern/form/horizontal/form.twig' %}

There exists some more patterns:

• confirmation.twig
• provider.mail.twig
• submitter.mail.twig

these patterns are used by the form samples and should be fitted to your needs.

##confirmation.twig

The confirmation.twig will be shown after the submission of the form.

You can change the header and text of the confirmation within the form.json.

If this does not fit to your needs, you can change the confirmation.twig in any way you want.

In the first step you should copy the content of the confirmation.twig pattern:

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default/pattern/form/horizontal/confirmation.twig

into your own confirmation.twig.

Now you can change the confirmation:

{# show the ENGLISH Version (STANDARD) #}
<div class="panel panel-default">
  <div class="panel-heading">
    <h3 class="panel-title">Thank you</h3>
  </div>
  <div class="panel-body">
    <p>We have received your submission and will contact you as soon as possible.</p>
    <p>If you have also submitted your email address, we have send you a confirmation mail.</p>
    <p><em>Regards, your {{ CMS_TYPE }} Team</em></p>
  </div>
</div> 

to your needs. You will find a block for each supported language and sure, you can add also additional languages.

Within this template you can also access the submitted form data:

• form_data contain the general form fields
• contact_data contain the contact form fields

To insert the email address of the submitter from the field communication_email use the placeholder:

{{ contact_data.confirmation_email }}

The scheme is always {{ contact_data.<fieldname> }} or {{ form_data.<fieldname> }}.

To access the submitted message use:

{{ form_data.message }}

Please have also a look into the Twig Documentation.

##provider.mail.twig & submitter.mail.twig

These both templates are used for the email to the provider (owner of the website, webmaster) and to the submitter of the form.

Copy the contents of the patterns from

/kit2/extension/phpmanufaktur/phpManufaktur/Contact/Template/default/pattern/form/mail

into your templates.

You will find a condition which check the language of the form:

{% if app.translator.locale == 'de' %}
  {# GERMAN Version #}
  ...
{% else %}
  {# ENGLISH Version #}
  ...    
{% endif %}     

Within the condition are placed loops like:

{% if contact_data|length > 0 %}
  <p>Submitted Contact data:</p>
  <p>{% for field, value in contact_data %}
  {% if loop.index > 1 %}<br />{% endif %}
    {{ field }} => {{ value }}
  {% endfor %}</p>
{% endif %}

these loops are useful to show all fields and values used in the form and therefor a good solution for the email send to the provider.

For the mail to the submitter you may prefer a less detailed but more individual message.

You can access each field value as described in confirmation.twig and you can use conditions to create personalized messages, i.e. if you are using the fields person_gender and person_last_name:

<p>Dear {% if contact_data.person_gender == 'MALE' %}Mr.{% else %}Mrs.{% endif %} {{ contact_data.person_last_name }},</p> 

to create Dear Mrs. Foobar, or Dear Mr. Foo, as first line of the email.

Please have also a look into the Twig Documentation.