You are browsing the documentation for BootstrapBundle v2.0, if you haven't upgraded yet you can still browse the documentation for BraincraftedBootstrapBundle v1.4.

Components

BraincraftedBootstrapBundle bundle makes it easy to style forms and components provided by third party bundles with Bootstraps styles and still gives you the power to customize every aspect.

Manually integrating the styles from Bootstraps forms into a Symfony2 application is probably the most tideous part. Gladly, BraincraftedBootstrapBundle takes the hard work of your shoulders and does most of the integration for you.

Styles

BraincraftedBootstrapBundle integrates all styles from Bootstrap. You can pass the style attribute to most form widgets

{{ form(form, { 'style': 'horizontal' }) }}
{{ form_start(form, { 'style': 'horizontal' }) }}
{{ form_row(form.firstName, { 'style': 'horizontal' }) }}
{{ form_label(form.firstName, '', { 'style': 'horizontal' }) }}

If you pass the style to form or form_start you don't have to pass the style attribute to each form_row widget. The style will be defined for each widget between form_start and form_end.

{{ form_start(form, { 'style': 'horizontal' }) }}
    {{ form_row(form.firstName) }}
    {{ form_row(form.lastName) }}
{{ form_end(form) }}

Internally BraincraftedBootstrapBundle uses functions to write and read the global style and use can also use these functions, for example, when you use HTML for the <form> tag but want set the style once for all fields.

<form action="..." method="..." class="form-horizontal">
    {{ bootstrap_set_style('horizontal') }}

    {{ form_row(form.firstName) }}
    {{ form_row(form.lastName) }}

    {{ bootstrap_set_style('') }}
</form>

The function bootstrap_get_style() returns the current style.

Examples

The following examples shows the styles of all widgets provided by Symfony2 by default.

%
:
:
     

Bootstrap uses its grid to determine the size of label and widget. You can pass the label_col and widget_col options to set the number of columns label and widget should have. If you pass the option to form or form_start the options will affect the whole form. You can also use the Twig functions bootstrap_set_widget_col() and bootstrap_set_label_col().

{{ form_row(form.firstName, { 'label_col': 4, 'widget_col': 8}) }}
{{ form_label(form.lastName, '', { 'label_col': 6, 'style': 'horizontal' }) }}
{{ form(form, { 'label_col': 6, 'widget_col': 6 }) }}
{{ form_start(form, { 'label_col': 6, 'widget_col': 6 }) }}
{{ bootstrap_set_widget_col(6) }}
{{ bootstrap_set_label_col(6) }}
$builder->add('firstName', 'text', array('attr' => array('label_col' => 4, 'widget_col' => 8)));

There is also an option simple_col which wraps the input field (i.e., the widget) in a <div> with the given size. This is useful when creating compound types and is used, for example, in the date widget provided by BraincraftedBootstrapBundle. If you render the form row instead of the widget use `label_col` and `widget_col` instead.

{{ form_widget(form.firstName, { 'simple_col': 4 }) }}
{{ form(form, { 'simple_col': 4 }) }}
{{ form_start(form, { 'simple_col': 4 }) }}
{{ bootstrap_set_simple_col(4) }}
$builder->add('firstName', 'text', array('attr' => array('simple_col' => 4)));

Bootstrap includes multiple sizes of columns that behave differently depending on the device size. You can set the column size using the col_size option. This option can be set in the template, the form builder or using the Twig helper bootstrap_set_col_size.

{{ form_row(form.firstName, { 'col_size': 'xs' }) }}
{{ form_label(form.lastName, '', { 'col_size': 'md' }) }}
{{ bootstrap_set_col_size('md') }}
$builder->add('firstName', 'text', array('attr' => array('col_size' => 'xs')));

By default BootstrapBundle will use columns of size lg to render the form grid; you can change that by calling form or form_start with the col_size option or to use the Twig helper bootstrap_set_col_style.

