Forms # form.json

The form.json is the setting file for a form in [JSON]((http://www.json.org/) format. You can edit this file with any Editor for text files.

The form.json uses different sections within the file to define the form, only the fields section is mandatory:

• confirmation - settings for the confirmation after form submission
• email - configure the email functions
• fields - list of field definitions (required)
• header - specify a header for the form
• panel - specify a panel at the top of the form
• recaptcha - configure the reCaptcha
• required - configure form settings

The sections are placed at the top level of the JSON file, the values of the section are enclosed between brackets:

{
    "fields":{
        ...
    }
}

###Section: confirmation

By default Contact will show the confirmation.twig from the form template directory after a successful submission of the form.

You can change the header and the text of the panel which is shown:

{
    "fields":{
        ...
    },
    "confirmation":{
        "header":"Thank you",
        "text":"We have received your message and will contact you as soon as possible."
    }
} 

It is also possible to use HTML tags but please be aware that you must mask all slashes / and double quotes " with a backslash: \/ and \" to avoid a breaking of the JSON code.

You can also redirect to another URL after a successful submission:

{
    "fields":{
        ...
    },
    "confirmation":{
        "redirect":{
            "url":"http:\/\/www.example.com\/example.php"
        }
    }
} 

this will redirect the submitter to the URL http://www.example.com/example.php.

You must always specify a complete URL with http:// .... Be aware that you must mask each slash / with a backslash \ to avoid problems reading the JSON: http:\/\/ ...

If you want to access the submitted form data at the redirected URL you can tell Contact to attach them as GET parameter to the URL:

{
    "fields":{
        ...
    },
    "confirmation":{
        "redirect":{
            "url":"http:\/\/www.example.com\/example.php",
            "parameter":true
        }
    }
} 

This will cause a redirection result like:

`http://www.example/example.php?ref=form&c=eyJw...ZXJzb25&f=yc29...uX2xh

where ref reference the the submission by the form.

The parameter c contain the submitted contact data and the parameter f the submitted general form data.

The contents of c and f are base64 encoded JSON strings, to access them in PHP:

$contact_data = json_decode(base64_decode($_GET['c']), true);

Be aware that the data are only encoded but not encrypted!

You can also tell Contact to use a route within the kitFramework to redirect to any other extension:

{
    "fields":{
        ...
    },
    "confirmation":{
        "redirect":{
            "route":"/example/confirmation"
        }
    }
}  

this will route to /example/confirmation as POST

The route will receive all generated form data, you can access them within your controller:

$form_config = $app['request']->get('config');
$form_data = $app['request']->get('form_data);
$contact_data = $app['request']->get('contact_data');
$form_record = $app['request']->get('form_record');

###Section: email

By default Contact will confirm the form submission also by email to the form submitter.

Contact parse for a field of type communication_email, if no field of this type exists Contact will parse for a field of type email and send a confirmation to this address if this field exists.

The website owner will also receive a email with the submitted form data. Contact will use the SERVER_EMAIL defined in the swift.cms.json.

You can switch off the email submission:

{
    "fields":{
        ...
    },
    "email":{
        "enabled":false
    }
} 

You can specify the sender email address and name:

{
    "fields":{
        ...
    },
    "email":{
        "mail_from":{
            "email":"[email protected]",
            "name":"Example Provider"
        }
    }
} 

and you can specify one or more recipients for email to the provider:

{
    "fields":{
        ...
    },
    "email":{
        "mail_to":[
            "[email protected]",
            "[email protected]"    
        ]
    }
}

in this case SERVER_EMAIL will no longer receive emails, but you can also add this email address to the mail_to list.

###Section: fields

This section contains the field definitions. The field types you can use here is full described in the chapter Forms # Field Types.

###Section: header

By default Contact does not spend the form any header, but you can set one:

{
    "fields":{
        ...
    },
    "header":{
        "text":"I'm a sample header!"
    }
}

additional you can set the level for the HTML header tag:

{
    "fields":{
        ...
    },
    "header":{
        "text":"I'm a sample header!",
        "level":3
    }
}

this will create:

<h3>I'm a sample header!</h3>

above the form.

###Section: panel

You can add a panel with brief information to the form. The panel will be displayed above the form and below the header (if you have specified one):

{
    "fields":{
        ...
    },
    "panel":{
        "text":"This is a brief description for the form below ..."
    }
}

You can also use HTML text but be aware to mask / and " with a backslash before: \/ and \" if they are used.

###Section: recaptcha

By default Contact will protect your form with a reCaptcha against SPAM.

You can switch off the reCaptcha:

{
    "fields":{
        ...
    },
    "recaptcha":{
        "enabled":false
    }
}

The reCaptcha is also switched off, if you have disabled it in the recaptcha.json.

###Section: required

By default the form will show an asterisk behind the label of a field, if this field is required.

Below the form is displayed a hint for these asterisks. You can switch off this hint:

{
    "fields":{
        ...
    },
    "required":{
        "hint":false
    }
}