docs/5-forms.md in activeadmin-0.6.6 vs docs/5-forms.md in activeadmin-1.0.0.pre1
- old
+ new
@@ -1,82 +1,159 @@
-# Customizing the Form
+# Forms
-Active Admin gives complete control over the output of the form by creating a thin DSL on top of
-the fabulous DSL created by [Formtastic](http://github.com/justinfrench/formtastic).
+Active Admin gives you complete control over the output of the form by creating
+a thin DSL on top of [Formtastic](https://github.com/justinfrench/formtastic):
- ActiveAdmin.register Post do
+```ruby
+ActiveAdmin.register Post do
- form do |f|
- f.inputs "Details" do
- f.input :title
- f.input :published_at, :label => "Publish Post At"
- f.input :category
- end
- f.inputs "Content" do
- f.input :body
- end
- f.actions
- end
-
+ form do |f|
+ inputs 'Details' do
+ input :title
+ input :published_at, label: "Publish Post At"
+ li "Created at #{f.object.created_at}" unless f.object.new_record?
+ input :category
end
+ panel 'Markup' do
+ "The following can be used in the content below..."
+ end
+ inputs 'Content', :body
+ para "Press cancel to return to the list without saving."
+ actions
+ end
-Please view [the documentation](http://github.com/justinfrench/formtastic)
-for Formtastic to see all the wonderful things you can do.
+end
+```
-If you require a more custom form than can be provided through the DSL, you can pass
-a partial in to render the form yourself.
+For more details, please see Formtastic's documentation.
-For example:
+## Default
- ActiveAdmin.register Post do
- form :partial => "form"
- end
+Resources come with a default form defined as such:
-Then implement app/views/admin/posts/_form.html.erb:
+```ruby
+form do |f|
+ f.semantic_errors # shows errors on :base
+ f.inputs # builds an input field for every attribute
+ f.actions # adds the 'Submit' and 'Cancel' buttons
+end
+```
- <%= semantic_form_for [:admin, @post] do |f| %>
- <%= f.inputs :title, :body %>
- <%= f.actions :commit %>
- <% end %>
+## Partials
+If you want to split a custom form into a separate partial use:
+
+```ruby
+ActiveAdmin.register Post do
+ form partial: 'form'
+end
+```
+
+Which looks for something like this:
+
+```ruby
+# app/views/admin/posts/_form.html.arb
+insert_tag active_admin_form_for resource do |f|
+ inputs :title, :body
+ actions
+end
+```
+
+This is a regular Rails partial so any template engine may be used.
+
## Nested Resources
-You can create forms with nested models using the `has_many` method:
+You can create forms with nested models using the `has_many` method, even if your model uses `has_one`:
- ActiveAdmin.register Post do
+```ruby
+ActiveAdmin.register Post do
- form do |f|
- f.inputs "Details" do
- f.input :title
- f.input :published_at, :label => "Publish Post At"
- end
- f.inputs "Content" do
- f.input :body
- end
- f.inputs do
- f.has_many :categories, :allow_destroy => true, :heading => 'Themes', :new_record => false do |cf|
- cf.input :title
- end
- end
- f.actions
+ form do |f|
+ f.inputs 'Details' do
+ f.input :title
+ f.input :published_at, label: 'Publish Post At'
+ end
+ f.inputs 'Content', :body
+ f.inputs do
+ f.has_many :categories, heading: 'Themes', allow_destroy: true, new_record: false do |a|
+ a.input :title
end
-
end
+ f.inputs do
+ f.has_many :taggings, sortable: :position, sortable_start: 1 do |t|
+ t.input :tag
+ end
+ end
+ f.inputs do
+ f.has_many :comment, new_record: 'Leave Comment' do |b|
+ b.input :body
+ end
+ end
+ f.actions
+ end
-The `:allow_destroy` option will add a checkbox to the end of the nested form allowing
-removal of the child object upon submission. Be sure to set `:allow_destroy => true`
+end
+```
+
+The `:allow_destroy` option adds a checkbox to the end of the nested form allowing
+removal of the child object upon submission. Be sure to set `allow_destroy: true`
on the association to use this option.
-The `:heading` option will add a custom heading to has_many form. You can hide a heading by setting `:heading => false`.
+The `:heading` option adds a custom heading. You can hide it entirely by passing `false`.
-The `:new_record` option will show or hide new record link at the bottom of has_many form. It is set as true by default.
+The `:new_record` option controls the visibility of the new record button (shown by default).
+If you pass a string, it will be used as the text for the new record button.
+The `:sortable` option adds a hidden field and will enable drag & drop sorting of the children. It
+expects the name of the column that will store the index of each child.
+
+The `:sortable_start` option sets the value (0 by default) of the first position in the list.
+
+## Datepicker
+
+ActiveAdmin offers the `datepicker` input, which uses the [jQuery UI datepicker](http://jqueryui.com/datepicker/).
+The datepicker input accepts any of the options available to the standard jQueryUI Datepicker. For example:
+
+```ruby
+form do |f|
+ f.input :starts_at, as: :datepicker, datepicker_options: { min_date: "2013-10-8", max_date: "+3D" }
+ f.input :ends_at, as: :datepicker, datepicker_options: { min_date: 3.days.ago.to_date, max_date: "+1W +5D" }
+end
+```
+
## Displaying Errors
-To display a list of all errors, include `semantic_errors` at top of form. Particularly useful to display errors on the base or virtual attributes.
+To display a list of all validation errors:
- form do |f|
- f.semantic_errors *f.object.errors.keys
- f.inputs
- f.buttons
- end
+```ruby
+form do |f|
+ f.semantic_errors *f.object.errors.keys
+ # ...
+end
+```
+This is particularly useful to display errors on virtual or hidden attributes.
+
+# Tabs
+
+You can arrage content in tabs as shown below:
+
+```ruby
+ form do |f|
+ tabs do
+ tab 'Basic' do
+ f.inputs 'Basic Details' do
+ f.input :email
+ f.input :password
+ f.input :password_confirmation
+ end
+ end
+
+ tab 'Advanced' do
+ f.inputs 'Advanced Details' do
+ f.input :role
+ end
+ end
+ end
+ f.actions
+ end
+```