{{ form(form, { 'style': 'horizontal', 'col_size': 'xs' }) }}
{{ form_start(form, { 'style': 'horizontal', 'col_size': 'xs' }) }}
{{ bootstrap_set_col_size('xs') }}

Basic Form

The default Bootstrap style is also included in this bundle.

Inline Form

Bootstrap also contains an inline style.

Requires custom widths

Inputs, selects, and textareas are 100% wide by default in Bootstrap. To use the inline form, you'll have to set a width on the form controls used within.

{{ form(inlineForm, { 'style': 'inline' }) }}
 
 
 

Checkbox and Radio Widgets

Note This section talks only about the field types checkbox and radio and not about choice, which can be rendered using checkbox and radio buttons.

Checkbox and radio widgets are a little bit different than other types of widgets, since Bootstraps wraps the input field inside the label. Therefore there are specific blocks checkbox_row and radio_row to render this markup. The blocks checkbox_widget and radio_widget only render the input element and not the label.

By default Bootstrap aligns checkboxes and radio fields on the left, if you want to align checkboxes and radio buttons with the other form elements, use the option align_with_widget. This option can be either setted on the form_row function or as an attribute when building the form.

$builder->add('termsAccepted', 'checkbox', array('attr' => array('align_with_widget' => true)));
{{ form_row(form.termsAccepted, { 'align_with_widget': true }) }}

Help text

You can add help texts either when building the form or directly in the template.

Letters, numbers and underscores are allowed.
$builder->add('username', 'text', array('attr' => array('help_text' => 'Letters, numbers and underscores are allowed.')));
{{ form_row(form.username, { 'help_text': 'Letters, numbers and underscores are allowed.' }) }}

Input groups

Input groups can also be added using the form builder or the template. Currently you can prepend and append text and control the size.

@
.00
$.00
$builder->add(
    'twitterScreenName',
    'text',
    array('attr' => array(
        'input_group' => array(
            'prepend' => '@',
            'size' => 'large'
        )
    ))
);
$builder->add(
    'price1',
    'text',
    array('attr' => array(
        'input_group' => array('append' => '.00')
    ))
);
$builder->add(
    'price2',
    'text',
    array(
        'attr' => array(
            'input_group' => array(
                'prepend' => '$',
                'append' => '.00',
                'size' => 'small'
            )
        )
    )
);
{{ form_row(form.twitterScreenname, { 'input_group': { 'prepend': '@', 'size': 'large' } }) }}
{{ form_row(form.price, { 'input_group': { 'append': '.00' } }) }}
{{ form_row(form.price2, { 'input_group': { 'prepend': '$', 'append': '.00', 'size': 'small' } }) }}

Icons

You can use icons in input groups by using the .icon- syntax. You can combine text and icons in a single input group.

$builder->add(
    'value',
    'text',
    array(
        'attr' => array(
            'input_group' => array(
                'prepend' => '.icon-cloud',
                'append' => '.icon-off',
                'size' => 'small'
            )
        )
    )
);
{{ form_row(form.value1, { 'input_group': { 'prepend': '.icon-cloud', 'size': 'large' } }) }}
{{ form_row(form.value2, { 'input_group': { 'append': '.icon-off' } }) }}

Buttons

You can also make use of buttons to attach them to fields, use the below syntax

$builder
    ->add('keywords', 'text', array(
        'attr' => array(
            'input_group' => array(
            'button_append' => array('name' => 'search', 'type' => 'submit')
        )
    )
));

Additional Form Types

BraincraftedBootstrapBundle does not only provides styles for the existing form types of Symfony2 but also provides you with addional types. In some cases this is due to technical limitations of the implementation of Twig and/or Symfony2.

Collection

bootstrap_collection is a form type that extends Symfony2s collection form type and includes styles and JavaScript to use the widget out of the box.

