From ecc533ce6ab53ce45decddc4d05cbc726fd598aa Mon Sep 17 00:00:00 2001 From: Petrik Date: Tue, 23 Jun 2020 15:57:40 +0200 Subject: [PATCH] Remove duplicate FormHelpers from ActionView Helpers guide [ci skip] Since there's already a whole seperate guide dedicated to Formhelpers, there is no need to duplicate them in the ActionView Helpers guide. We can link to the FormHelpers guide instead. --- guides/source/action_view_helpers.md | 684 +-------------------------- 1 file changed, 6 insertions(+), 678 deletions(-) diff --git a/guides/source/action_view_helpers.md b/guides/source/action_view_helpers.md index 57b0b249e6..da1bba304b 100644 --- a/guides/source/action_view_helpers.md +++ b/guides/source/action_view_helpers.md @@ -5,7 +5,10 @@ Action View Helpers After reading this guide, you will know: -* What helpers are provided by Action View. +* How to format dates, strings and numbers +* How to link to images, videos, stylesheets, etc... +* How to sanitize content +* How to localize content -------------------------------------------------------------------------------- @@ -248,22 +251,6 @@ For example, let's say we have a standard application layout, but also a special ### DateHelper -#### date_select - -Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based attribute. - -```ruby -date_select("article", "published_on") -``` - -#### datetime_select - -Returns a set of select tags (one for year, month, day, hour, and minute) pre-selected for accessing a specified datetime-based attribute. - -```ruby -datetime_select("article", "published_on") -``` - #### distance_of_time_in_words Reports the approximate distance in time between two Time or Date objects or integers as seconds. Set `include_seconds` to true if you want more detailed approximations. @@ -275,99 +262,6 @@ distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true # => less than 20 seconds ``` -#### select_date - -Returns a set of HTML select-tags (one for year, month, and day) pre-selected with the `date` provided. - -```ruby -# Generates a date select that defaults to the date provided (six days after today) -select_date(Time.today + 6.days) - -# Generates a date select that defaults to today (no specified date) -select_date() -``` - -#### select_datetime - -Returns a set of HTML select-tags (one for year, month, day, hour, and minute) pre-selected with the `datetime` provided. - -```ruby -# Generates a datetime select that defaults to the datetime provided (four days after today) -select_datetime(Time.now + 4.days) - -# Generates a datetime select that defaults to today (no specified datetime) -select_datetime() -``` - -#### select_day - -Returns a select tag with options for each of the days 1 through 31 with the current day selected. - -```ruby -# Generates a select field for days that defaults to the day for the date provided -select_day(Time.today + 2.days) - -# Generates a select field for days that defaults to the number given -select_day(5) -``` - -#### select_hour - -Returns a select tag with options for each of the hours 0 through 23 with the current hour selected. - -```ruby -# Generates a select field for hours that defaults to the hours for the time provided -select_hour(Time.now + 6.hours) -``` - -#### select_minute - -Returns a select tag with options for each of the minutes 0 through 59 with the current minute selected. - -```ruby -# Generates a select field for minutes that defaults to the minutes for the time provided. -select_minute(Time.now + 10.minutes) -``` - -#### select_month - -Returns a select tag with options for each of the months January through December with the current month selected. - -```ruby -# Generates a select field for months that defaults to the current month -select_month(Date.today) -``` - -#### select_second - -Returns a select tag with options for each of the seconds 0 through 59 with the current second selected. - -```ruby -# Generates a select field for seconds that defaults to the seconds for the time provided -select_second(Time.now + 16.seconds) -``` - -#### select_time - -Returns a set of HTML select-tags (one for hour and minute). - -```ruby -# Generates a time select that defaults to the time provided -select_time(Time.now) -``` - -#### select_year - -Returns a select tag with options for each of the five years on each side of the current, which is selected. The five year radius can be changed using the `:start_year` and `:end_year` keys in the `options`. - -```ruby -# Generates a select field for five years on either side of Date.today that defaults to the current year -select_year(Date.today) - -# Generates a select field from 1900 to 2009 that defaults to the current year -select_year(Date.today, start_year: 1900, end_year: 2009) -``` - #### time_ago_in_words Like `distance_of_time_in_words`, but where `to_time` is fixed to `Time.now`. @@ -376,15 +270,6 @@ Like `distance_of_time_in_words`, but where `to_time` is fixed to `Time.now`. time_ago_in_words(3.minutes.from_now) # => 3 minutes ``` -#### time_select - -Returns a set of select tags (one for hour, minute, and optionally second) pre-selected for accessing a specified time-based attribute. The selects are prepared for multi-parameter assignment to an Active Record object. - -```ruby -# Creates a time select tag that, when POSTed, will be stored in the order variable in the submitted attribute -time_select("order", "submitted") -``` - ### DebugHelper Returns a `pre` tag that has object dumped by YAML. This creates a very readable way to inspect an object. @@ -409,565 +294,8 @@ third: Form helpers are designed to make working with models much easier compared to using just standard HTML elements by providing a set of methods for creating forms based on your models. This helper generates the HTML for forms, providing a method for each sort of input (e.g., text, password, select, and so on). When the form is submitted (i.e., when the user hits the submit button or form.submit is called via JavaScript), the form inputs will be bundled into the params object and passed back to the controller. -There are two types of form helpers: those that specifically work with model attributes and those that don't. This helper deals with those that work with model attributes; to see an example of form helpers that don't work with model attributes, check the `ActionView::Helpers::FormTagHelper` documentation. - -The core method of this helper, `form_with`, gives you the ability to create a form for a model instance; for example, let's say that you have a model Person and want to create a new instance of it: - -```html+erb - -<%= form_with model: @person do |form| %> - <%= form.text_field :first_name %> - <%= form.text_field :last_name %> - <%= submit_tag 'Create' %> -<% end %> -``` - -The HTML generated for this would be: - -```html -
- - - - - -
-``` - -The params object created when this form is submitted would look like: - -```ruby -{"utf8" => "✓", "authenticity_token" => "lTuvBzs7ANygT0NFinXj98tfw3Emfm65wwYLbUvoWsK2pngccIQSUorM2C035M9dZswXgWTvKwFS8W5TVblpYw==", "person" => {"first_name" => "William", "last_name" => "Smith"}, "commit" => "Create", "controller" => "people", "action" => "create"} -``` - -The params hash has a nested person value, which can therefore be accessed with `params[:person]` in the controller. - -#### check_box - -Returns a checkbox tag tailored for accessing a specified attribute. - -```ruby -# Let's say that @article.validated? is 1: -check_box("article", "validated") -# => -# -``` - -#### fields_for - -Creates a scope around a specific model object. This makes `fields_for` suitable for specifying additional model objects in the same form: - -```html+erb -<%= form_with model: @person do |person_form| %> - First name: <%= person_form.text_field :first_name %> - Last name : <%= person_form.text_field :last_name %> - - <%= fields_for @person.permission do |permission_fields| %> - Admin? : <%= permission_fields.check_box :admin %> - <% end %> -<% end %> -``` - -#### file_field - -Returns a file upload input tag tailored for accessing a specified attribute. - -```ruby -file_field(:user, :avatar) -# => -``` - -#### form_with - -Creates a form builder to work with. If a `model` argument is specified, form fields will be scoped to that model, and form field values will be prepopulated with corresponding model attributes. - -```html+erb -<%= form_with model: @article do |form| %> - <%= form.label :title, 'Title' %>: - <%= form.text_field :title %>
- <%= form.label :body, 'Body' %>: - <%= form.text_area :body %>
-<% end %> -``` - -#### hidden_field - -Returns a hidden input tag tailored for accessing a specified attribute. - -```ruby -hidden_field(:user, :token) -# => -``` - -#### label - -Returns a label tag tailored for labelling an input field for a specified attribute. - -```ruby -label(:article, :title) -# => -``` - -#### password_field - -Returns an input tag of the "password" type tailored for accessing a specified attribute. - -```ruby -password_field(:login, :pass) -# => -``` - -#### radio_button - -Returns a radio button tag for accessing a specified attribute. - -```ruby -# Let's say that @article.category returns "rails": -radio_button("article", "category", "rails") -radio_button("article", "category", "java") -# => -# -``` - -#### text_area - -Returns a textarea opening and closing tag set tailored for accessing a specified attribute. - -```ruby -text_area(:comment, :text, size: "20x30") -# => -``` - -#### text_field - -Returns an input tag of the "text" type tailored for accessing a specified attribute. - -```ruby -text_field(:article, :title) -# => -``` - -#### email_field - -Returns an input tag of the "email" type tailored for accessing a specified attribute. - -```ruby -email_field(:user, :email) -# => -``` - -#### url_field - -Returns an input tag of the "url" type tailored for accessing a specified attribute. - -```ruby -url_field(:user, :url) -# => -``` - -### FormOptionsHelper - -Provides a number of methods for turning different kinds of containers into a set of option tags. - -#### collection_select - -Returns `select` and `option` tags for the collection of existing return values of `method` for `object`'s class. - -Example object structure for use with this method: - -```ruby -class Article < ApplicationRecord - belongs_to :author -end - -class Author < ApplicationRecord - has_many :articles - def name_with_initial - "#{first_name.first}. #{last_name}" - end -end -``` - -Sample usage (selecting the associated Author for an instance of Article, `@article`): - -```ruby -collection_select(:article, :author_id, Author.all, :id, :name_with_initial, { prompt: true }) -``` - -If `@article.author_id` is 1, this would return: - -```html - -``` - -#### collection_radio_buttons - -Returns `radio_button` tags for the collection of existing return values of `method` for `object`'s class. - -Example object structure for use with this method: - -```ruby -class Article < ApplicationRecord - belongs_to :author -end - -class Author < ApplicationRecord - has_many :articles - def name_with_initial - "#{first_name.first}. #{last_name}" - end -end -``` - -Sample usage (selecting the associated Author for an instance of Article, `@article`): - -```ruby -collection_radio_buttons(:article, :author_id, Author.all, :id, :name_with_initial) -``` - -If `@article.author_id` is 1, this would return: - -```html - - - - - - -``` - -Recovering some option passed (e.g. programmatically checking an object from collection): - -```ruby -collection_radio_buttons(:article, :author_id, Author.all, :id, :name_with_initial, {checked: Author.last}) -``` - -In this case, the last object from the collection will be checked: - -```html - - - - - - -``` - -To access the passed options programmatically (e.g. adding a custom class if checked): - -**Sample html.erb** - -```html+erb -<%= collection_radio_buttons(:article, :author_id, Author.all, :id, :name_with_initial, {checked: Author.last, required: true} do |rb| %> - <%= rb.label(class: "#{'my-custom-class' if rb.value == Author.last.id}") { rb.radio_button + rb.text } %> -<% end %> -``` - - -#### collection_check_boxes - -Returns `check_box` tags for the collection of existing return values of `method` for `object`'s class. - -Example object structure for use with this method: - -```ruby -class Article < ApplicationRecord - has_and_belongs_to_many :authors -end - -class Author < ApplicationRecord - has_and_belongs_to_many :articles - def name_with_initial - "#{first_name.first}. #{last_name}" - end -end -``` - -Sample usage (selecting the associated Authors for an instance of Article, `@article`): - -```ruby -collection_check_boxes(:article, :author_ids, Author.all, :id, :name_with_initial) -``` - -If `@article.author_ids` is [1], this would return: - -```html - - - - - - - -``` - -#### option_groups_from_collection_for_select - -Returns a string of `option` tags, like `options_from_collection_for_select`, but groups them by `optgroup` tags based on the object relationships of the arguments. - -Example object structure for use with this method: - -```ruby -class Continent < ApplicationRecord - has_many :countries - # attribs: id, name -end - -class Country < ApplicationRecord - belongs_to :continent - # attribs: id, name, continent_id -end -``` - -Sample usage: - -```ruby -option_groups_from_collection_for_select(@continents, :countries, :name, :id, :name, 3) -``` - -Possible output: - -```html - - - - ... - - - - - - ... - -``` - -NOTE: Only the `optgroup` and `option` tags are returned, so you still have to wrap the output in an appropriate `select` tag. - -#### options_for_select - -Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. - -```ruby -options_for_select([ "VISA", "MasterCard" ]) -# => -``` - -NOTE: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag. - -#### options_from_collection_for_select - -Returns a string of option tags that have been compiled by iterating over the `collection` and assigning the result of a call to the `value_method` as the option value and the `text_method` as the option text. - -```ruby -options_from_collection_for_select(collection, value_method, text_method, selected = nil) -``` - -For example, imagine a loop iterating over each person in `@project.people` to generate an input tag: - -```ruby -options_from_collection_for_select(@project.people, "id", "name") -# => -``` - -NOTE: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag. - -#### select - -Create a select tag and a series of contained option tags for the provided object and method. - -Example: - -```ruby -select("article", "person_id", Person.all.collect { |p| [ p.name, p.id ] }, { include_blank: true }) -``` - -If `@article.person_id` is 1, this would become: - -```html - -``` - -#### time_zone_options_for_select - -Returns a string of option tags for pretty much any time zone in the world. - -#### time_zone_select - -Returns select and option tags for the given object and method, using `time_zone_options_for_select` to generate the list of option tags. - -```ruby -time_zone_select("user", "time_zone") -``` - -#### date_field - -Returns an input tag of the "date" type tailored for accessing a specified attribute. - -```ruby -date_field("user", "dob") -``` - -### FormTagHelper - -Provides a number of methods for creating form tags that are not scoped to model objects. Instead, you provide the names and values manually. - -#### check_box_tag - -Creates a check box form input tag. - -```ruby -check_box_tag 'accept' -# => -``` - -#### field_set_tag - -Creates a field set for grouping HTML form elements. - -```html+erb -<%= field_set_tag do %> -

