v7.0.0
Veja mais em rubyonrails.org: Mais Ruby on Rails

Action View Helpers

Depois de ler este guia, você saberá:

1 Visão geral dos helpers fornecidos pelo Action View

WIP: Nem todos os helpers estão listados aqui. Para uma lista completa, consulte a documentação da API

O que se segue é apenas um breve resumo geral dos helpers disponíveis no Action View. É recomendável que você revise a documentação da API, que cobre todos os helpers de forma mais detalhada, mas esse conteúdo deve servir como um bom ponto de partida.

1.1 AssetTagHelper

Este módulo fornece métodos para gerar HTML que vincula views aos assets, como imagens, arquivos JavaScript, folhas de estilo e feeds.

Por padrão, o Rails disponibiliza esses assets no host atual na pasta public, mas você pode direcionar o Rails para disponibilizar os assets de um servidor de assets dedicado definindo config.asset_host na configuração da aplicação, normalmente em config/environment/production.rb. Por exemplo, digamos que seu host de assets seja assets.example.com:

config.asset_host = "assets.example.com"
image_tag("rails.png")
# => <img src="http://assets.example.com/images/rails.png" />

Retorna uma tag de link que navegadores e leitores de feed podem usar para detectar automaticamente um feed RSS, Atom ou JSON.

auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", { title: "RSS Feed" })
# => <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="http://www.example.com/feed.rss" />
1.1.2 image_path

Gera o caminho para uma imagem no diretório app/assets/images. Caminhos completos da raiz do documento são interpretados como caminhos absolutos, ignorando as configurações da asset pipeline. Usado internamente por image_tag para construir o caminho da imagem.

image_path("edit.png") # => /assets/edit.png

Uma fingerprint será adicionada ao nome do arquivo se config.assets.digest for definido como verdadeiro.

image_path("edit.png")
# => /assets/edit-2d1a2db63fc738690021fedb5a65b68e.png
1.1.3 image_url

Gera a URL para um asset de imagem no diretório app/assets/images. Isso chamará image_path internamente e mesclará com seu host atual ou seu host de assets.

image_url("edit.png") # => http://www.example.com/assets/edit.png
1.1.4 image_tag

Retorna uma tag de imagem HTML para a fonte. A fonte pode ser um caminho completo ou um arquivo que existe em seu diretório app/assets/images.

image_tag("icon.png") # => <img src="/assets/icon.png" />
1.1.5 javascript_include_tag

Retorna uma tag de script HTML para cada uma das fontes fornecidas. Você pode passar o nome de arquivos JavaScript (a extensão .js é opcional) que existem no seu diretório app/assets/javascripts para inclusão na página atual ou você pode passar o caminho completo relativo à raiz do seu documento.

javascript_include_tag "common"
# => <script src="/assets/common.js"></script>
1.1.6 javascript_path

Gera o caminho para um asset JavaScript no diretório app/assets/javascripts. Se o nome do arquivo fonte não tiver extensão, .js será anexado. Caminhos completos da raiz do documento podem ser passados. Usado internamente por javascript_include_tag para construir o caminho do script.

javascript_path "common" # => /assets/common.js
1.1.7 javascript_url

Gera a URL para um asset JavaScript no diretório app/assets/javascripts. Isso chamará javascript_path internamente e mesclará com seu host atual ou seu host de assets.

javascript_url "common"
# => http://www.example.com/assets/common.js

Retorna uma tag com link de folha de estilo para as fontes especificadas como argumentos. Se você não especificar uma extensão, .css será anexado automaticamente.

stylesheet_link_tag "application"
# => <link href="/assets/application.css" rel="stylesheet" />
1.1.9 stylesheet_path

Gera o caminho para um recurso de stylesheet no diretório app/assets/stylesheets. Se o nome do arquivo fonte não tiver extensão, .css será anexado automaticamente. Caminhos completos da raiz do documento podem ser passados. Usado internamente por stylesheet_link_tag para construir o caminho da folha de estilo.

stylesheet_path "application" # => /assets/application.css
1.1.10 stylesheet_url

Gera a URL para um asset de folha de estilo no diretório app/assets/stylesheets. Isso chamará stylesheet_path internamente e mesclará com seu host atual ou seu host de asset.

stylesheet_url "application"
# => http://www.example.com/assets/application.css

1.2 AtomFeedHelper

1.2.1 atom_feed

Este helper facilita a construção de um feed Atom. Aqui está um exemplo completo de uso:

config/routes.rb

resources :articles

app/controllers/articles_controller.rb

def index
  @articles = Article.all

  respond_to do |format|
    format.html
    format.atom
  end
end

app/views/articles/index.atom.builder

atom_feed do |feed|
  feed.title("Articles Index")
  feed.updated(@articles.first.created_at)

  @articles.each do |article|
    feed.entry(article) do |entry|
      entry.title(article.title)
      entry.content(article.body, type: 'html')

      entry.author do |author|
        author.name(article.author_name)
      end
    end
  end
end

1.3 BenchmarkHelper

1.3.1 benchmark

