NAME

Mojolicious::Plugin::TagHelpers - Tag helpers plugin

SYNOPSIS

  # Mojolicious
  $app->plugin('TagHelpers');

  # Mojolicious::Lite
  plugin 'TagHelpers';

DESCRIPTION

Mojolicious::Plugin::TagHelpers is a collection of HTML tag helpers for Mojolicious, based on the HTML Living Standard.

Most form helpers can automatically pick up previous input values and will show them as default. You can also use "param" in Mojolicious::Plugin::DefaultHelpers to set them manually and let necessary attributes always be generated automatically.

  % param country => 'germany' unless param 'country';
  <%= radio_button country => 'germany' %> Germany
  <%= radio_button country => 'france'  %> France
  <%= radio_button country => 'uk'      %> UK

For fields that failed validation with "validation" in Mojolicious::Plugin::DefaultHelpers the field-with-error class will be automatically added through "tag_with_error", to make styling with CSS easier.

  <input class="field-with-error" name="age" type="text" value="250">

This is a core plugin, that means it is always enabled and its code a good example for learning how to build new plugins, you're welcome to fork it.

See "PLUGINS" in Mojolicious::Plugins for a list of plugins that are available by default.

HELPERS

Mojolicious::Plugin::TagHelpers implements the following helpers.

asset_tag

  %= asset_tag '/app.js'
  %= asset_tag '/app.js', async => 'async'

Generate script, link or img tag for static asset.

button_to

  %= button_to Test => 'some_get_route'
  %= button_to Test => some_get_route => {id => 23} => (class => 'menu')
  %= button_to Test => 'http://example.com/test' => (class => 'menu')
  %= button_to Remove => 'some_delete_route'

Generate portable form tag with "form_for", containing a single button.

  <form action="/path/to/get/route">
    <input type="submit" value="Test">
  </form>
  <form action="/path/to/get/route/23" class="menu">
    <input type="submit" value="Test">
  </form>
  <form action="http://example.com/test" class="menu">
    <input type="submit" value="Test">
  </form>
  <form action="/path/to/delete/route?_method=DELETE" method="POST">
    <input type="submit" value="Remove">
  </form>

check_box

  %= check_box 'employed'
  %= check_box employed => 1
  %= check_box employed => 1, checked => undef, id => 'foo'

Generate input tag of type checkbox. Previous input values will automatically get picked up and shown as default.

  <input name="employed" type="checkbox">
  <input name="employed" type="checkbox" value="1">
  <input checked id="foo" name="employed" type="checkbox" value="1">

color_field

  %= color_field 'background'
  %= color_field background => '#ffffff'
  %= color_field background => '#ffffff', id => 'foo'

Generate input tag of type color. Previous input values will automatically get picked up and shown as default.

  <input name="background" type="color">
  <input name="background" type="color" value="#ffffff">
  <input id="foo" name="background" type="color" value="#ffffff">

csrf_button_to

  %= csrf_button_to Remove => 'some_delete_route'

Same as "button_to", but also includes a "csrf_field".

  <form action="/path/to/delete/route?_method=DELETE" method="POST">
    <input name="csrf_token" type="hidden" value="fa6a08...">
    <input type="submit" value="Remove">
  </form>

csrf_field

  %= csrf_field

Generate input tag of type hidden with "csrf_token" in Mojolicious::Plugin::DefaultHelpers.

  <input name="csrf_token" type="hidden" value="fa6a08...">

date_field

  %= date_field 'end'
  %= date_field end => '2012-12-21'
  %= date_field end => '2012-12-21', id => 'foo'

Generate input tag of type date. Previous input values will automatically get picked up and shown as default.

  <input name="end" type="date">
  <input name="end" type="date" value="2012-12-21">
  <input id="foo" name="end" type="date" value="2012-12-21">

datetime_field

  %= datetime_field 'end'
  %= datetime_field end => '2012-12-21T23:59:59'
  %= datetime_field end => '2012-12-21T23:59:59', id => 'foo'

Generate input tag of type datetime-local. Previous input values will automatically get picked up and shown as default.

  <input name="end" type="datetime-local">
  <input name="end" type="datetime-local" value="2012-12-21T23:59:59">
  <input id="foo" name="end" type="datetime-local" value="2012-12-21T23:59:59">

email_field

  %= email_field 'notify'
  %= email_field notify => 'nospam@example.com'
  %= email_field notify => 'nospam@example.com', id => 'foo'

