NAME Mojolicious::Plugin::BootstrapHelpers - Type less bootstrap SYNOPSIS # Mojolicious $self->plugin('BootstrapHelpers'); # ::Lite plugin 'BootstrapHelpers'; # Meanwhile, somewhere in a template... %= formgroup 'Email', text_field => ['email'], large, cols => { small => [3, 9] } # ...that renders into
STATUS This is an unstable work in progress. Backwards compatibility is currently not to be expected between releases. Currently supported Bootstrap version: 3.2.0. Currently only Perl 5.20+ is supported (thanks to postderef). DESCRIPTION Mojolicious::Plugin::BootstrapHelpers is a convenience plugin that reduces some bootstrap complexity by introducing several tag helpers specifically for Bootstrap 3 . The goal is not to have tag helpers for everything, but for common use cases. All examples below (and more, see tests) is expected to work. How to use Bootstrap If you don't know what Bootstrap is, see for possible usages. You might want to use Mojolicious::Plugin::Bootstrap3 in your templates. To get going quickly by using the official CDN you can use the following helpers: # CSS %= bootstrap # or (if you want to use the theme) %= bootstrap 'theme' # And the javascript %= bootstrap 'js' # Or just: %= bootstrap 'all' It is also possible to automatically include jQuery (2.*) %= bootstrap 'jsq' %= bootstrap 'allq' Strappings There are several shortcuts ("strappings") for applying context and size classes that automatically expands to the correct class depending on which tag it is applied to. For instance, if you apply the "info" strapping to a panel, it becomes "panel-info", but when applied to a button it becomes "btn-info". You can use them in two different ways, but internally they are the same. These to lines are exactly identical: %= button 'Push me', primary %= button 'Push me', __primary => 1 For sizes, you can only use the longform ("xsmall", "small", "medium" and "large") no matter if you use the short strapping form or not. They are shortened to the Bootstrap type classes. The following strappings are available: xsmall default striped caret right small primary bordered medium success hover large info condensed warning responsive danger Add two leading underscores if you don't want to use the short form. See below for usage. Important: You can't follow a short form strapping with a fat comma ("=>"). The fat comma auto-quotes the strapping, and then it breaks. If there is no corresponding class for the element you add the strapping to it is silently not applied. Syntax convention In the syntax sections below the following conventions are used: name A specific string $name Any string %name One or more key-value pairs, written as: key => 'value', key2 => 'value2' or, if you use short form strappings: primary, large $key => [...] Both of these are array references where the ordering of strings key => [...] are significant, for example: key => [ $thing, $thing2, %hash ] $key => {...} Both of these are hash references where the ordering of pairs are key => {...} are insignificant, for example: key => { key2 => $value, key3 => 'othervalue' } (...) Anything between parenthesis is optional. The parenthesis is not part of the actual syntax |...| Two pipes is a reference to another specification. For instance, button toolbars contain button groups that contain buttons. Using this syntax makes the important parts clearer. The pipes are not part of the actual syntax. Ordering between two hashes that follows each other is also not significant. About %has The following applies to all %has hashes below: * They refer to any html attributes and/or strappings to apply to the current element. * When helpers are nested, all occurrencies are change to tag-specific names, such as %panel_has. * This hash is always optional. It is not marked so in the definitions below in order to reduce clutter. * Depending on context either the leading or following comma is optional together with the hash. It is usually obvious. * Sometimes on nested helpers (such as tables in panels just below), %has is the only thing that can be applied to the other element. In this case "panel => { %panel_has }". It follows from above that in those cases this entire expression is *also* optional. Such cases are also not marked as optional in syntax definitions and are not mentioned in syntax description, unless they need further comment. From this definition: %= table ($title,) %table_has, panel => { %panel_has }, begin $body % end Both of these are legal: # since both panel => { %panel_has } and %table_has are hashes, their ordering is not significant. %= table 'Heading Table', panel => { success }, condensed, id => 'the-table', begin A Table Cell % end %= table begin A Table Cell % end References All other "|references|" are also helpers, so "|link|" and "|item|" needs special mention. |link| "|link|" creates an "" tag. |link| Is exactly the same as $link_text, [ $url ], %link_has $link_text Mandatory. The text on the link. $url Mandatory. It sets the "href" on the link. url_for is used to create the link. %link_has Which strappings are available varies depending on context. |item| "|item|" is used in the various submenus/dropdowns. One "|item|" creates one "
  • " tag. |item| Is exactly the same as [ |link| ] # or $header_text # or [] So, a submenu item can be one of three things: 1. A link, in which case you create a "|link|" in an array reference. 2. A ".dropdown-header", in which case you give it a 'string' which then is turned into the text of the header. 3. A ".divider", in which case you give it an empty array reference. See "Dropdowns", "Button groups" and "Navbars" for examples. HELPERS Bootstrap documentation Badges Syntax %= badge $text, %has $text Mandatory. If it is "undef" no output is produced. Available strappings "right" applies ".pull-right". Examples <%= badge '3' %> 3 <%= badge '4', data => { custom => 'yes' }, right %> 4 Buttons Bootstrap documentation Syntax %= button $button_text(, [$url]), %has %= submit_button $text, %has $button_text Mandatory. The text on the button. "[$url]" Optional array reference. It is handed off to url_for, so with it this is basically link_to with Bootstrap classes. Not available for "submit_button". Available strappings "default" "primary" "success" "info" "warning" "danger" "link" applies the various ".btn-*" classes. "large" "small" "xsmall" applies ".btn-lg" ".btn-sm" ".btn-xs" respectively. "active" "block" applies the ".active" and ".block" classes. "disabled" applies the ".disabled" class if the generated element is an "". On a " %= button 'The example 1' => ['http://www.example.com/'], small The example 1 %= submit_button 'Save 2', primary Button groups Syntax There are two different syntaxes. One for single-button groups and one for multi-button groups. The difference is that single-button groups can't change anything concerning the buttongroup (e.g. it can't be "justified"). If you need to do that there is nothing wrong with having a multi-button group with just one button. # multi button <%= buttongroup %has, buttons => [ [ |button|, (items => [ |item| ]) ] ] %> # single button <%= buttongroup [ |button|, (items => [ |item| ]) ] %> "buttons => []" The single-button style is a shortcut for the "buttons" array reference. It takes ordinary buttons, with two differences: The "items" array reference, and it is unnecessary to give a button with "items" a url. "items => [...]" Giving a button an "items" array reference consisting of one or many "|item|" creates a dropdown like submenu. Read more under "item". Examples <%= buttongroup buttons => [ ['Button 1'], ['Button 2'], ['Button 3'], ] %>
    <%= buttongroup small, buttons => [ ['Button 1'], ['Dropdown 1', caret, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ], ['Button 2'], ['Button 3'], ], %>
    <%= buttongroup vertical, buttons => [ ['Button 1'], ['Dropdown 1', caret, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ], ['Button 2'], ['Button 3'], ], %>
    <%= buttongroup justified, buttons => [ ['Link 1', ['http://www.example.com/'] ], ['Link 2', ['http://www.example.com/'] ], ['Dropup 1', caret, dropup, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ], ] %> <%= buttongroup buttons => [ ['Link 1', ['http://www.example.com/'] ], [undef, caret, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ], ] %> <%= buttongroup ['Default', caret, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ] %> <%= buttongroup ['Big danger', caret, large, danger, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ] %>
    Button toolbars Syntax <%= toolbar %toolbar_has, groups => [ { |button_group| } ] %> "groups => [ { |button_group| } ]" A mandatory array reference of button groups. Examples <%= toolbar id => 'my-toolbar', groups => [ { buttons => [ ['Button 1'], ['Button 2'], ['Button 3'], ], }, { buttons => [ ['Button 4', primary], ['Button 5'], ['Button 6'], ], }, ] %>
    Dropdowns Syntax <%= dropdown %has, [ |button|, items => [ |item| ] ] "[ |button| ]" Mandatory array reference. It takes an ordinary button, with two differences: The "items" array reference, and it is unnecessary to give a button with "items" a url. "items" Mandatory array reference consisting of one or many "|item|". Read more under "item". Available strappings "caret" adds a "" element on the button. Examples <%= dropdown ['Dropdown 1', id => 'a_custom_id', right, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ] ] ] %> <%= dropdown ['Dropdown 2', caret, large, primary, items => [ ['Item 1', ['item1'], data => { attr => 2 } ], ['Item 2', ['item2'], disabled, data => { attr => 4 } ], [], ['Item 3', ['item3'], data => { attr => 7 } ], [], ['Item 4', ['item4'], tabindex => 4 ], 'This is a header', ['Item 5', ['item5'] ], ] ] %> Form groups Bootstrap documentation Syntax <%= formgroup ($labeltext,) %formgroup_has, (cols => { $size => [ $label_columns, $input_columns ], (...) }) $fieldtype => [ $input_name, ($input_value,) %input_has, ] %> # The $labeltext can also be given in the body %= formgroup , begin $labeltext % end $labeltext Optional. It is either the first argument, or placed in the body. It creates a "label" element before the "input". "cols" Optional. It is only used when the "form" is a ".form-horizontal". You can defined the widths for one or more or all of the sizes. See examples. $size Mandatory. It is one of "xsmall", "small", "medium" or "large". $size takes a two item array reference. $label_columns Mandatory. The number of columns that should be used by the label for that size of screen. Applies ".col-$size-$label_columns" on the label. $input_columns Mandatory. The number of columns that should be used by the input for that size of screen. Applies ".col-$size-$input_columns" around the input. $fieldtype Mandatory. Is one of "text_field", "password_field", "datetime_field", "date_field", "month_field", "time_field", "week_field", "number_field", "email_field", "url_field", "search_field", "tel_field", "color_field". There can be only one $fieldtype per "formgroup". $name Mandatory. It sets both the "id" and "name" of the input field. If the $name contains dashes then those are translated into underscores when setting the "name". If "id" exists in %input_has then that is used for the "id" instead. $input_value Optional. If you prefer you can set "value" in %input_has instead. (But don't do both for the same field.) Examples %= formgroup 'Text test 1', text_field => ['test_text']
    %= formgroup 'Text test 4', text_field => ['test-text', large]
    %= formgroup 'Text test 5', text_field => ['test_text', '200' ]
    %= formgroup 'Text test 6', text_field => ['test_text'], large, cols => { small => [2, 10] }
    %= formgroup 'Text test 8', text_field => ['test_text'], cols => { medium => [2, 10], small => [4, 8] }
    Icons This helper needs to be activated separately, see options below. Syntax %= icon $icon_name $icon_name Mandatory. The specific icon you wish to create. Possible values depends on your icon pack. Examples <%= icon 'copyright-mark' %> %= icon 'sort-by-attributes-alt' Input groups Syntax <%= input %has, (prepend => ...,) input => { |input_field| }, (append => ...) %> "input => { }" Mandatory hash reference. The content is handed off to input_tag in Mojolicious::Plugin::TagHelpers. "prepend" and "append" Both are optional, but input groups don't make sense if neither is present. They take the same arguments, but there are a few to choose from: "prepend => $string" "prepend => { check_box => [ |check_box| ] }" Creates a checkbox by giving its content to check_box in Mojolicious::Plugin::TagHelpers. "prepend => { radio_button => [ |radio_button| ] }" Creates a radiobutton by giving its content to radio_button in Mojolicious::Plugin::TagHelpers. "prepend => { buttongroup => { |buttongroup| }" Creates a single button buttongroup. See button groups for details. "prepend => { buttongroup => [ |buttongroup| ]" Creates a multi button buttongroup. See button groups for details. Examples <%= input input => { text_field => ['username'] }, prepend => { check_box => ['agreed'] } %>
    <%= input large, prepend => { radio_button => ['yes'] }, input => { text_field => ['username'] }, append => '@' %>
    @
    <%= input input => { text_field => ['username'] }, append => { button => ['Click me!'] }, %>
    <%= input input => { text_field => ['username'] }, append => { buttongroup => [['The button', caret, right, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ] ] ] } %>
    <%= input input => { text_field => ['username'] }, prepend => { buttongroup => [ buttons => [ ['Link 1', ['http://www.example.com/'] ], [undef, caret, items => [ ['Item 1', ['item1'] ], ['Item 2', ['item2'] ], [], ['Item 3', ['item3'] ], ], ], ], ], }, %> Navs Syntax <%= nav %has, $type => [ |link|, (items => [ |item| ]) ] %> "Navs" are syntactically similar to button groups. "$type => [...]" Mandatory. $type is either "pills" or "tabs" (or "items" if the "nav" is in a navbar) and applies the adequate class to the surrounding "ul". "items => [ |item| ]" If present does the same as "items" in dropdown. Also see "item". Examples <%= nav pills => [ ['Item 1', ['#'] ], ['Item 2', ['#'], active ], ['Item 3', ['#'] ], ['Item 4', ['#'], disabled ], ] %> <%= nav justified, id => 'my-nav', tabs => [ ['Item 1', ['#'] ], ['Item 2', ['#'], active ], ['Item 3', ['#'] ], ['Dropdown', ['#'], caret, items => [ ['There are...', ['#'] ], ['...three...', ['#'] ], [], ['...choices', ['#'] ], ], ], ] %> Navbars Syntax navbar (inverse,) header => [ |link|, %navbar_has ], form => [ [ [ $url ], %form_has ], [ formgroup => [ |formgroup| ], input => [ |input| ], button => [ |button| ], submit_button => [ |submit_button| ], ] ], button => [ |button| ], nav => [ |nav| ] p => [ $text, %p_has ] "Navbars" are complex structures. They take the following arguments: "inverse" The "inverse" strapping is currently outside the %navbar_has. It applies the ".navbar-inverse" class. "header => [ |link|, %navbar_has ]" "header" creates a "navbar-header". There can be only one "header". "|link|" Creates the "brand". Set the link text to "undef" if you don't want a brand. %navbar_has Can take the following extra arguments: The "hamburger" strapping creates the menu button for collapsed navbars. "toggler => $collapse_id" This sets the "id" on the collapsing part of the navbar. Set it if you need to reference that part of the navbar, otherwise an id will be generated. The following arguments can appear any number of times, and is rendered in order. "button => [ |button| ]" Creates a button. "nav => [ |nav| ]" Creates a nav. Use "items" if you need to create submenus. "p => [ $text, %p_has ]" Creates a "

    $text

    " tag. "form => [...]" Creates a "form", by leveraging form_for in Mojolicious::Plugin::TagHelpers. "[ [ $url ], %form_has ]" Mandatory array reference. This sets up the "form" tag. "[...]" Mandatory array reference. The second argument to "form" can take different types (any number of times, rendered in order): "formgroup => [ |formgroup| ]" "input => [ |input| ]" "button => [ |button| ]" "submit_button => [ |submit_button| ]" Creates form groups, input groups, buttons and submit_buttons Examples <%= navbar header => ['The brand', ['#'], hamburger, toggler => 'bs-example-navbar-collapse-2'], nav => [ items => [ ['Link', ['#'] ], ['Another link', ['#'], active ], ['Menu', ['#'], caret, items => [ ['Choice 1', ['#'] ], ['Choice 2', ['#'] ], [], ['Choice 3', ['#'] ], ] ], ] ] %> <%= navbar header => ['Brand', ['#'], hamburger, toggler => 'collapse-4124'], nav => [ items => [ ['Link', ['#'], active ], ['Link', ['#'] ], ['Dropdown', ['#'], caret, items => [ ['Action', ['#'] ], ['Another action', ['#'] ], ['Something else here', ['#'] ], [], ['Separated link', ['#'] ], [], ['One more separated link', ['#'] ], ] ] ], ], form => [ [['/login'], method => 'post', left], [ formgroup => [ text_field => ['the-search', placeholder => 'Search' ], ], submit_button => ['Submit'], ] ], nav => [ right, items => [ ['Link', ['#'] ], ['Dropdown', ['#'], caret, items => [ ['Action', ['#'] ], ['Another action', ['#'] ], ['Something else here', ['#'] ], [], ['Separated link', ['#'] ], ], ] ], ] %> Panels Bootstrap documentation Syntax %= panel ($title, %has, begin $body % end) $title Usually mandatory, but can be omitted if there are no other arguments to the "panel". Otherwise, if you don't want a title, set it "undef". $body Optional (but panels are not much use without it). The html inside the "panel". Examples %= panel
    %= panel undef ,=> begin

    A short text.

    % end

    A short text.

    %= panel 'The Header' => begin

    A short text.

    % end

    The Header

    A short text.

    %= panel 'Panel 5', success, begin

    A short text.

    % end

    Panel 5

    A short text.

    Tables Bootstrap documentation Syntax %= table ($title,) %table_has, panel => { %panel_has }, begin $body % end $title Optional. If set the table will be wrapped in a panel, and the table replaces the body in the panel. $body Mandatory. "thead", "td" and so on. "panel => { %panel_has }" Optional if the table has a $title, otherwise without use. Examples <%= table begin %> Table 1 <% end %>
    Table 1
    %= table hover, striped, condensed, begin Table 2 % end
    Table 2
    %= table 'Heading Table 4', panel => { success }, condensed, id => 'the-table', begin Table 4 % end

    Heading Table 4

    Table 4
    OPTIONS Some options are available: $app->plugin('BootstrapHelpers', { tag_prefix => 'bs', short_strappings_prefix => 'set', init_short_strappings => 1, icons => { class => 'glyphicon' formatter => 'glyphicon-%s', }, }); tag_prefix Default: "undef" If you want to you change the name of the tag helpers, by applying a prefix. These are not aliases; by setting a prefix the original names are no longer available. The following rules are used: * If the option is missing, or is "undef", there is no prefix. * If the option is set to the empty string, the prefix is "_". That is, "panel" is now used as "_panel". * If the option is set to any other string, the prefix is that string. If you set "tag_prefix => 'bs'", then "panel" is now used as "bspanel". short_strappings_prefix Default: "undef" This is similar to "tag_prefix", but is instead applied to the short form strappings. The same rules applies. init_short_strappings Default: 1 If you don't want the short form of strappings setup at all, set this option to a defined but false value. All functionality is available, but instead of "warning" you must now use "__warning => 1". With short form turned off, sizes are still only supported in long form: "__xsmall", "__small", "__medium" and "__large". The Bootstrap abbreviations ("xs" - "lg") are not used. icons Default: not set By setting these keys you activate the "icon" helper. You can pick any icon pack that sets one main class and one subclass to create an icon. "class" This is the main icon class. If you use the glyphicon pack, this should be set to 'glyphicon'. "formatter" This creates the specific icon class. If you use the glyphicon pack, this should be set to 'glyphicon-%s', where the '%s' will be replaced by the icon name you give the "icon" helper. AUTHOR Erik Carlsson COPYRIGHT Copyright 2014- Erik Carlsson Bootstrap itself is (c) Twitter. See their license information . Mojolicious::Plugin::BootstrapHelpers is third party software, and is not endorsed by Twitter. LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.