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-address', prepend => '@'], large # ...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 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[] An array reference (ordering significant) %name A hash (ordering not significant) $name{} A hash reference (ordering not significant) (optional) Anything inside parenthesis is optional HELPERS Panels Bootstrap documentation Syntax %= panel ($title, ((%strappings,) 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". %strappings Optional. Any strapping you want applied to the "panel". $body Optional (but panels are not much use without it). The html inside the "panel". Examples No body, no title %= panel
The class is set to "panel-default", by default. Body, no title %= panel undef ,=> begin

A short text.

% end

A short text.

If you want a panel without title, set the title to "undef". Note that you can't use a regular fat comma since that would turn undef into a string. A normal comma is of course also ok. Body and title %= panel 'The header' => begin

A short text.

% end

The Header

A short text.

Body and title, with context %= panel 'Panel 5', success, begin

A short text.

% end

Panel 5

A short text.

Here, the "success" strapping applies ".panel-success" to the panel. Form groups Bootstrap documentation Syntax %= formgroup ($labeltext,) %arguments %= formgroup %arguments, begin $labeltext % end # %arguments: (cols => $size_definitions{}) (%group_strappings) $fieldtype => $field_setting[], # $field_setting[] $name, ($value,) (%field_arguments) # $size_definitions{} { $size => [ $label_columns, $input_columns ](, ...) }, # %field_arguments (%html_attributes,) (prepend => $to_prepend,) (append => $to_append,) (%field_strappings) $labeltext Optional. It is either the first argument, or placed in the body. It creates a "label" element before the "input". %arguments Mandatory: "cols => $size_definitions{}" Optional key-value pair. It is only used when the "form" is a ".form-horizontal". You can define the widths for one or more or all of the sizes. $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. $input_columns Mandatory. The number of columns used for the input field for that size. %group_strappings Optional hash. One or more strappings you want applied to the ".form-group" element. $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". (Behavior if having more than one is not defined.) $field_setting[] Mandatory. An array reference: $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 $field_arguments{'id'} exists then that is used for the "id" instead. $value Optional. It is the same as setting $field_arguments{'value'}. (But don't do both for the same field.) %field_arguments Optional. A hash: %html_attributes Optional. All html attributes you want to set on the "input". "prepend => $to_prepend" Optional key-value pair. Can be used with "append". They are used to create input groups . $prepend This string is placed directly in front of the "input". "append => $to_append" Optional key-value pair. Can be used with "prepend". $append This string is placed directly after the "input". %field_strappings Optional. All strappings you want applied to the "input". Examples Basic form group %= formgroup 'Text test 1', text_field => ['test_text']
The first item in the array ref is used for both "id" and "name". Except... Input group (before), and large input field %= formgroup 'Text test 4', text_field => ['test-text', append => '.00', large]
.00
Strappings can also be used in this context. Here "large" applies ".input-lg". If the input name (the first item in the text_field array ref) contains dashes, those are replaced (in the "name") to underscores. Input group (before and after), and with value %= formgroup 'Text test 5', text_field => ['test_text', '200', prepend => '$', append => '.00']
$ .00
Here, the second item in the "text_field" array reference is a value that populates the "input". Large input group %= formgroup 'Text test 6', text_field => ['test_text'], large
Note the difference with the earlier example. Here "large" is outside the "text_field" array reference, and therefore ".form-group-lg" is applied to the form group. Horizontal form groups %= formgroup 'Text test 8', text_field => ['test_text'], cols => { medium => [2, 10], small => [4, 8] }
If the "form" is ".form-horizontal", you can set the column widths with the "cols" attribute. The first item in each array ref is for the label, and the second for the input. (Note that in this context, "medium" and "large" are not short form strappings. Those don't take arguments.) Buttons Bootstrap documentation Syntax %= button $button_text(, $url[])(, %arguments) # %arguments (%html_attributes,) (%strappings) $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. %arguments Optional hash: %html_attributes Optional hash of any html attributes you want to set on the button/link. %strappings Optional hash. Any strappings you want to set on the button/link. Examples %= button 'The example 5' => large, warning An ordinary button, with applied strappings. %= button 'The example 1' => ['http://www.example.com/'], small The example 1 With a url the button turns into a link. Tables Syntax %= table ($title,) (%arguments,) begin $body % end # %arguments (%html_attributes,) (%strappings,) (panel => $strappings{}) $title Optional. If set the table will be wrapped in a panel. The table replaces the body. %arguments Optional hash: %html_attributes Optional. A hash of html attributes you want applied to the table. %strappings Optional. A hash of the strappings to apply to the table. "panel => $strappings{}" An optional key-value pair: $strappings{} A hash reference containing any strapping you want to set on the panel. Examples Bootstrap documentation <%= table begin %> Table 1 <% end %>
Table 1
A basic table. %= table hover, striped, condensed, begin Table 2 % end
Table 2
Several classes applied to the table. %= table 'Heading Table 4', panel => { success }, condensed, id => 'the-table', begin Table 4 % end

Heading Table 4

Table 4
A "condensed" table with an "id" wrapped in a "success" panel. OPTIONS Some options are available: $app->plugin('BootstrapHelpers', { tag_prefix => 'bs', short_strappings_prefix => 'set', init_short_strappings => 1, }); 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 followed by "_". If you set "tag_prefix => 'bs'", then "panel" is now used as "bs_panel". 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. 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.