Generate input tag of type email. Previous input values will automatically get picked up and shown as default.

  <input name="notify" type="email">
  <input name="notify" type="email" value="nospam@example.com">
  <input id="foo" name="notify" type="email" value="nospam@example.com">

favicon

  %= favicon
  %= favicon '/favicon.ico';

Generate link tag for favicon, defaulting to the one that comes bundled with Mojolicious.

  <link rel="icon" href="/mojo/favicon.ico">
  <link rel="icon" href="/favicon.ico">

file_field

  %= file_field 'avatar'
  %= file_field 'avatar', id => 'foo'

Generate input tag of type file.

  <input name="avatar" type="file">
  <input id="foo" name="avatar" type="file">

form_for

  %= form_for login => begin
    %= text_field 'first_name'
    %= submit_button
  % end
  %= form_for login => {format => 'txt'} => (method => 'POST') => begin
    %= text_field 'first_name'
    %= submit_button
  % end
  %= form_for '/login' => (enctype => 'multipart/form-data') => begin
    %= text_field 'first_name', disabled => 'disabled'
    %= submit_button
  % end
  %= form_for 'http://example.com/login' => (method => 'POST') => begin
    %= text_field 'first_name'
    %= submit_button
  % end
  %= form_for some_delete_route => begin
    %= submit_button 'Remove'
  % end

Generate portable form tag with "url_for" in Mojolicious::Controller. For routes that do not allow GET, a method attribute with the value POST will be automatically added. And for methods other than GET or POST, an _method query parameter will be added as well.

  <form action="/path/to/login">
    <input name="first_name" type="text">
    <input type="submit" value="Ok">
  </form>
  <form action="/path/to/login.txt" method="POST">
    <input name="first_name" type="text">
    <input type="submit" value="Ok">
  </form>
  <form action="/path/to/login" enctype="multipart/form-data">
    <input disabled="disabled" name="first_name" type="text">
    <input type="submit" value="Ok">
  </form>
  <form action="http://example.com/login" method="POST">
    <input name="first_name" type="text">
    <input type="submit" value="Ok">
  </form>
  <form action="/path/to/delete/route?_method=DELETE" method="POST">
    <input type="submit" value="Remove">
  </form>

hidden_field

  %= hidden_field foo => 'bar'
  %= hidden_field foo => 'bar', id => 'bar'

Generate input tag of type hidden.

  <input name="foo" type="hidden" value="bar">
  <input id="bar" name="foo" type="hidden" value="bar">

image

  %= image '/images/foo.png'
  %= image '/images/foo.png', alt => 'Foo'

Generate portable img tag.

  <img src="/path/to/images/foo.png">
  <img alt="Foo" src="/path/to/images/foo.png">

input_tag

  %= input_tag 'first_name'
  %= input_tag first_name => 'Default'
  %= input_tag 'employed', type => 'checkbox'

Generate input tag. Previous input values will automatically get picked up and shown as default.

  <input name="first_name">
  <input name="first_name" value="Default">
  <input name="employed" type="checkbox">

javascript

  %= javascript '/script.js'
  %= javascript '/script.js', defer => undef
  %= javascript begin
    const a = 'b';
  % end

Generate portable script tag for JavaScript asset.

  <script src="/path/to/script.js"></script>
  <script defer src="/path/to/script.js"></script>
  <script><![CDATA[
    const a = 'b';
  ]]></script>

label_for

  %= label_for first_name => 'First name'
  %= label_for first_name => 'First name', class => 'user'
  %= label_for first_name => begin
    First name
  % end
  %= label_for first_name => (class => 'user') => begin
    First name
  % end

Generate label tag.

  <label for="first_name">First name</label>
  <label class="user" for="first_name">First name</label>
  <label for="first_name">
    First name
  </label>
  <label class="user" for="first_name">
    First name
  </label>
  %= link_to Home => 'index'
  %= link_to Home => 'index' => {format => 'txt'} => (class => 'menu')
  %= link_to index => {format => 'txt'} => (class => 'menu') => begin
    Home
  % end
  %= link_to Contact => 'mailto:sri@example.com'
  <%= link_to index => begin %>Home<% end %>
  <%= link_to '/file.txt' => begin %>File<% end %>
  <%= link_to 'https://mojolicious.org' => begin %>Mojolicious<% end %>
  <%= link_to url_for->query(foo => 'bar')->to_abs => begin %>Retry<% end %>