Permite medir o tempo de execução de um bloco em um template e registra o resultado no log. Para tal, envolva este bloco em torno de operações custosas, ou com possíveis gargalos, para obter o tempo de leitura da operação.

<% benchmark "Process data files" do %>
  <%= expensive_files_operation %>
<% end %>

Isso adicionaria algo como "Process data files (0.34523)" ao log, que você pode usar para comparar tempos ao otimizar seu código.

1.4 CacheHelper

1.4.1 cache

Um método para armazenar em cache fragmentos de uma view, em vez de uma ação ou página inteira. Essa técnica é útil para armazenar componentes como: menus, listas de tópicos de notícias, fragmentos de HTML estáticos e assim por diante. Este método pega um bloco que contém o conteúdo que você deseja armazenar em cache. Veja AbstractController::Caching::Fragments para mais informações.

<% cache do %>
  <%= render "shared/footer" %>
<% end %>

1.5 CaptureHelper

1.5.1 capture

O método capture permite que você extraia parte de um template em uma variável. Você pode então usar essa variável em qualquer lugar nos templates ou layout.

<% @greeting = capture do %>
  <p>Welcome! The date and time is <%= Time.now %></p>
<% end %>

A variável capturada pode então ser usada em qualquer outro lugar.

<html>
  <head>
    <title>Welcome!</title>
  </head>
  <body>
    <%= @greeting %>
  </body>
</html>
1.5.2 content_for

Chamar content_for permite armazena um bloco de marcação em um identificador para uso posterior. Você pode fazer chamadas subsequentes para o conteúdo armazenado em outros templates ou no layout, passando o identificador como um argumento para yield.

Por exemplo, digamos que temos um layout padrão da aplicação, mas também uma página especial que requer determinado código JavaScript que o resto do site não precisa. Podemos usar content_for para incluir este código JavaScript em nossa página especial sem inflar o resto do site.

app/views/layouts/application.html.erb

<html>
  <head>
    <title>Boas vindas!</title>
    <%= yield :special_script %>
  </head>
  <body>
    <p>Boas vindas! A data e hora são <%= Time.now %></p>
  </body>
</html>

app/views/articles/special.html.erb

<p>Esta é a página especial.</p>

<% content_for :special_script do %>
  <script>alert('Ola!')</script>
<% end %>

1.6 DateHelper

1.6.1 distance_of_time_in_words

Informa a distância aproximada de tempo entre dois objetos Time, Date ou integers como segundos. Defina include_seconds como true se você quiser aproximações mais detalhadas.

distance_of_time_in_words(Time.now, Time.now + 15.seconds)
# => menos de um minuto
distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true)
# => menos de 20 segundos
1.6.2 time_ago_in_words

Como distance_of_time_in_words, mas onde to_time é fixado em Time.now.

time_ago_in_words(3.minutes.from_now) # => 3 minutos

1.7 DebugHelper

Retorna uma tag pre com um objeto YAML. Isso cria uma maneira muito legível de inspecionar um objeto.

my_hash = { 'first' => 1, 'second' => 'two', 'third' => [1,2,3] }
debug(my_hash)
<pre class='debug_dump'>---
first: 1
second: two
third:
- 1
- 2
- 3
</pre>

1.8 FormHelper

FormHelper são projetados para tornar o trabalho com models muito mais fácil em comparação com o uso apenas de elementos HTML padrão, fornecendo um conjunto de métodos para a criação de formulários com base em seus models. Este auxiliar gera o HTML para os formulários, fornecendo um método para cada tipo de entrada (por exemplo, texto (text), senha (password), seleção (select), e assim por diante). Quando o formulário é enviado (ou seja, quando o usuário clica no botão de envio, ou através de form.submit chamado via JavaScript), as entradas do formulário são agrupadas dentro de parâmetros de um objeto e devolvidas ao controlador.

Você pode aprender mais sobre os helpers de formulário em Action View Form Helpers Guide.

1.9 JavaScriptHelper

Fornece funcionalidades para trabalhar com JavaScript em suas views.

1.9.1 escape_javascript

Escapa retornos, aspas simples e aspas duplas para segmentos JavaScript.

1.9.2 javascript_tag

Retorna uma tag JavaScript envolvendo o código fornecido.

javascript_tag "alert('Tudo está bem')"
<script>
//<![CDATA[
alert('Tudo está bem')
//]]>
</script>

1.10 NumberHelper

Fornece métodos para converter números em strings formatadas. Métodos são fornecidos para números de telefone, moeda, porcentagem, precisão, notação posicional e tamanhos de arquivo.

1.10.1 number_to_currency

Formata um número em uma string de moeda (por exemplo, $13.65).

number_to_currency(1234567890.50) # => $1,234,567,890.50
1.10.2 number_to_human

Imprime (formata e aproxima) um número para que seja mais legível pelos usuários; útil para números que podem ficar muito grandes.

number_to_human(1234)    # => 1.23 Thousand
number_to_human(1234567) # => 1.23 Million
1.10.3 number_to_human_size

Formata os bytes em tamanho em uma representação mais compreensível; útil para relatar tamanhos de arquivo aos usuários.

