PHPackages                             josephjbrewer/form-utils - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. josephjbrewer/form-utils

ActiveLibrary[Validation & Sanitization](/categories/validation)

josephjbrewer/form-utils
========================

Front-end form validation utilities for Symfony2 integration.

1.0.3(9y ago)218.1k2MITPHPPHP >=5.5.0

Since Jan 25Pushed 9y ago3 watchersCompare

[ Source](https://github.com/josephjbrewer/form-utils)[ Packagist](https://packagist.org/packages/josephjbrewer/form-utils)[ RSS](/packages/josephjbrewer-form-utils/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)DependenciesVersions (7)Used By (0)

JJB/FormUtilsBundle
===================

[](#jjbformutilsbundle)

This bundle is designed to validate Symfony forms on the front-end without duplicating code or validation efforts. This plugin also fully supports translations for error messages and suggestion text.

Installation
------------

[](#installation)

### Require composer package

[](#require-composer-package)

```
composer require josephjbrewer/form-utils

```

### Enable the bundle

[](#enable-the-bundle)

```
// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new JJB\FormUtilsBundle\JJBFormUtilsBundle(),
    );
}
```

### Set default form theme

[](#set-default-form-theme)

Edit app/config.yml and set the default form template provided by the form-utils bundle.

```
twig:
    form:
        resources:
            - 'JJBFormUtilsBundle:Form:form_theme.html.twig'
```

Usage
-----

[](#usage)

### Assets

[](#assets)

Add the assets provided in this bundle. I recommend using assetic.

```
{% javascripts
'@JJBFormUtilsBundle/Resources/assets/js/jquery.validator.js' %}

{% endjavascripts %}

{% stylesheets
'@JJBFormUtilsBundle/Resources/assets/css/style.scss' filter='compass' %}

{% endstylesheets %}
```

### Overriding the form theme

[](#overriding-the-form-theme)

By default, the provided form template uses the bootstrap theme provided by Symfony. This can be easily changed by making your own form theme and extending what is provided by this bundle.

The example below uses Symfony's default form theme.

```

{% extends 'form_div_layout.html.twig' %}
{% use 'JJBFormUtilsBundle:Form:form_blocks.html.twig' %}
```

### Rendering Forms

[](#rendering-forms)

In order for the form elements to render the data attributes required for validation, you will need to use twig to render the form fields.

```
{{ form_start(form) }}
{{ form_errors(form) }}

{{ form_row(form.username) }}
{{ form_row(form.password) }}
{{ form_row(form.submit) }}

{{ form_end(form) }}
```

### Data Suggestions

[](#data-suggestions)

Data suggestions are used to provide information to the user about a form field. For example, if the form is focused on a password field, it might be helpful to show the user what characters are allowed in the password. To do this, you have to add an attribute to your form field called `data-suggest`. This can be done in one of two ways.

#### With a form class

[](#with-a-form-class)

This method uses the "attr" option in the form builder.

```
public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder->add(
        'password',
        'password', [
            'attr' => [
                'data-suggest' => 'Must contain ...'
            ]
        ]
    );
}
```

#### With twig attributes

[](#with-twig-attributes)

This method adds the attribute directly to the form field.

```
{{ form_row(form.password.second, { 'attr' : {
    'data-suggest' : 'Must contain ...'
}}) }}
```

### Bind validator to form

[](#bind-validator-to-form)

Binding the validator to the form sets up listeners on the form and all of its elements. When the blur event is triggered on a form element, the plugin will validate it. When the submit event is triggered on the form, the plugin will validate all of the form elements. If validation fails, event propagation will stop and the form will not be submitted.

```
var form = $('#myForm');

// Enable validation (optional configuration)
$(form).validator(options);
```

In some cases, event propagation will be stopped before the validation listeners are triggered. This can happen if other javascript plugins are also listening to the submit event on the form. If this happens, you will need to manually trigger validator on your form. To do this, just use the following syntax:

```
if ($(form).validator('validate'[, options])) {
    // Do something
}
```

### Handle AJAX Errors

[](#handle-ajax-errors)

One of the reasons this bundle was developed is to help with binding errors that occur on the server-side to the form elements on the front-end. When validation fails on the server side, an error object is created. To handle AJAX errors on the front-end, return the serialized error object and the plugin will do the rest.

```
$(form).validator('handleErrors', response[, options]);
```

### Formatting Errors & Data Suggestions

[](#formatting-errors--data-suggestions)

Formatting errors and data suggestions is as simple as providing an inline template. The `messageTemplate` key is used for errors and the `suggestTemplate` key is used for data suggestions.

```
$(document).ready(function() {
    $('#myForm').validator({
        messageTemplate: ' {{message}}'
    });
});
```

Validator Options
-----------------

[](#validator-options)

KeyDescriptionDefault ValuerootErrorMessagePrepend root-level error with a title? (e.g. "Your form contains errors") ***Only works with AJAX errors***nullcontinueOnErrorContinue validation after an error occurs?falseseparatorCharacter used to concatenate form id's.\_suggestTemplateTemplate used for data suggestions{{message}}messageTemplateTemplate used for error messages{{message}}Advanced Usage
--------------

[](#advanced-usage)

### Supporting YAML/XML/Annotation Constraints

[](#supporting-yamlxmlannotation-constraints)

In a lot of cases, developers will use annotations or yaml/xml files to add constraints to a model. When a form is validated in Symfony, these constraints are validated along with any constraints added to the form.

If you instantiate a form that extends `AbstractBaseForm` with `MetaDataConstraintService` then the form will add the yaml/xml/annotation constraints to the form object when building the form view.

#### Create the form class

[](#create-the-form-class)

```