The form type also introduces new options:

  • add_button_text allows you to define the text on the Add button
  • delete_button_text allows you to define the text on the Delete button
  • sub_widget_col sets the number of columns used for the widget
  • button_col sets the number of columns used for the delete button

Here is an example of a form that lets you add and delete hobbits.

$form = $this->createFormBuilder(array())
    ->add(
        'hobbits',
        'bootstrap_collection',
        array(
            'allow_add'          => true,
            'allow_delete'       => true,
            'add_button_text'    => 'Add Hobbit',
            'delete_button_text' => 'Delete Hobbit',
            'sub_widget_col'     => 9,
            'button_col'         => 3
        )
    )
    ->getForm();

When rendered with Bootstraps horizontal style it will look like this:

Form Actions

By default buttons will be printed each in the own form_group, this means they will show up one per line. In order to get all the buttons to show up in the same line you can use the form_actions type.

It takes two syntaxes, you can either add buttons using the buttons option, or by adding the buttons as children of the form_actions type, see the examples below:

$form = $this->createFormBuilder(array())
    ->add('actions', 'form_actions', [
        'buttons' => [
            'save' => ['type' => 'submit', 'options' => ['label' => 'button.save']],
            'cancel' => ['type' => 'button', 'options' => ['label' => 'button.cancel']],
        ]
    ])
    ->getForm();

or

$form = $this->createFormBuilder(array())
        ->add('actions', 'form_actions');

    $form->get('actions')->add('save', 'submit', ['label' => 'button.save']);
    $form->get('actions')->add('cancel', 'button', ['label' => 'button.cancel']);
    $form->getForm();

Form errors

BraincraftedBootstrapBundle automatically styles error messages in forms.

Horizontal Form

  • This value should not be blank.
    • This value should not be blank.
    • This value should not be blank.
  • This value should not be blank.
  • This value should not be blank.
  • This value should be true.
  • This value should not be blank.

If you want to explicit show the global form errors, you need to pass global_errors to form_errors.

{{ form_errors(form, { 'global_errors': true }) }}

Basic Form

  • This value should be true.
  • This value should not be blank.
    • This value should not be blank.
    • This value should not be blank.
  • This value should not be blank.
  • This value should not be blank.
  • This value should not be blank.

Inline Form

  • This value should not be blank.
 
  • This value should not be blank.
 
  • This value should not be blank.
 

BraincraftedBootstrapBundle includes styles for KnpMenuBundle. Since Bootstrap contains a bunch of different styles you have provide the knp_menu_render with the style option.

Renders a menu in the tabs style of Bootstrap.

{{ knp_menu_render(menu, { 'style': 'tabs' }) }}

Tabs can be justified to span the whole width of the parent container.

{{ knp_menu_render(menu, { 'style': 'justified-tabs' }) }}
{{ knp_menu_render(menu, { 'style': 'pills' }) }}

Pills can also be stacked:

{{ knp_menu_render(menu, { 'style': 'stacked-pills' }) }}

Just like tabs, pills can also be justified.

{{ knp_menu_render(menu, { 'style': 'justified-pills' }) }}

You can also use KnpMenu to create the navigation elements in navbars. There are two types specifically for navbars: navbar and navbar-right for navbars that are pulled to the right.

<nav class="navbar navbar-default" role="navigation">
    <!-- Brand and toggle get grouped for better mobile display -->
    <div class="navbar-header">
        <button type="button" class="navbar-toggle"
                data-toggle="collapse" data-target=".navbar-ex1-collapse">
            <span class="sr-only">Toggle navigation</span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="#">Brand</a>
    </div>

    <!-- Collect the nav links, forms, and other content for toggling -->
    <div class="collapse navbar-collapse navbar-ex1-collapse">
        {{ knp_menu_render(leftNavbarMenu, { 'style': 'navbar' }) }}
        <form class="navbar-form navbar-left" role="search">
            <div class="form-group">
                <input type="text" class="form-control" placeholder="Search">
            </div>
            <button type="submit" class="btn btn-default">Submit</button>
        </form>
        {{ knp_menu_render(rightNavbarMenu, { 'style': 'navbar-right' }) }}
    </div><!-- /.navbar-collapse -->
