Chapters1 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" />
1.1.1 auto_discovery_link_tag
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
1.1.8 stylesheet_link_tag
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.
1.11.3 strip_links(html)
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
1.12.2 link_to
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 forum oficial do Ruby on Rails e nas issues do Guia em português.