Forms # Field Types

There a many different field types you can use within the fields section of the form.json setting file.

For Contact Forms exists two groups of field types:

• General form field types
• Accessing the Contact CRM

the field type is the main aspect of the field Properties and the only property which is mandatory for each field.

In general the sequence of the field definitions within the fields section is also so sequence shown by the generated form.

##Sample: Simple form

This is a complete form.json:

{
    "fields":{
        "email":{
            "type":"communication_email"
        },
        "message":{
            "type":"textarea",
            "name":"message"
        }
    }
} 

and will create a form with a mandatory email field and a textarea for a message:

The form is using the field type communication_email which causes the form to insert the submitted email address in Contact if the email address not already exist.

##Properties

Properties define the behavior of the fields used in form.

• choices
• help
• label
• name
• required
• type
• value

###Property: choices

The property choices enable you to define a group of value and text pairs and is mandatory for the field types:

• checkbox
• radio
• select

Example:

{
    "fields":{
        "example":{
            "name":"example",
            "type":"checkbox",
            "choices":{
                "value_1":"Text: Check value 1",
                "value_2":"Text: Check value 2",
                "value_3":"Text: Check value 3"
            }
        }
    }
}

###Property: help

The property help is optional and enable you to place a hint or help beneath the desired field.

Example:

Example:

{
    "fields":{
        "example":{
            "name":"example",
            "type":"text",
            "help":"I'm a hint for the usage of this field!"
        }
    }
}

###Property: label

The property label is optional. In general the label is shown at the left of a field and describe the function of the field. If you don't define the label property Contact will

• use the humanized name property for all general form field types
• use the default label for all field types to access the Contact CRM

Example:

{
    "fields":{
        "example":{
            "name":"example",
            "type":"text",
            "label":"Label for the example field"
        }
    }
}

###Property: name

The property name is

• mandatory for all general form field types
• ignored for field types to access the Contact CRM, the name value is identical with the type

The name property is needed to identify the field and to access the field values.

Example:

{
    "fields":{
        "example":{
            "name":"example",
            "type":"text"
        }
    }
}

In a Twig Template you can access the form row of the example field above:

{{ form_row(form.example) }}

###Property: required

The property required is used to indicate fields which must be filled out by the user, in general this will be an asterisk * behind the label or the field.

By default:

• required is set to false for all general form field types
• required is set to true for all field types to access the Contact CRM

Example:

{
    "fields":{
        "example":{
            "name":"example",
            "type":"text",
            "required":true
        }
    }
} 

###Property: type

The property type specify the type of the field. Contact knows to groups of field types:

• General form field types
• Field types to access the Contact CRM

###Property: value

The property value can be used to set a default value for a field.

Example:

{
    "fields":{
        "color":{
            "name":"color",
            "type":"radio",
            "choices":{
                "red":"Select the red one",
                "green":"Select the green one",
                "blue":"Select the blue one"
            },
            "value":"green"
        }
    }
}

this will pre-select the radio button with the entry "Select the green one".

The property value can also used to set multiple values as array if the field support this, i.e. tags:

{
    "fields":{
        "tags":{
            "type":"tags",
            "value":[
                "Newsletter",
                "Blog"
            ]
        }
    }
} 

##General form field types

• checkbox
• email
• hidden
• radio
• select
• single_checkbox
• text
• textarea
• url

###Type: checkbox

Define a checkbox group which can contain one or more values which can be selected (checked). The user can check multiple values.

If you need only one checkbox you should also have a look at the single_checkbox

Mandatory properties:

• type
• name
• choices

###Type: email

Define a input field of type email. You should use the field type email only, if you don't want to collect the form data at the Contact CRM. Otherwise it is always better to use communication_email instead!

Mandatory properties:

• type
• name

###Type: hidden

Define a hidden form field which will not be shown to the form submitter.

Mandatory properties:

• type
• name
• value

###Type: radio

Define a radio button group which can contain one or more values which can be selected. The user can select only one value.

Mandatory properties:

• type
• name
• choices

###Type: select

Define a select dropdown which can contain multiple values. The user can select only one value.

Mandatory properties:

• type
• name
• choices

###Type: single_checkbox

Define a *single checkbox" which can be checked. In different to checkbox this field will not display a label before the checkbox. This type is useful i.e. if you want that the submitter confirm your business conditions ...

Mandatory properties:

• type
• name

###Type: text

This will create a standard text input field for a general usage.

Mandatory properties:

• type
• name

###Type: textarea

This type will create a text input field with multiple lines.

Mandatory properties:

• type
• name

###Type: url

Will create a special input field for URLs. Contact will perform a check, if the URL is valid.

Mandatory properties:

• type
• name

##Field types to access the Contact CRM

The following field types are used to connect the form data with the Contact database and to collect all data at the Customer Relationship Management (CRM).

To open the connection the field type communication_email is mandatory, all other field types are optional.

• If the form submitter not exists in the Contact database a new record will be created and get the tag FORMS
• If the form submitter already exists in the Contact database the submitted data will be compared and the Contact record will be updated if necessary.

The following field types are actually supported:

• person_gender
• person_first_name
• person_last_name
• person_nick_name
• communication_email
• communication_phone
• address_city
• address_street
• address_zip
• tags

The following field types are actually not supported but coming in the near future:

• contact_type
• person_title
• person_birthday
• company_name
• company_department
• address_area
• address_state
• address_country_code

###Type: person_gender

This will create a dropdown select field with the choices Male and Female to specify the gender of the form submitter.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = person_gender
• label = Gender
• required = true

You can change property values other than name.

###Type: person_first_name

This will create a text field to collect the first name of the form submitter.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = person_first_name
• label = First name
• required = true

You can change property values other than name.

###Type: person_last_name

This will create a text field to collect the last name of the form submitter.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = person_last_name
• label = Last name
• required = true

You can change property values other than name.

###Type: person_nick_name

This will create a text field to collect the nick name of the form submitter.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = person_nick_name
• label = Nick name
• required = true

You can change property values other than name.

###Type: communication_email

This will create a field to collect the email address of the form submitter. This field is mandatory if you are using any field types to access the Contact CRM and always set to required.

If this field is set the submitter will receive a email confirmation for his form submission at this address.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = communication_email
• label = Email
• required = true

You can change property values other than name and required.

###Type: communication_phone

This will create a text field to collect the phone number of the form submitter

Mandatory properties:

• type

Properties automatically set by Contact:

• name = communication_phone
• label = Phone
• required = true

You can change property values other than name.

###Type: address_city

This will create a text field to collect the city the form submitter is living.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = address_city
• label = City
• required = true

You can change property values other than name.

###Type: address_street

This will create a text field to collect the street the form submitter is living.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = address_street
• label = Street
• required = true

You can change property values other than name.

###Type: address_zip

This will create a text field to collect the ZIP code of the city the form submitter is living.

Mandatory properties:

• type

Properties automatically set by Contact:

• name = address_zip
• label = ZIP
• required = true

You can change property values other than name.

###Type: tags

This will create a hidden field to add one or more TAG to your form, i.e. to indicate a Newsletter.

Mandatory properties:

• type
• value (support multiple values)

Properties automatically set by Contact:

• name = tags