<%= text_field_tag 'name' %>

-<% end %> -# =>

-``` - -#### file_field_tag - -Creates a file upload field. - -```html+erb -<%= form_with url: new_account_avatar_path(@account), multipart: true do %> - <%= file_field_tag 'avatar' %> - <%= submit_tag %> -<% end %> -``` - -Example output: - -```ruby -file_field_tag 'attachment' -# => -``` - -#### hidden_field_tag - -Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or data that should be hidden from the user. - -```ruby -hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@' -# => -``` - -#### image_submit_tag - -Displays an image which when clicked will submit the form. - -```ruby -image_submit_tag("login.png") -# => -``` - -#### label_tag - -Creates a label field. - -```ruby -label_tag 'name' -# => -``` - -#### password_field_tag - -Creates a password field, a masked text field that will hide the users input behind a mask character. - -```ruby -password_field_tag 'pass' -# => -``` - -#### radio_button_tag - -Creates a radio button; use groups of radio buttons named the same to allow users to select from a group of options. - -```ruby -radio_button_tag 'favorite_color', 'maroon' -# => -``` - -#### select_tag - -Creates a dropdown selection box. - -```ruby -select_tag "people", "" -# => -``` - -#### submit_tag - -Creates a submit button with the text provided as the caption. - -```ruby -submit_tag "Publish this article" -# => -``` - -#### text_area_tag - -Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions. - -```ruby -text_area_tag 'article' -# => -``` - -#### text_field_tag - -Creates a standard text field; use these text fields to input smaller chunks of text like a username or a search query. - -```ruby -text_field_tag 'name' -# => -``` - -#### email_field_tag - -Creates a standard input field of email type. - -```ruby -email_field_tag 'email' -# => -``` - -#### url_field_tag - -Creates a standard input field of url type. - -```ruby -url_field_tag 'url' -# => -``` - -#### date_field_tag - -Creates a standard input field of date type. - -```ruby -date_field_tag "dob" -# => -``` +You can learn more about form helpers in the [Action View Form Helpers +Guide](form_helpers.html). ### JavaScriptHelper