ZenstruckFormBundle
Provides Twitter Bootstrap form theme, useful FormType Extensions and javascript helpers.
Installation
Add to your
composer.json
:composer require zenstruck/form-bundle:~1.4
Optional If using the
ajax_entity_controller
feature, addzendframework/zend-crypt
to yourcomposer.json
:composer require zendframework/zend-crypt:~2.0,!=2.1.1
Note: Version 2.1.1 of
zend-crypt
does not have it's autoloader configured correctly.Optional If using the Grouped form feature, add
cocur/slugify to yourcomposer.json
composer require cocur/slugify:~0.8
Register the bundle with Symfony2:
// app/AppKernel.php public function registerBundles() { $bundles = array( // ... new Zenstruck\Bundle\FormBundle\ZenstruckFormBundle(), // enable if you want to use the grouped form // new Cocur\Slugify\Bridge\Symfony\CocurSlugifyBundle() ); // ... }
If using 'Select2', be sure to download the required files from http://ivaynberg.github.io/select2/ and include the files in your template.
//base.html.twig Example //... {% block stylesheets %} <link href="{{ asset('path/to/select2.css') }}" type="text/css" rel="stylesheet" /> //... {% block javascripts %} <script type="text/javascript" src="{{ asset('path/to/select2.js') }}"></script> <script type="text/javascript" src="{{ asset('path/to/zenstruckform/js/helper.js') }}"></script> <script type="text/javascript" src="{{ asset('path/to/zenstruckform/js/script.js') }}"></script>
Twitter Bootstrap form layout
To use, do one of the following:
Add for a single template:
{# for bootstrap 2.x #} {% form_theme form 'ZenstruckFormBundle:Twitter:form_bootstrap_layout.html.twig' %} {# for bootstrap 3.x #} {% form_theme form 'ZenstruckFormBundle:Twitter:form_bootstrap3_layout.html.twig' %}
Add globally in your
config.yml
:twig: form: resources: # for bootstrap 2.x - 'ZenstruckFormBundle:Twitter:form_bootstrap_layout.html.twig' # for bootstrap 3.x - 'ZenstruckFormBundle:Twitter:form_bootstrap3_layout.html.twig'
FormType Extensions
AjaxEntityType
Creates a 1-m
or m-m
entity association field. This type simply creates a hidden field that takes
an either 1 or multiple comma separated entity ids. Note: Ensure the entity has __toString()
defined.
Enable in your config.yml
(disabled by default):
zenstruck_form:
form_types:
ajax_entity: true
There are several ways to use this type:
Default - creates a hidden field type. It is up to the user to add functionality.
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'zenstruck_ajax_entity', array( 'class' => 'AppBundle:MyEntity' // ensure MyEntity::__toString() is defined )) ; } // ... }
Select2 with built in entity finder (
zendframework/zend-crypt
required):Enable the controller in your
config.yml
(disabled by default):zenstruck_form: form_types: ajax_entity_controller: true
Add the route to your
routing.yml
:zenstruck_form: resource: "@ZenstruckFormBundle/Resources/config/ajax_entity_routing.xml"
Add to your form type:
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'zenstruck_ajax_entity', array( 'class' => 'AppBundle:MyEntity', // ensure MyEntity::__toString() is defined 'use_controller' => true, 'property' => 'name', // the entity property to search by // 'repo_method' => 'findActive' // for using a custom repository method // 'extra_data' => array() // for adding extra data in the ajax request (only applicable when using repo_method) )) ; } // ... }
Note: The URL is dynamically generated for each entity but is encrypted with the application's
secret
for
security purposes.Select2 with custom URL. This will create a Select2 widget for this field.
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'zenstruck_ajax_entity', array( 'class' => 'AppBundle:MyEntity', // ensure MyEntity::__toString() is defined 'url' => '/myentity/find' )) ; } // ... }
The url endpoint receives the search string as a
q
request parameter and must return a json encoded array.
Here is an example:[ {"id":2004,"text":"dolorem"}, {"id":2008,"text":"inventore"} ]
FormType options
class
: The entity the field represents. Required.url
: The url that Select2 will send search queries toproperty
: The entity property to search by (Overridesurl
)method
: The custom repository method to call for searches (Overridesproperty
)placeholder
: The Select2 placeholder text. Default: Choose an optionmultiple
: Whether this is allows for multiple values. Default: falseuse_controller
: Whether to use the bundled controller or not (``). Default: falserepo_method
: For using a custom repository method. Default: nullextra_data
: For adding extra data in the ajax request (only applicable when using repo_method). Default array()
Select2 Javascript Helper
Enables the Select2 widget for AjaxEntityType
. Requires
Select2.
Enable with ZenstruckFormHelper.initSelect2Helper()
TunnelEntityType
Creates an entity association field with a select button. A javascript callback for the select button may be defined.
Can be used for opening a dialog to choose an entity.
Enable in your
config.yml
(disabled by default):zenstruck_form: form_types: tunnel_entity: true
Add help option to your form fields
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'zenstruck_tunnel_entity', array( 'class' => 'AppBundle:MyEntity', 'callback' => 'MyApp.selectMyEntity', 'required' => false )) ; } // ... }
The widget html generated by the above example is as follows:
<div class="input-append zenstruck-tunnel-widget">
<input type="hidden" class="zenstruck-tunnel-id" />
<span class="uneditable-input zenstruck-tunnel-title">{{ title }}</span>
<a href="#" class="btn zenstruck-tunnel-clear"><b class="icon-remove"></b></a>
<a href="#" class="btn zenstruck-tunnel-select" data-callback="MyApp.selectMyEntity">Select...</a>
</div>
Your javascript can hook into the clear button and select button. Here are the useful classes:
.zenstruck-tunnel-id
: id of the selected entity.zenstruck-tunnel-title
: title of the selected entity.zenstruck-tunnel-clear
: button that clears the title/id (only available ifrequired
isfalse
).zenstruck-tunnel-select
: button that initiates the entity selection
FormType options
class
: The entity the field represents. Required.callback
: The javascript callbackbutton_text
: The text for the select button. Default: Select...
Tunnel Javascript Helper
Adds events to the clear and select buttons. The select button calls the callback
defined in the type options.
The callback receives the following parameters:
id
: the id of the currently selected entity (if any)element
: the hidden input element
Enable with ZenstruckFormHelper.initTunnelHelper()
HelpType
Allow you to add help messages to your form fields.
Enable in your
config.yml
(disabled by default):zenstruck_form: form_types: help: true
Add help option to your form fields
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'text', array( 'help' => 'Your full name' )) ; } // ... }
Group Type
This type allows you group large forms into tabs.
Enable in your
config.yml
(disabled by default):zenstruck_form: form_types: group: true
Add help option to your form fields
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'text', array( 'group' => 'Foo' )) ->add('name', 'text', array( 'group' => 'Bar' )) ; } // ... }
Note: fields without a group will be in the first, default tab.
When creating your form view in your controller, wrap it with
Zenstruck\Bundle\FormBundle\Form\GroupedFormView
class MyController extends Controller { public function newAction(Request $request) { // ... return array( 'grouped_form' => new \Zenstruck\Bundle\FormBundle\Form\GroupedFormView($form->createView()) ); } }
Note: to name your default tab to something other than Default, pass it as the second parameter
to theGroupedFormView
constructor.In your template, include
grouped_form.html.twig
to render the form.<form method="post" {{ form_enctype(grouped_form.form) }}> {% include 'ZenstruckFormBundle:Twitter:grouped_form.html.twig' with { 'grouped_form': grouped_form } %} </form>
Note: to use the wrapped form, use
grouped_form.form
Add custom data to GroupedFormView
// ..
$groupedForm = new \Zenstruck\Bundle\FormBundle\Form\GroupedFormView($form->createView());
$groupedForm->setData('foo', 'bar');
In your template:
{# ... #}
{{ grouped_form.data('foo') }} {# returns bar #}
Custom group order
$groupedForm = new GroupedFormView($form->createView(), 'Default', array(
'Bar', 'Foo', 'Default'
));
Theme Type
Allow you to add theme options to your form fields. The theme_options
variable will be
available in your form theme. The bootstrap3 theme currently utilizes.
Enable in your
config.yml
(disabled by default):zenstruck_form: form_types: theme: true
Set default theme options in your
config.yml
zenstruck_form: theme_options: control_width: col-md-4 label_width: col-md-2 # ...
Set theme options on a field in your form
use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; class MyFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('name', 'text', array( 'theme_options' => array('control_width' => 'col-md-6') )) ; } // ... }
Miscellaneous Javascript helpers
This bundle comes with a set of useful javascript helpers. To enable, add the following javascipt file (or add to your
assetic javascripts):
<script type="text/javascript" src="{{ asset('bundles/zenstruckform/js/helper.js') }}"></script>
Initialize all helpers with:
$(function() {
ZenstruckFormHelper.initialize();
});
PostLinkHelper
Allows a standard <a>
tag to become a method="POST" link. Add the class method-post
, method-post-confirm
or method-delete
to an <a>
tag for it's href value to become a POST link.
method-post
: standard post link (no confirmation)method-post-confirm
:method-post
with a confirmation dialog that is customizable via thedata-message
attributemethod-delete
: cross browser compatible DELETE link with a "Are you sure you want to delete?" confirmation dialog
Enable with ZenstruckFormHelper.initPostLinkHelper()
FormCollectionHelper
Adds Symfony2 form collection 'add' and 'delete' button functionality. See the
Symfony2 docs. This works out of the box when
using the form_bootstrap_layout.html.twig
form layout provided by this bundle.
Note: Do not add the javascript provided in the Symfony2 cookbook article
Enable with ZenstruckFormHelper.initFormCollectionHelper()
Full default config
zenstruck_form:
form_types:
help: false
group: false
tunnel_entity: false
ajax_entity: false
ajax_entity_controller: false
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
zenstruck_form:
form_types:
help: false
group: false
theme: false
tunnel_entity: false
ajax_entity: false
ajax_entity_controller: false
theme_options: Array
-
Merge pull request #43 from ptsavdar/master
By kbond, 5 years ago
-
Added icon option for ajax entity dropdown result items
By ptsavdar, 5 years ago
-
Update README.md
By kbond, 5 years ago
-
Merge pull request #41 from philkingston/master
By kbond, 5 years ago
-
Format code (replace tabs with spaces and align values)
By Phil Kingston, 5 years ago
-
Add parameter for minimumInputLength
By Phil Kingston, 5 years ago
-
update readme (fixes (#40)
By kbond, 5 years ago
-
fix typo (fixes #39)
By kbond, 5 years ago
-
Merge pull request #37 from maxailloud/class_on_textarea_field
By kbond, 5 years ago
-
Add form-control class on textarea form field
By maxailloud, 5 years ago
-
added more test environments
By kbond, 6 years ago
-
Merge pull request #33 from maxailloud/patch-2
By kbond, 6 years ago
-
Fix javascript to call for working with form collection
By maxailloud, 6 years ago
-
update changelog
By kbond, 6 years ago
-
switch from ZenstruckSlugifyBundle to CocurSlugifyBundle
By kbond, 6 years ago
-
added changelog
By kbond, 6 years ago
-
Merge pull request #30 from doughayward0/patch-1
By kbond, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Merge pull request #28 from doughayward0/patch-1
By kbond, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Update README.md
By DougHayward, 6 years ago
-
Merge pull request #27 from maxailloud/extra-data-for-ajax-request
By kbond, 6 years ago
-
Add default value for extra parameter for BC
By maxailloud, 6 years ago
-
Adding documentation for the new field option
By maxailloud, 6 years ago
-
Allow the use of extra data for ajax request when using the ajax entity type field form
By maxailloud, 6 years ago
-
Merge pull request #24 from rgb-/patch-1
By kbond, 7 years ago