NAME
Mojolicious::Plugin::BootstrapHelpers - Type less bootstrap
SYNOPSIS
# Mojolicious
$self->plugin('BootstrapHelpers');
# ::Lite
plugin 'BootstrapHelpers';
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.
Only Perl 5.20+ is supported (thanks to postderef). This might change.
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'
Shortcuts
There are several shortcuts for 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" shortcut to a panel, it becomes
"panel-info", but when applied to a button it becomes "btn-info".
For sizes, you can only use "xsmall", "small", "medium" and "large",
they are shortened to the Bootstrap type classes.
The following shortcuts are available:
xsmall default striped
small primary bordered
medium success hover
large info condensed
warning responsive
danger
See below for usage. Important: You can't follow a shortcut with a fat
comma ("=>"). The fat comma auto-quotes the shortcut, and then the
shortcut is not a shortcut anymore.
If there is no corresponding class for the element you add the shortcut
to it is automatically removed.
Panels
Bootstrap documentation
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.
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.
The first shortcut, "success". This applies ".panel-success".
Form groups
Bootstrap documentation
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
Shortcuts 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
The (optional) second item in the array ref is the value, if any, that
should populate the input tag.
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 ref, 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.
Buttons
Bootstrap documentation
%= button 'The example 5' => large, warning
An ordinary button, with applied shortcuts.
%= button 'The example 1' => ['http://www.example.com/'], small
The example 1
If the first argument after the button text is an array ref, it is used
to populate "href" and turns the button into a link. The url is handed
off url_for, so this is basically link_to with Bootstrap classes.
Tables
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.
OPTIONS
Some options are available:
$app->plugin('BootstrapHelpers', {
tag_prefix => 'bs',
shortcut_prefix => 'set',
init_shortcuts => 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 using the prefix to 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".
shortcut_prefix
Default: "undef"
This is similar to "tag_prefix", but is instead applied to the
shortcuts. The same rules applies.
init_shortcuts
Default: 1
If you don't want the shortcuts 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". That is why they are shortcuts.
AUTHOR
Erik Carlsson
COPYRIGHT
Copyright 2014- Erik Carlsson
LICENSE
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.