Generate portable a tag with "url_for" in Mojolicious::Controller, defaults to using the capitalized link target as content.

  <a href="/path/to/index">Home</a>
  <a class="menu" href="/path/to/index.txt">Home</a>
  <a class="menu" href="/path/to/index.txt">
    Home
  </a>
  <a href="mailto:sri@example.com">Contact</a>
  <a href="/path/to/index">Home</a>
  <a href="/path/to/file.txt">File</a>
  <a href="https://mojolicious.org">Mojolicious</a>
  <a href="http://127.0.0.1:3000/current/path?foo=bar">Retry</a>

The first argument to link_to is the link content, except when the final argument is Perl code such as a template block (created with the begin and end keywords); in that case, the link content is omitted at the start of the argument list, and the block will become the link content.

month_field

  %= month_field 'vacation'
  %= month_field vacation => '2012-12'
  %= month_field vacation => '2012-12', id => 'foo'

Generate input tag of type month. Previous input values will automatically get picked up and shown as default.

  <input name="vacation" type="month">
  <input name="vacation" type="month" value="2012-12">
  <input id="foo" name="vacation" type="month" value="2012-12">

number_field

  %= number_field 'age'
  %= number_field age => 25
  %= number_field age => 25, id => 'foo', min => 0, max => 200

Generate input tag of type number. Previous input values will automatically get picked up and shown as default.

  <input name="age" type="number">
  <input name="age" type="number" value="25">
  <input id="foo" max="200" min="0" name="age" type="number" value="25">

password_field

  %= password_field 'pass'
  %= password_field 'pass', id => 'foo'

Generate input tag of type password.

  <input name="pass" type="password">
  <input id="foo" name="pass" type="password">

radio_button

  %= radio_button 'test'
  %= radio_button country => 'germany'
  %= radio_button country => 'germany', checked => undef, id => 'foo'

Generate input tag of type radio. Previous input values will automatically get picked up and shown as default.

  <input name="test" type="radio">
  <input name="country" type="radio" value="germany">
  <input checked id="foo" name="country" type="radio" value="germany">

range_field

  %= range_field 'age'
  %= range_field age => 25
  %= range_field age => 25, id => 'foo', min => 0, max => 200

Generate input tag of type range. Previous input values will automatically get picked up and shown as default.

  <input name="age" type="range">
  <input name="age" type="range" value="25">
  <input id="foo" max="200" min="200" name="age" type="range" value="25">

search_field

  %= search_field 'q'
  %= search_field q => 'perl'
  %= search_field q => 'perl', id => 'foo'

Generate input tag of type search. Previous input values will automatically get picked up and shown as default.

  <input name="q" type="search">
  <input name="q" type="search" value="perl">
  <input id="foo" name="q" type="search" value="perl">

select_field

  %= select_field country => ['de', 'en']
  %= select_field country => [[Germany => 'de'], 'en'], id => 'eu'
  %= select_field country => [[Germany => 'de', selected => 'selected'], 'en']
  %= select_field country => [c(EU => [[Germany => 'de'], 'en'], id => 'eu')]
  %= select_field country => [c(EU => ['de', 'en']), c(Asia => ['cn', 'jp'])]

Generate select and option tags from array references and optgroup tags from Mojo::Collection objects. Previous input values will automatically get picked up and shown as default.

  <select name="country">
    <option value="de">de</option>
    <option value="en">en</option>
  </select>
  <select id="eu" name="country">
    <option value="de">Germany</option>
    <option value="en">en</option>
  </select>
  <select name="country">
    <option selected="selected" value="de">Germany</option>
    <option value="en">en</option>
  </select>
  <select name="country">
    <optgroup id="eu" label="EU">
      <option value="de">Germany</option>
      <option value="en">en</option>
    </optgroup>
  </select>
  <select name="country">
    <optgroup label="EU">
      <option value="de">de</option>
      <option value="en">en</option>
    </optgroup>
    <optgroup label="Asia">
      <option value="cn">cn</option>
      <option value="jp">jp</option>
    </optgroup>
  </select>

