Mojolicious::Plugin::TagHelpers(3pm)

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 <https://html.spec.whatwg.org>.

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
  %= 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>.