README.rdoc in simple_form-1.2.2 vs README.rdoc in simple_form-1.3.0
- old
+ new
@@ -2,10 +2,32 @@
Forms made easy (for Rails)!
SimpleForm aims to be as flexible as possible while helping you with powerful components to create your forms. The basic goal of simple form is to not touch your way of defining the layout, letting you find the better design for your eyes. Good part of the DSL was inherited from Formtastic, which we are thankful for and should make you feel right at home.
+== Information
+
+=== Google Group
+
+If you have any questions, comments, or concerns please use the Google Group instead of the GitHub Issues tracker:
+
+http://groups.google.com/group/plataformatec-simpleform
+
+=== RDocs
+
+You can view the SimpleForm documentation in RDoc format here:
+
+http://rubydoc.info/github/plataformatec/simple_form/master/frames
+
+If you need to use SimpleForm with Rails 2.3, you can always run `gem server` from the command line after you install the gem to access the old documentation.
+
+=== Bug reports
+
+If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as possible to help us fixing the possible bug. We also encourage you to help even more by forking and sending us a pull request.
+
+http://github.com/plataformatec/simple_form/issues
+
== Installation
Install the gem:
gem install simple_form
@@ -16,10 +38,14 @@
Run the generator:
rails generate simple_form:install
+Also, if you want to use the country select, you will need the country_select plugin, install with following command:
+
+ rails plugin install git://github.com/rails/country_select.git
+
And you are ready to go. Since this branch aims Rails 3 support,
if you want to use it with Rails 2.3 you should check this branch:
http://github.com/plataformatec/simple_form/tree/v1.0
@@ -35,15 +61,16 @@
<%= f.button :submit %>
<% end %>
This will generate an entire form with labels for user name and password as well, and render errors by default when you render the form with invalid data (after submitting for example).
-You can overwrite the default label by passing it to the input method, or even add a hint:
+You can overwrite the default label by passing it to the input method, add a hint or even a placeholder:
<%= simple_form_for @user do |f| %>
<%= f.input :username, :label => 'Your username please' %>
<%= f.input :password, :hint => 'No special characters.' %>
+ <%= f.input :email, :placeholder => 'user@domain.com' %>
<%= f.button :submit %>
<% end %>
You can also disable labels, hints or error or configure the html of any of them:
@@ -52,10 +79,19 @@
<%= f.input :password, :hint => false, :error_html => { :id => "password_error"} %>
<%= f.input :password_confirmation, :label => false %>
<%= f.button :submit %>
<% end %>
+It is also possible to pass any html attribute straight to the input, by using the :input_html option, for instance:
+
+ <%= simple_form_for @user do |f| %>
+ <%= f.input :username, :input_html => { :class => 'special' } %>
+ <%= f.input :password, :input_html => { :maxlength => 20 } %>
+ <%= f.input :remember_me, :input_html => { :value => '1' } %>
+ <%= f.button :submit %>
+ <% end %>
+
By default all inputs are required, which means an * is prepended to the label, but you can disable it in any input you want:
<%= simple_form_for @user do |f| %>
<%= f.input :name, :required => false %>
<%= f.input :username %>
@@ -73,10 +109,26 @@
<%= f.button :submit %>
<% end %>
So instead of a checkbox for the :accepts attribute, you'll have a pair of radio buttons with yes/no labels and a text area instead of a text field for the description. You can also render boolean attributes using :as => :select to show a dropdown.
+It is also possible to give the :disabled option to SimpleForm, and it'll automatically mark the wrapper as disabled with a css class, so you can style labels, hints and other components inside the wrapper as well:
+
+ <%= simple_form_for @user do |f| %>
+ <%= f.input :username, :disabled => true, :hint => "You cannot change your username." %>
+ <%= f.button :submit %>
+ <% end %>
+
+SimpleForm accepts same options as their corresponding input type helper in Rails:
+
+ <%= simple_form_for @user do |f| %>
+ <%= f.input :date_of_birth, :as => :date, :start_year => Date.today.year - 90,
+ :end_year => Date.today.year - 12, :discard_day => true,
+ :order => [:month, :year] %>
+ <%= f.button :submit %>
+ <% end %>
+
SimpleForm also allows you using label, hint and error helpers it provides:
<%= simple_form_for @user do |f| %>
<%= f.label :username %>
<%= f.text_field :username %>
@@ -103,11 +155,11 @@
* label_method => the label method to be applied to the collection to retrieve the label
* value_method => the value method to be applied to the collection to retrieve the value
-Those methods are useful to manipulate the given collection. All other options given are sent straight to the underlying helper. For example, you can give prompt as:
+Those methods are useful to manipulate the given collection. Both of these options also except lambda/procs incase you want to calculate the value or label in a special way eg. custom translation. All other options given are sent straight to the underlying helper. For example, you can give prompt as:
f.input :age, :collection => 18..60, :prompt => "Select your age"
=== Priority
@@ -210,11 +262,11 @@
=== Collection Check Box
Creates a collection of check boxes with labels associated (same API as collection_select):
form_for @user do |f|
- f.collection_check_box :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
+ f.collection_check_boxes :options, [[true, 'Yes'] ,[false, 'No']], :first, :last
end
<input name="user[options][]" type="hidden" value="" />
<input id="user_options_true" name="user[options][]" type="checkbox" value="true" />
<label class="collection_check_box" for="user_options_true">Yes</label>
@@ -230,11 +282,13 @@
boolean check box boolean
string text field string
email email field string with name matching "email"
url url field string with name matching "url"
+ tel tel field string with name matching "phone"
password password field string with name matching "password"
+ search search -
text text area text
file file field string, responding to file methods
hidden hidden field -
integer number field integer
float number field float
@@ -248,11 +302,11 @@
country country select string with name matching "country"
time_zone time zone select string with name matching "time_zone"
== I18n
-SimpleForm uses all power of I18n API to lookup labels and hints for you. To customize your forms you can create a locale file like this:
+SimpleForm uses all power of I18n API to lookup labels, hints and placeholders. To customize your forms you can create a locale file like this:
en:
simple_form:
labels:
user:
@@ -260,14 +314,18 @@
password: 'Password'
hints:
user:
username: 'User name to sign in.'
password: 'No special characters, please.'
+ placeholders:
+ user:
+ username: 'Your username'
+ password: '****'
-And your forms will use this information to render labels and hints for you.
+And your forms will use this information to render the components for you.
-SimpleForm also lets you be more specific, separating lookups through actions for both hint and label. Let's say you want a different label for new and edit actions, the locale file would be something like:
+SimpleForm also lets you be more specific, separating lookups through actions for labels, hints and placeholders. Let's say you want a different label for new and edit actions, the locale file would be something like:
en:
simple_form:
labels:
user:
@@ -285,17 +343,29 @@
username: 'User name'
password: 'Password'
hints:
username: 'User name to sign in.'
password: 'No special characters, please.'
+ placeholders:
+ username: 'Your username'
+ password: '****'
-SimpleForm will always look for a default attribute translation if no specific is found inside the model key. In addition, SimpleForm will fallback to default human_attribute_name from Rails when no other translation is found.
+SimpleForm will always look for a default attribute translation if no specific is found inside the model key. In addition, SimpleForm will fallback to default human_attribute_name from Rails when no other translation is found for labels.
-Finally, you can also overwrite labels and hints inside your view, just by passing the label/hint manually. This way the I18n lookup will be skipped.
+Finally, you can also overwrite any label, hint or placeholder inside your view, just by passing the option manually. This way the I18n lookup will be skipped.
-There are other options that can be configured through I18n API, such as required text, boolean and button texts. Be sure to check our locale file or the one copied to your application after you run "rails generate simple_form:install".
+It's also possible to translate buttons, using Rails' built-in I18n support:
+ en:
+ helpers:
+ submit:
+ user:
+ create: "Add %{model}"
+ update: "Save Changes"
+
+There are other options that can be configured through I18n API, such as required text and boolean. Be sure to check our locale file or the one copied to your application after you run "rails generate simple_form:install".
+
== Configuration
SimpleForm has several configuration values. You can read and change them in the initializer created by SimpleForm, so if you haven't executed the command below yet, please do:
rails generate simple_form:install
@@ -307,12 +377,8 @@
== Maintainers
* José Valim (http://github.com/josevalim)
* Carlos Antonio da Silva (http://github.com/carlosantoniodasilva)
-== Bugs and Feedback
-
-If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
-
-http://github.com/plataformatec/simple_form/issues
+== License
MIT License. Copyright 2010 Plataforma Tecnologia. http://blog.plataformatec.com.br