Mojolicious::Plugin::BootstrapHelpers - Type less bootstrap
# Mojolicious $self->plugin('BootstrapHelpers'); # ::Lite plugin 'BootstrapHelpers'; # Meanwhile, somewhere in a template... %= formgroup 'Email' => text_field => ['email-address', prepend => '@'], large # ...that renders into <div class="form-group form-group-lg"> <label class="control-label" for="email-address">Email</label> <div class="input-group"> <span class="input-group-addon">@</span> <input class="form-control" id="email-address" name="email_address" type="text" /> </div> </div>
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).
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.
If you don't know what Bootstrap is, see http://www.getbootstrap.com/ 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 <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"> # or (if you want to use the theme) %= bootstrap 'theme' <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"> <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"> # And the javascript %= bootstrap 'js' <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script> # Or just: %= bootstrap 'all' <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"> <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"> <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
It is also possible to automatically include jQuery (2.*)
%= bootstrap 'jsq' <script src="//code.jquery.com/jquery-2.1.1.min.js"></script> <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script> %= bootstrap 'allq' <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"> <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"> <script src="//code.jquery.com/jquery-2.1.1.min.js"></script> <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
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.
info
panel-info
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.
xsmall
small
medium
large
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.
The short form is recommended for readability, but it does setup several helpers in your templates. You can turn off the short forms, see init_short_strappings.
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)
Bootstrap documentation
%= panel %= 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.
panel
undef
%strappings
Optional hash. Any strapping you want applied to the panel.
$body
Optional (but panels are not much use without it). The html inside the panel.
No body, no title
%= panel <div class="panel panel-default"> <div class="panel-body"> </div> </div>
The class is set to panel-default, by default.
panel-default
Body, no title
%= panel undef ,=> begin <p>A short text.</p> % end <div class="panel panel-default"> <div class="panel-body"> <p>A short text.</p> </div> </div>
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 <p>A short text.</p> % end <div class="panel panel-default"> <div class="panel-heading"> <h3 class="panel-title">The Header</h3> </div> <div class="panel-body"> <p>A short text.</p> </div> </div>
Body and title, with context
%= panel 'Panel 5', success, begin <p>A short text.</p> % end <div class="panel panel-success"> <div class="panel-heading"> <h3 class="panel-title">Panel 5</h3> </div> <div class="panel-body"> <p>A short text.</p> </div> </div>
Here, the success strapping applies .panel-success to the panel.
success
.panel-success
%= formgroup $labeltext, %arguments %= formgroup %arguments, begin $labeltext % end # %arguments: cols => { $size => [ $label_columns, $input_columns ], ... }, %strappings $fieldtype => $field_setting[], # $field_setting[] $name, $value, %field_arguments # %field_arguments %html_attributes, %prepend, %append, %strappings
$labeltext
Mandatory. It is either the first argument, or placed in the body.
%arguments
Mandatory. A hash:
cols
Optional hash reference. It is only used when the form is a .form-horizontal. $size is one of xsmall, small, medium, or large. $size takes a two item array reference: $label_columns is the number of columns that should be used by the label for that size, and $input_columns is the number of columns used for the input field for that size.
form
.form-horizontal
$size
$label_columns
$input_columns
You can defined the widths for one or more or all of the sizes.
Optional hash. One or more strappings you want applied to the .form-group element.
.form-group
$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.
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.)
formgroup
$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.
id
name
$field_arguments{'id'}
$value
Optional. It is the same as setting $field_arguments{'value'}. (But don't do both for the same field.)
$field_arguments{'value'}
%field_arguments
Optional. A hash:
%html_attributes
Optional. All html attributes you want to set on the input.
input
%prepend and %append
%prepend
%append
Optional. Can be used individually or together. They are used to create input groups.
Optional. All strappings you want applied to the input.
Basic form group
%= formgroup 'Text test 1', text_field => ['test_text'] <div class="form-group"> <label class="control-label" for="test_text">Text test 1</label> <input class="form-control" id="test_text" name="test_text" type="text" /> </div>
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] <div class="form-group"> <label class="control-label" for="test_text">Text test 4</label> <div class="input-group"> <input class="form-control input-lg" id="test-text" name="test_text" type="text" /> <span class="input-group-addon">.00</span> </div> </div>
Strappings can also be used in this context. Here large applies .input-lg.
.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'] <div class="form-group"> <label class="control-label" for="test_text">Text test 5</label> <div class="input-group"> <span class="input-group-addon">$</span> <input class="form-control" id="test_text" name="test_text" type="text" value="200" /> <span class="input-group-addon">.00</span> </div> </div>
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 <div class="form-group form-group-lg"> <label class="control-label" for="test_text">Text test 6</label> <input class="form-control" id="test_text" name="test_text" type="text" /> </div>
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.
.form-group-lg
Horizontal form groups
%= formgroup 'Text test 8', text_field => ['test_text'], cols => { medium => [2, 10], small => [4, 8] } <div class="form-group"> <label class="control-label col-md-2 col-sm-4" for="test_text">Text test 8</label> <div class="col-md-10 col-sm-8"> <input class="form-control" id="test_text" name="test_text" type="text" /> </div> </div>
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.)
%= 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.
Optional hash.
Optional hash of any html attributes you want to set on the button/link.
Optional hash. Any strappings you want to set on the button/link.
%= button 'The example 5' => large, warning <button class="btn btn-lg btn-warning">The example 5</button>
An ordinary button, with applied strappings.
%= button 'The example 1' => ['http://www.example.com/'], small <a class="btn btn-sm" href="http://www.example.com/">The example 1</a>
With a url the button turns into a link.
%= table $title, %arguments, begin $body % end # %arguments %strappings panel => $strappings{}
Optional. If set the table will be wrapped in a panel. The table replaces the body.
Optional hash:
Optional. A hash of the strappings to apply to the table.
panel => $strappings{}
An optional key-value pair. $strappings{} is hash reference containing any strapping you want to set on the panel.
<%= table begin %> <tr><td>Table 1</td></tr> <% end %> <table class="table"> <tr><td>Table 1</td></tr> </table>
A basic table.
%= table hover, striped, condensed, begin <tr><td>Table 2</td></tr> % end <table class="table table-condensed table-hover table-striped"> <tr><td>Table 2</td></tr> </table>
Several classes applied to the table.
%= table 'Heading Table 4', panel => { success }, condensed, begin <tr><td>Table 4</td></tr> % end <div class="panel panel-success"> <div class="panel-heading"> <h3 class="panel-title">Heading Table 4</h3> </div> <table class="table table-condensed"> <tr><td>Table 4</td></tr> </table> </div>
A condensed table wrapped in a success panel.
condensed
Some options are available:
$app->plugin('BootstrapHelpers', { tag_prefix => 'bs', short_strappings_prefix => 'set', init_short_strappings => 1, });
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.
_
_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.
tag_prefix => 'bs'
bs_panel
This is similar to tag_prefix, but is instead applied to the short form strappings. The same rules applies.
tag_prefix
Default: 1
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>>.
warning
<__warning =
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.
__xsmall
__small
__medium
__large
xs
lg
Erik Carlsson <csson@cpan.org>
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.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Mojolicious::Plugin::BootstrapHelpers, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious::Plugin::BootstrapHelpers
CPAN shell
perl -MCPAN -e shell install Mojolicious::Plugin::BootstrapHelpers
For more information on module installation, please visit the detailed CPAN module installation guide.