модуль ActionView::Helpers::TagHelper

Подключенные модули:: ActionView::Helpers::CaptureHelper, ActionView::Helpers::OutputSafetyHelper

Вспомогательные методы тегов Action View

Предоставляет методы для программной генерации HTML-тегов как в современном стиле построителя, совместимом с HTML5, так и в устаревшем формате тегов, совместимом с XHTML.

Константы

ARIA_PREFIXES
BOOLEAN_ATTRIBUTES
DATA_PREFIXES
PRE_CONTENT_STRINGS
TAG_TYPES

Общедоступные методы класса

build_tag_values (*args) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 577
def build_tag_values(*args)
  tag_values = []

  args.each do |tag_value|
    case tag_value
    when Hash
      tag_value.each do |key, val|
        tag_values << key.to_s if val && key.present?
      end
    when Array
      tag_values.concat build_tag_values(*tag_value)
    else
      tag_values << tag_value.to_s if tag_value.present?
    end
  end

  tag_values
end

ensure_valid_html5_tag_name (name) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 572
def ensure_valid_html5_tag_name(name)
  raise ArgumentError, "Invalid HTML5 tag name: #{name.inspect}" unless /\A[a-zA-Z][^\s\/>]*\z/.match?(name)
end

Общедоступные методы экземпляра

cdata_section (content) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 555
def cdata_section(content)
  splitted = content.to_s.gsub(/\]\]>/, "]]]]><![CDATA[>")
  "<![CDATA[#{splitted}]]>".html_safe
end

Возвращает раздел CDATA с указанным content. Разделы CDATA используются для экранирования блоков текста, содержащих символы, которые иначе распознавались бы как разметка. Разделы CDATA начинаются со строки <![CDATA[ и заканчиваются строкой ]]> (которую они не могут содержать).

cdata_section("<hello world>")
# => <![CDATA[<hello world>]]>

cdata_section(File.read("hello_world.txt"))
# => <![CDATA[<hello from a text file]]>

cdata_section("hello]]>world")
# => <![CDATA[hello]]]]><![CDATA[>world]]>

class_names (*args)

Псевдоним для: token_list

content_tag (name, content_or_options_with_block = nil, options = nil, escape = true, &block) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 513
def content_tag(name, content_or_options_with_block = nil, options = nil, escape = true, &block)
  ensure_valid_html5_tag_name(name)

  if block_given?
    options = content_or_options_with_block if content_or_options_with_block.is_a?(Hash)
    tag_builder.content_tag_string(name, capture(&block), options, escape)
  else
    tag_builder.content_tag_string(name, content_or_options_with_block, options, escape)
  end
end

Возвращает блочный HTML-тег типа name, обрамляющий content. Чтобы добавить HTML-атрибуты, передайте хеш атрибутов в options. Вместо передачи содержимого в качестве аргумента можно использовать блок; в этом случае передайте options в качестве второго параметра. Установите escape в false, чтобы отключить экранирование. Примечание: это устаревший синтаксис; подробности см. в описании метода tag.

Параметры

Хеш options можно использовать с атрибутами без значения, такими как (disabled и readonly), которым можно присвоить значение true в хеше options. В качестве имен атрибутов можно использовать символы или строки.

Примеры

content_tag(:p, "Hello world!")
 # => <p>Hello world!</p>
content_tag(:div, content_tag(:p, "Hello world!"), class: "strong")
 # => <div class="strong"><p>Hello world!</p></div>
content_tag(:div, "Hello world!", class: ["strong", "highlight"])
 # => <div class="strong highlight">Hello world!</div>
content_tag(:div, "Hello world!", class: ["strong", { highlight: current_user.admin? }])
 # => <div class="strong highlight">Hello world!</div>
content_tag("select", options, multiple: true)
 # => <select multiple="multiple">...options...</select>

<%= content_tag :div, class: "strong" do -%>
  Hello world!
<% end -%>
 # => <div class="strong">Hello world!</div>

escape_once (html) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 567
def escape_once(html)
  ERB::Util.html_escape_once(html)
end

Возвращает экранированную версию html, не затрагивая уже экранированные сущности.

escape_once("1 < 2 &amp; 3")
# => "1 &lt; 2 &amp; 3"

escape_once("&lt;&lt; Accept & Checkout")
# => "&lt;&lt; Accept &amp; Checkout"

tag (name = nil, options = nil, open = false, escape = true) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 476
def tag(name = nil, options = nil, open = false, escape = true)
  if name.nil?
    tag_builder
  else
    ensure_valid_html5_tag_name(name)
    "<#{name}#{tag_builder.tag_options(options, escape) if options}#{open ? ">" : " />"}".html_safe
  end
end

Возвращает HTML-тег.

Создание HTML-тегов

Создает теги, совместимые с HTML5, с помощью прокси-объекта тегов. Каждый тег можно создать следующим образом:

tag.<tag name>(optional content, options)

где именем тега может быть, например, br, div, section, article или любой другой тег.

Передача содержимого

Tags можно передать содержимое для включения в тег:

tag.h1 'All titles fit to print' # => <h1>All titles fit to print</h1>