number_to_human_size(1234)    # => 1.21 KB
number_to_human_size(1234567) # => 1.18 MB
1.10.4 number_to_percentage

Formata um número como string de porcentagem.

number_to_percentage(100, precision: 0) # => 100%
1.10.5 number_to_phone

Formata um número em um número de telefone (formato dos EUA por padrão).

number_to_phone(1235551234) # => 123-555-1234
1.10.6 number_with_delimiter

Formata um número com casas de milhar usando um delimitador.

number_with_delimiter(12345678) # => 12,345,678
1.10.7 number_with_precision

Formata um número com o nível especificado de precision (precisão), cujo o padrão é 3.

number_with_precision(111.2345)               # => 111.235
number_with_precision(111.2345, precision: 2) # => 111.23

1.11 SanitizeHelper

O módulo SanitizeHelper fornece um conjunto de métodos para limpar o texto de elementos HTML indesejados.

1.11.1 sanitize

Este helper de limpeza codificará em HTML todas as tags e removerá todos os atributos que não são especificamente permitidos.

sanitize @article.body

Se as opções :attributes (atributos) ou :tags são passadas, apenas os atributos e tags mencionados são permitidos e nada mais.

sanitize @article.body, tags: %w(table tr td), attributes: %w(id class style)

Para alterar os padrões para múltiplos usos, por exemplo, adicionando tags de tabela ao padrão:

class Application < Rails::Application
  config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
end
1.11.2 sanitize_css(style)

Limpa um bloco de código CSS.

Remove todas as tags de link do texto, deixando apenas o texto do link.

strip_links('<a href="https://rubyonrails.org">Ruby on Rails</a>')
# => Ruby on Rails
strip_links('e-mails para <a href="mailto:[email protected]">[email protected]</a>.')
# => e-mails para [email protected].
strip_links('Blog: <a href="http://myblog.com/">Visite</a>.')
# => Blog: Visite.
1.11.4 strip_tags(html)

Retira todas as tags HTML do html, incluindo comentários. Essa funcionalidade é alimentada pela gem rails-html-sanitizer.

strip_tags("Remova <i>essas</i> tags!")
# => Remova essas tags!
strip_tags("Sem <b>Bold</b> mais!  <a href='more.html'>Ver mais</a>")
# => Sem bold mais!  Ver mais

Nota: A saída ainda pode conter caracteres '<', '>', '&' sem ser escapadas e confundir os navegadores.

1.12 UrlHelper

Fornece métodos para criar links e obter URLs que dependem do subsistema de roteamento.

1.12.1 url_for

Retorna a URL para o conjunto de options fornecido.

1.12.1.1 Exemplos
url_for @profile
# => /profiles/1

url_for [ @hotel, @booking, page: 2, line: 3 ]
# => /hotels/1/bookings/1?line=3&page=2

Links para uma URL derivada de url_for nos bastidores. Usado principalmente para criar links de recursos RESTful, que, para este exemplo, se resumem a ao passar models para link_to.

Exemplos

link_to "Profile", @profile
# => <a href="/profiles/1">Profile</a>

Você também pode usar um bloco se o destino do link não couber no parâmetro de nome. Exemplo de ERB:

<%= link_to @profile do %>
  <strong><%= @profile.name %></strong> -- <span>Confira!</span>
<% end %>

produziria:

<a href="/profiles/1">
  <strong>David</strong> -- <span>Confira!</span>
</a>

Consulte a documentação da API para obter mais informações

1.12.3 button_to

Gera um formulário que submete para a URL passada. O formulário tem um botão de envio com o valor do name (nome).

1.12.3.1 Examples
<%= button_to "Entrar", sign_in_path %>

produziria aproximadamente algo como:

<form method="post" action="/sessions" class="button_to">
  <input type="submit" value="Entrar" />
</form>

Consulte a documentação da API para obter mais informações

1.13 CsrfHelper

Retorna meta tags "csrf-param" e "csrf-token" com o nome do cross-site. Solicita parâmetros de proteção contra falsificação e token, respectivamente.

<%= csrf_meta_tags %>

Os formulários regulares geram campos ocultos, portanto, não usam essas tags. Mais detalhes podem ser encontrados no Rails Security Guide.

Feedback

Você é incentivado a ajudar a melhorar a qualidade deste guia.

Por favor, contribua caso veja quaisquer erros, inclusive erros de digitação. Para começar, você pode ler nossa sessão de contribuindo com a documentação.

Você também pode encontrar conteúdo incompleto ou coisas que não estão atualizadas. Por favor, adicione qualquer documentação em falta na main do Rails. Certifique-se de checar o Edge Guides (en-US) primeiro para verificar se o problema já foi resolvido ou não no branch main. Verifique as Diretrizes do Guia Ruby on Rails para estilo e convenções.

Se, por qualquer motivo, você encontrar algo para consertar, mas não conseguir consertá-lo, por favor abra uma issue no nosso Guia.

E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem vinda na lista de discussão rubyonrails-docs e nas issues do Guia em português.


dark theme icon