admin_assistant 1.0.0 → 1.0.1

data/website/api/form.markdown

@@ -0,0 +1,291 @@
+---
+layout: api
+title:  Form
+---
+
+![form](../img/user-form.png)
+
+Form configuration affects both creating new records and updating existing records. Most of its customization happens through the form builder object:
+
+
+    class Admin::BlogPostsController < ApplicationController
+      admin_assistant_for BlogPost do |a|
+        a.form do |form|
+          form.columns :user, :title, :body
+        end
+      end
+    end
+
+### Form config options
+
+#### columns
+
+    form.columns :user, :title, :body
+
+Shows only these columns in the form.
+
+#### columns\_for\_edit
+
+    form.columns_for_edit :title, :user, :published_at, :body, :merged_into
+
+Shows only these columns in the edit action.
+
+
+#### columns\_for\_new
+
+    form.columns_for_new  :title, :user, :published_at
+
+Shows only these columns in the new action.
+
+
+#### multi
+
+    form.multi = true
+    
+Set this to true to enable multi-record creation in your form. Validation errors will be shown on top of the individual row that caused the error, and if any of the records has a validation error, none of the records will be created.
+
+Please note that this feature is alpha and may change significantly in the near future. As always, input is appreciated.
+
+
+#### submit\_buttons
+
+    form.submit_buttons << 'Preview'
+
+    
+By default, there is one button at the bottom of the form, saying either "Create" or "Update". By appending to this array you can specify other buttons, and then check if those buttons were clicked in `destination_after_save`, below.
+
+### Column config options
+
+#### datetime\_select\_options
+
+    form[:published_at].datetime_select_options =
+        {:include_blank => false, :start_year => 2009}
+
+Passes through these options to the datetime select for this column. By default this is set to `{:include_blank => true}`.
+
+#### default
+
+    form[:published_at].default do |controller|
+      controller.default_published_at
+    end
+
+Sets a default value for the column when rendering the new form.
+
+        
+#### description
+
+    form[:publish].description = "Click this check box to publish this blog post."
+
+Sets descriptive text that will appear next to the column's input.
+
+#### image\_size
+
+    form[:image].image_size = '300x500'
+
+By default, [Paperclip] and [FileColumn] image files are rendered at full-size in the form. To restrict their size, pass a size string to `image_size`.
+
+#### input
+
+    form[:publish].input = :check_box
+
+Currently supports `:check_box`, `:select`, `:text_area`, and `:us_state`. `:us_state` will render a drop-down with U.S. states.
+
+#### nilify\_link
+
+Date and datetime fields come with a javascript link the clears the value in the date or datetime selects. The text of this link is "Set \[column name\] to nil" by default, but you may want to customize this text:
+
+    form[:sale_starts_at].nilify_link = 'Not on sale'
+
+
+#### read\_only
+
+    a.form[:comment].read_only
+
+If this is set, the given column will only be displayed, and not editable.
+
+
+#### select\_choices
+
+    form[:admin_level].select_choices = %w(normal admin superuser)
+    
+Uses this with select inputs to set or override what is passed to Rails' `select` method as its `choices` argument.
+
+
+#### select\_options
+
+    form[:user].select_options = {:include_blank => false}
+
+Use this with belongs-to associations to tell admin\_assistant how to configure the `select` dropdown for the associated field. By default, this is set to `{:include_blank => true}`.
+
+#### text\_area\_options
+
+    form[:body].text_area_options = {:cols => 20, :rows => 40}
+
+Sets options to pass through to the text area that will be rendered for this column.
+
+#### write\_once
+
+    form[:body].write_once
+    
+If this is set, the given column will only be editable on the new page, not on the edit page.
+
+
+### Controller methods
+
+#### after\_save
+
+Runs after the record is saved.
+
+#### before\_create
+
+Runs before the record is created.
+
+#### before\_save
+
+    def before_save(blog_post)
+      if params[:blog_post][:publish] && blog_post.published_at.nil?
+        blog_post.published_at = Time.now.utc
+      end
+    end
+
+Runs before the record is saved.
+
+#### before\_update
+
+Runs before the record is updated.
+
+
+#### before\_validation
+
+Runs before the record is validated.
+
+
+#### \[column\]\_exists?
+
+Used for image fields in generating form pages. If this method exists on the controller, it will be called to see if the image exists. You'll probably use this in conjunction with `[column]_url` and `destroy_[column]_in_attributes`.
+
+    def tmp_avatar_exists?(user)
+      user.has_avatar?
+    end
+
+#### \[column\]\_url
+
+Used for image fields in generating form pages. If the existing record has an image, and this method exists on the controller, it will be called to get the URL that should be rendered. You'll probably use this in conjunction with `[column]_exists?` and `destroy_[column]_in_attributes`.
+
+    def tmp_avatar_url(user)
+      "http://my-image-server.com/users/#{user.id}.jpg?v=#{user.avatar_version}"
+    end
+
+
+
+#### \[column\]\_from\_form
+
+    def tags_from_form(tags_strings)
+      tags_strings.split(/\s+/).map { |tag_str|
+        Tag.find_by_tag(tag_str) || Tag.create(:tag => tag_str)
+      }
+    end
+
+Should return a value suitable for assignment. In the above example, a BlogPost has-many tags, and the method tags\_from\_form will turn the string `"funny, video, lolcat"` into an array of three Tag model records, so admin\_assistant can set BlogPost#tags to that array.
+
+If you need to return a value from another parameter, you can accept a second argument, which will be the params hash for the record.
+
+    def title_from_form(title_str, record_params)
+      if title_str.blank?
+        record_params[:title_alt]
+      else
+        title_str
+      end
+    end
+
+If the value being returned is meant to be assigned through an association, you may find it useful to return custom errors to work around the strangeness of ActiveRecord's association-assignment error-handling. So admin\_assistant lets you optionally take a 3rd errors argument, which you can use to attach errors to the core model. This error object isn't returned, but changes to it will persist outside the body of the method.
+
+    def tags_from_form(tags_string, record_params, errors)
+      tags = tags_string.split(/\s+/).map { |tag_str|
+        Tag.find_by_tag(tag_str) || Tag.create(:tag => tag_str)
+      }
+      if tags.any? { |t| !t.valid? }
+        errors.add(:tags, "One or more tags was invalid")
+      end
+      tags
+    end
+
+
+
+
+#### destination\_after\_save
+
+    def destination_after_save(blog_post, params)
+      if params[:commit] == 'Preview'
+        {:action => 'edit', :id => blog_post.id, :preview => '1'}
+      end
+    end
+
+This method should return a hash to redirect to after a successful save. If it returns nil, the default is to return to the index page.
+
+#### destroy\_\[column\]\_in\_attributes
+
+Used for image fields. If a file field already exists, and the user clicks on the checkbox to delete this file, this method will be called if it's defined. You'll probably use this in conjunction with `[column]_exists?` and `[column]_exists?`.
+
+    def destroy_tmp_avatar_in_attributes(attributes)
+      attributes[:has_avatar] = false
+    end
+    
+    
+#### validate
+
+Runs after the model's built-in validation, before admin\_assistant tries to save the model.
+
+
+### Helper methods
+
+#### after\_\[column\]\_input
+
+If this helper method is present, whatever text it returns will be rendered after the default input for the column in the form. Takes the record as its only argument. You can also create a partial named `_after_[column]_input.html.erb`.
+
+    def after_password_input(user)
+      if user.id
+        "Reset #{check_box_tag('reset_password')}"
+      end
+    end
+
+#### \[column\]\_input
+
+If this helper method is present, whatever text it returns will be rendered instead of the default input for the column in the form. If it returns nil, the default input will be rendered instead. Takes the record as its only argument.
+
+    def password_input(user)
+      if !user.id
+        "(autogenerated)"
+      end
+    end
+
+You can also create a partial named `_[column]_input.html.erb`.
+
+#### \[column\]\_string
+
+If this helper method is present, its returned string will be rendered within a text field. Odds are you'll use this with the controller method `[column]_from_form`, above.
+
+    def tags_string(blog_post)
+      blog_post.tags.map { |tag| tag.tag }.join ' '
+    end
+
+
+### Partials
+
+#### \_\[column\]\_input.html.erb
+
+If this partial is present, it will be rendered instead of the default input for the column. 
+
+#### \_after\_\[column\]\_input.html.erb
+
+
+If this partial is present, it will be rendered after the default input for the column. You can also use the helper method `after_[column]_input`.
+
+#### \_after\_form.html.erb
+
+If this partial is present in the controller's views directory, it will be rendered after the normal form.
+
+
+[FileColumn]: http://www.kanthak.net/opensource/file_column/
+[Paperclip]: http://thoughtbot.com/projects/paperclip
+