tag.div tag.p('Hello world!')  # => <div><p>Hello world!</p></div>

Содержимое также можно захватить с помощью блока, что удобно в шаблонах:

<%= tag.p do %>
  The next great American novel starts here.
<% end %>
# => <p>The next great American novel starts here.</p>

Параметры

Используйте параметры с ключами-символами, чтобы добавить атрибуты к создаваемому тегу.

tag.section class: %w( kitties puppies )
# => <section class="kitties puppies"></section>

tag.section id: dom_id(@post)
# => <section id="<generated dom id>"></section>

Передавайте true для любых атрибутов, которые могут отображаться без значения, например disabled и readonly.

tag.input type: 'text', disabled: true
# => <input type="text" disabled="disabled">

Атрибуты HTML5 data-* и aria-* можно задать с помощью одного ключа data или aria, указывающего на хеш вложенных атрибутов.

Для совместимости с соглашениями JavaScript имена вложенных атрибутов преобразуются в формат с дефисами.

tag.article data: { user_id: 123 }
# => <article data-user-id="123"></article>

Таким образом, к data-user-id можно обратиться как к dataset.userId.

Значения атрибутов данных кодируются в JSON, за исключением строк, символов и BigDecimal. Это может пригодиться при использовании учитывающего HTML5 метода .data() из jQuery 1.4.3.

tag.div data: { city_state: %w( Chicago IL ) }
# => <div data-city-state="[&quot;Chicago&quot;,&quot;IL&quot;]"></div>

Имена создаваемых тегов и атрибутов по умолчанию экранируются. Это можно отключить с помощью escape.

tag.img src: 'open & shut.png'
# => <img src="open &amp; shut.png">

tag.img src: 'open & shut.png', escape: false
# => <img src="open & shut.png">

Если содержимое не передано, построитель тегов учитывает пустые элементы HTML5 и не добавляет для них закрывающие теги.

# A standard element:
tag.div # => <div></div>

# A void element:
tag.br  # => <br>

Обратите внимание: при использовании формы с блоком параметры следует заключать в скобки.

<%= tag.a(href: "/about", class: "font-bold") do %>
  About the author
<% end %>
# => <a href="/about" class="font-bold">About the author</a>

Создание HTML-атрибутов

Преобразует Hash в HTML-атрибуты, готовые для подстановки в ERB. Включает или исключает логические атрибуты в зависимости от их истинности. Преобразует ключи, вложенные в объекты aria: или data:, в атрибуты с префиксами aria- и data-:

<input <%= tag.attributes(type: :text, aria: { label: "Search" }) %>>
# => <input type="text" aria-label="Search">

<button <%= tag.attributes id: "call-to-action", disabled: false, aria: { expanded: false } %> class="primary">Get Started!</button>
# => <button id="call-to-action" aria-expanded="false" class="primary">Get Started!</button>

Устаревший синтаксис

Следующий формат предназначен для поддержки устаревшего синтаксиса. В будущих версиях Rails он будет объявлен устаревшим.

tag(name, options = nil, open = false, escape = true)

Возвращает пустой HTML-тег типа name, который по умолчанию совместим с XHTML. Установите open в true, чтобы создать открытый тег, совместимый с HTML 4.0 и более ранними версиями. Чтобы добавить HTML-атрибуты, передайте хеш атрибутов в options. Установите escape в false, чтобы отключить экранирование значений атрибутов.

Параметры

В качестве имен атрибутов можно использовать символы или строки.

Используйте true с логическими атрибутами, которые могут отображаться без значения, например disabled и readonly.

Атрибуты HTML5 data-* можно задать с помощью одного ключа data, указывающего на хеш вложенных атрибутов.

Примеры

tag("br")
# => <br />

tag("br", nil, true)
# => <br>

tag("input", type: 'text', disabled: true)
# => <input type="text" disabled="disabled" />

tag("input", type: 'text', class: ["strong", "highlight"])
# => <input class="strong highlight" type="text" />

tag("img", src: "open & shut.png")
# => <img src="open &amp; shut.png" />

tag("img", { src: "open &amp; shut.png" }, false, false)
# => <img src="open &amp; shut.png" />

tag("div", data: { name: 'Stephen', city_state: %w(Chicago IL) })
# => <div data-name="Stephen" data-city-state="[&quot;Chicago&quot;,&quot;IL&quot;]" />

tag("div", class: { highlight: current_user.admin? })
# => <div class="highlight" />

token_list (*args) Показать исходный код

# File actionview/lib/action_view/helpers/tag_helper.rb, line 535
def token_list(*args)
  tokens = build_tag_values(*args).flat_map { |value| CGI.unescape_html(value.to_s).split(/\s+/) }.uniq

  safe_join(tokens, " ")
end

Возвращает строку токенов, построенную из args.

Примеры

token_list("foo", "bar")
 # => "foo bar"
token_list("foo", "foo bar")
 # => "foo bar"
token_list({ foo: true, bar: false })
 # => "foo"
token_list(nil, false, 123, "", "foo", { bar: true })
 # => "123 foo bar"

Также имеет псевдоним: class_names