stylesheet

  %= stylesheet '/foo.css'
  %= stylesheet '/foo.css', title => 'Foo style'
  %= stylesheet begin
    body {color: #000}
  % end

Generate portable style or link tag for CSS asset.

  <link href="/path/to/foo.css" rel="stylesheet">
  <link href="/path/to/foo.css" rel="stylesheet" title="Foo style">
  <style><![CDATA[
    body {color: #000}
  ]]></style>

submit_button

  %= submit_button
  %= submit_button 'Ok!', id => 'foo'

Generate input tag of type submit.

  <input type="submit" value="Ok">
  <input id="foo" type="submit" value="Ok!">

t

  %= t div => 'test & 123'

Alias for "tag".

  <div>test &amp; 123</div>

tag

  %= tag 'br'
  %= tag 'div'
  %= tag 'div', id => 'foo', hidden => undef
  %= tag 'div', 'test & 123'
  %= tag 'div', id => 'foo', 'test & 123'
  %= tag 'div', data => {my_id => 1, Name => 'test'}, 'test & 123'
  %= tag div => begin
    test & 123
  % end
  <%= tag div => (id => 'foo') => begin %>test & 123<% end %>

Alias for "new_tag" in Mojo::DOM.

  <br>
  <div></div>
  <div id="foo" hidden></div>
  <div>test &amp; 123</div>
  <div id="foo">test &amp; 123</div>
  <div data-my-id="1" data-name="test">test &amp; 123</div>
  <div>
    test & 123
  </div>
  <div id="foo">test & 123</div>

Very useful for reuse in more specific tag helpers.

  my $output = $c->tag('meta');
  my $output = $c->tag('meta', charset => 'UTF-8');
  my $output = $c->tag('div', '<p>This will be escaped</p>');
  my $output = $c->tag('div', sub { '<p>This will not be escaped</p>' });

Results are automatically wrapped in Mojo::ByteStream objects to prevent accidental double escaping in ep templates.

tag_with_error

  %= tag_with_error 'input', class => 'foo'

Same as "tag", but adds the class field-with-error.

  <input class="foo field-with-error">

tel_field

  %= tel_field 'work'
  %= tel_field work => '123456789'
  %= tel_field work => '123456789', id => 'foo'

Generate input tag of type tel. Previous input values will automatically get picked up and shown as default.

  <input name="work" type="tel">
  <input name="work" type="tel" value="123456789">
  <input id="foo" name="work" type="tel" value="123456789">

text_area

  %= text_area 'story'
  %= text_area 'story', cols => 40
  %= text_area story => 'Default', cols => 40
  %= text_area story => (cols => 40) => begin
    Default
  % end

Generate textarea tag. Previous input values will automatically get picked up and shown as default.

  <textarea name="story"></textarea>
  <textarea cols="40" name="story"></textarea>
  <textarea cols="40" name="story">Default</textarea>
  <textarea cols="40" name="story">
    Default
  </textarea>

text_field

  %= text_field 'first_name'
  %= text_field first_name => 'Default'
  %= text_field first_name => 'Default', class => 'user'

Generate input tag of type text. Previous input values will automatically get picked up and shown as default.

  <input name="first_name" type="text">
  <input name="first_name" type="text" value="Default">
  <input class="user" name="first_name" type="text" value="Default">

time_field

  %= time_field 'start'
  %= time_field start => '23:59:59'
  %= time_field start => '23:59:59', id => 'foo'

Generate input tag of type time. Previous input values will automatically get picked up and shown as default.

  <input name="start" type="time">
  <input name="start" type="time" value="23:59:59">
  <input id="foo" name="start" type="time" value="23:59:59">

url_field

  %= url_field 'address'
  %= url_field address => 'https://mojolicious.org'
  %= url_field address => 'https://mojolicious.org', id => 'foo'

Generate input tag of type url. Previous input values will automatically get picked up and shown as default.

  <input name="address" type="url">
  <input name="address" type="url" value="https://mojolicious.org">
  <input id="foo" name="address" type="url" value="https://mojolicious.org">

week_field

  %= week_field 'vacation'
  %= week_field vacation => '2012-W17'
  %= week_field vacation => '2012-W17', id => 'foo'

Generate input tag of type week. Previous input values will automatically get picked up and shown as default.

  <input name="vacation" type="week">
  <input name="vacation" type="week" value="2012-W17">
  <input id="foo" name="vacation" type="week" value="2012-W17">

METHODS

Mojolicious::Plugin::TagHelpers inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

  $plugin->register(Mojolicious->new);

Register helpers in Mojolicious application.

SEE ALSO

Mojolicious, Mojolicious::Guides, https://mojolicious.org.