data/website/api/idx.markdown

@@ -0,0 +1,286 @@
+---
+layout: api
+title:  Index
+---
+
+![index](../img/blog_posts-index.png)
+
+The index is the action that lets you view all records, with pagination and sorting. To customize it by getting the index builder inside of your admin\_assistant config:
+
+    class Admin::BlogPostsController < ApplicationController
+      admin_assistant_for BlogPost do |a|
+        a.index do |index|
+          index.columns :user, :title
+          index.sort_by 'published_at desc'
+        end
+      end
+    end
+
+### Index config options
+
+#### actions
+
+    index.actions['All'] = {:all => '1'}
+
+Adds more links to the upper-right hand-corner. By default there are two links there: "Search", and "New \[model name\]". If you have any other specific links to add, you can add them with index.actions, and they will be added to the right of those default two links.
+
+#### cache\_total\_entries
+
+    index.cache_total_entries 12.hours
+    
+This is an optimization for large tables. Some databases are slow when trying to simply get the number of records in the table; but this number is required for any paginated view. If your index views are slow because of this, you should consider setting `cache_total_entries` to some amount of time. This will cache the count SQL request, so that the count will be slightly off for some period of time, but that probably doesn't matter if you have, for example, 150,000 users.
+
+
+#### conditions
+
+Specifies additional SQL that can restrict the records shown in the index view. This can be a simple string:
+
+    index.conditions "deleted_at is null"
+
+It can also be a block that will be passed the params hash:
+
+    index.conditions do |params|
+      "deleted_at is null" unless params[:all]
+    end
+
+This can also be accomplished with a protected controller method `conditions_for_index`; see below.
+
+#### per\_page
+
+    index.per_page 100
+
+By default, 25 rows per page will be shown. Set per\_page to set it to another number.
+
+#### columns
+
+    index.columns :user, :title
+
+If called, restricts which columns are shown. By default admin\_assistant will try to show all columns on the DB table, which will probably be too much if your table has a lot of columns.
+
+Can also be used to add model methods that aren't database fields.
+
+#### header
+
+    index.header do |params|
+      if params[:all]
+        "Blog posts (all)"
+      else
+        "Blog posts (unpublished)"
+      end
+    end
+
+For customization the text at the top of the page; takes a block with params as its argument
+
+#### include
+
+    index.include :users
+    
+Accepts one or more association names to be eagerly loaded by ActiveRecord.
+
+<a name="builder_right_column_links"></a>
+#### right\_column\_links
+
+By default, there are two links on the right-hand side of the row for each model: "Edit" and "Show". You can add new ones by appending to `right_column_links`:
+
+    index.right_column_links << lambda { |blog_post|
+      [
+        "New comment for this blog post",
+        {:controller => '/admin/comments', :action => 'new',
+         :comment => {:blog_post_id => blog_post.id }}
+      ]
+    }
+
+The lambda should receive the model and return a two-element array: The first element should be the text of the link and the second should be the URL parameters for that link.
+
+See also the helper method [extra\_right\_column\_links\_for\_index](#helper_extra_right_column_links_for_index).
+
+#### search
+
+    index.search :id, :title
+
+Shortcut to Search [`columns`](/api/search.html#builder_columns) .
+
+#### sort\_by
+
+Sets the default sorting of records, which will be used unless the user has specified sorting by clicking any of the sort headers. This can be a SQL string:
+
+    index.sort_by 'published_at desc, id asc'
+
+It can also just be a belongs-to association:
+
+    index.sort_by :user
+
+In the case of a belongs-to association, by default it will search for fields called `name`, `title`, `login`, or `username` on the associated model and use that.
+
+#### total\_entries
+
+    index.total_entries = do
+      BlogPost.cached_count
+    end
+
+This block will be called during pagination to provide the total number of records. This can come in handy if you have a huge number of records and are finding the count(\*) SQL statement too expensive.
+
+### Column config options
+
+There are also configurations that can be applied to specific columns in the index view.
+
+#### ajax\_toggle
+
+    index[:textile].ajax_toggle = false
+    
+By default, all boolean fields displayed in the index can be toggled with an Ajax link. Set `ajax_toggle` to false to disable this behavior.
+
+#### image\_size
+
+    index[:image].image_size = '300x500'
+
+By default, [Paperclip] and [FileColumn] image files are rendered at full-size in the index. To restrict their size, pass a size string to `image_size`.
+
+
+#### link\_to\_args
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost do |aa|
+        aa.index[:user].link_to_args do |blog_post|
+          {:controller => 'admin/users', :action => 'edit',
+           :id => blog_post.user_id }
+        end
+      end
+    end
+    
+
+If you'd like this column to link somewhere from the index view, set this with a block that returns a hash for `url_for` when called.
+
+Note that this block takes the base record as its argument, not the value of the specific column or association. In the example above, the base model is BlogPost, so the block is receiving a blog post, not the associated user.
+
+### Controller methods
+
+#### before\_render\_for\_index
+
+If defined on your controller, this hook is executed just before render takes place for the index action.
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost
+  
+      protected
+  
+      # Blog post authors should not be visible if they have requested anonymity
+      def before_render_for_index
+        @index.records.each do |record|
+          record.author = nil if record.author.requested_anonymity?
+        end
+      end
+    end
+
+#### conditions\_for\_index
+
+    def conditions_for_index
+      "deleted_at is null" unless params[:all]
+    end
+
+Specifies additional SQL that can restrict the records shown in the index view.
+
+Can also be set via `index.conditions`; see `conditions` above.
+
+### Helper methods
+
+#### \[column\]\_html\_for\_index
+
+    def title_html_for_index(blog_post)
+      "TITLE #{blog_post.title.capitalize}"
+    end
+
+If this method exists on the helper, it will be used to render the HTML shown in each row for the column in question. It takes the model as its only argument.
+
+<a name="helper_extra_right_column_links_for_index"></a>
+#### extra\_right\_column\_links\_for\_index
+
+By default, there are two links on the right-hand side of the row for each model: "Edit" and "Show". You can add new ones by returning them from `extra_right_column_links_for_index`:
+
+    def extra_right_column_links_for_index(blog_post)
+      link_to(
+        'New comment',
+        {
+          :controller => 'admin/comments', :action => 'new',
+          :comment => {:blog_post_id => blog_post.id}
+        }
+      )
+    end
+
+Also see the builder method [right\_column\_links](#builder_right_column_links).
+
+#### link\_to\_new\_in\_index?
+
+The link to create a new record will be shown on the index view if there is a 'new' action for the controller (whether via admin\_assistant or otherwise). If you don't want the link generated, define a helper method like this:
+
+    def link_to_new_in_index?
+      false
+    end
+
+#### link\_to\_search\_in\_index?
+
+The link to the search form will be shown unless it is prevented using a define a helper method like this:
+
+    def link_to_search_in_index?
+      false
+    end
+
+#### link\_to\_edit\_in\_index?
+
+The edit link in the right column of each row will be shown if there is a 'edit' action for the controller (whether via admin\_assistant or otherwise). If you don't want the link generated, define a helper method like this:
+
+    def link_to_edit_in_index?(blog_post)
+      false
+    end
+
+#### link\_to\_delete\_in\_index?
+
+The delete link in the right column of each row will be shown if there is a 'destroy' action for the controller (whether via admin\_assistant or otherwise). If you don't want the link generated, define a helper method like this:
+
+    def link_to_delete_in_index?(blog_post)
+      false
+    end
+
+#### link\_to\_show\_in\_index?
+
+The show link in the right column of each row will be shown if there is a 'show' action for the controller (whether via admin\_assistant or otherwise). If you don't want the link generated, define a helper method like this:
+
+    def link_to_show_in_index?(blog_post)
+      false
+    end
+    
+#### \[column\]\_css\_class\_for\_index\_td
+
+To add a css class to a table cell, define a helper method based on the name of the column:
+
+    def user_css_class_for_index_td(blog_post)
+      'custom_td_css_class'
+    end
+
+#### css\_class\_for\_index\_tr
+
+To add a css class to a table row, define a helper method like so:
+
+    def css_class_for_index_tr(blog_post)
+      'custom_tr_css_class'
+    end
+
+### Partials
+
+#### \_after\_index.html.erb
+
+If this partial is present, it will be rendered after the entire index HTML.
+
+#### \_before\_index.html.erb
+
+If this partial is present, it will be rendered before the entire index HTML.
+
+
+
+[FileColumn]: http://www.kanthak.net/opensource/file_column/
+[Paperclip]: http://thoughtbot.com/projects/paperclip
+