</nav>

You can use BraincraftedBootstrapBundle to style the paginator component provided by KnpPaginatorBundle.

{{ knp_pagination_render(pagination) }}

You can override the previous and next labels and you can add links to jump to the first and last page.

{{ knp_pagination_render(pagination, "", {}, { "prev_label": "Previous", "next_label": "Next", "first_label": "First", "last_label": "Last"}) }}

You can also add a custom CSS class to the wrapping ul-element.

{{ knp_pagination_render(pagination, "", {}, { "class": "my_pagination" }) }}

Pager

Pager is an alternative style of pagination provided by Bootstrap. Instead of listing the available page numbers, only Previous and Next links are displayed. You can activate this kind of pagination by using the pager style.

{{ knp_pagination_render(pagination, "", {}, { "style": "pager" }) }} 

Bootstrap also provides an aligned style where the links are displayed on the left and right instead of the middle.

{{ knp_pagination_render(pagination, "", {}, { "style": "pager", "aligned": true }) }}

You can also override the labels of the pager component

{{ knp_pagination_render(pagination, "", {}, { "style": "pager", "prev_label": "&larr; Older", "next_label": "Newer &rarr;" }) }}

BraincraftedBootstrapBundle provides a helper class to easily create flash messages with Bootstrap alert styles. It is configured as a service with the ID braincrafted_bootstrap.flash. In a controller it would work like this:

$flash = $this->get('braincrafted_bootstrap.flash');
$flash->alert('This is an alert flash message.');
$flash->error('This is an error flash message.');
$flash->info('This is an info flash message.');
$flash->success('This is an success flash message.');

In a template you can use the flash.html.twig to quickly display all flash messages.

{% include 'BraincraftedBootstrapBundle::flash.html.twig' %}

Since the bundle utilizes the FlashBag of Symfony2 you also just use the service or just the template.

You can allow users to dismiss the messages by sending the close with value TRUE to the template.

{% include 'BraincraftedBootstrapBundle::flash.html.twig' with { 'close': true } %}

The bundle comes with Twig extensions to help you use Bootstraps labels in your templates.

{{ label('Default') }} Labels are great

Additionally BraincraftedBootstrapBundle comes with functions for different types of lables.

{{ label_success('Success') }}
{{ label_primary('Primary') }}
{{ label_info('Info') }}
{{ label_warning('Warning') }}
{{ label_danger('danger') }}

The bundle comes with Twig extensions to help you use Bootstraps badges in your templates.

<a href="#">Unread messages {{ badge('42') }}</a>

BraincraftedBootstrapBundle provides a function to include Glyphicons in templates.

<button type="button" class="btn btn-default btn-lg">{{ icon('camera') }} Camera</button>

There is also a filter to parse icons in a string of text. Just use .icon-NAME anywhere in the string and the filter will replace it with the HTML code.

{{ 'This is the story of a .icon-paperclip that travled the .icon-globe with his .icon-headphones on.'|parse_icons }}

Info You need to install the Glyphicon icon font before this will work. More information are in the installation instructions.

Info You can use a different icon set with BootstrapBundle. Include the other icon set in your stylesheets and change the value of braincrafted_bootstrap.icon_prefix to the appropriate prefix.

Font Awesome

BootstrapBundle works with Font Awesome. First you need to add Font Awesome to your project. For example, you can use Composer and add the official package to your composer.json:

$ composer require fortawesome/font-awesome:~4.0

Next you need to change the icon prefix to fa:

braincrafted_bootstrap:
  icon_prefix: fa

Info If you used another method to install Font Awesome (e.g., Bower or direct download) you probably need to change the braincrafted_bootstrap.fontawesome_dir option to point to the directory where the Font Awesome files are located.