admin_assistant 2.0.0 → 2.0.1

data/website/v1/api/idx.markdown

@@ -0,0 +1,288 @@
+---
+layout: default
+title:  "Version 1 API: Index"
+subtitle: Index
+subnav:   api1
+---
+
+![index](/admin_assistant/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`](/admin_assistant/v1/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
+

data/website/v1/api/index.markdown

@@ -0,0 +1,149 @@
+---
+layout:   default
+title:    "Version 1 API"
+subnav:   api1
+---
+
+### Reference sections
+
+The API reference is broken down into a few sections:
+
+* [Core](/admin_assistant/v1/api/core.html): Settings that apply to an admin controller in general.
+* [Destroy](/admin_assistant/v1/api/destroy.html): Settings that apply to destroying records. Note that `destroy` is turned off by default. To turn it on, use the core [actions](/admin_assistant/v1/api/core.html#builder_actions) method.
+* [Form](/admin_assistant/v1/api/form.html): Settings that apply to creating or updating records.
+* [Index](/admin_assistant/v1/api/idx.html): Settings that apply to the index view, which you use to view records, paginate, and sort.
+* [Search](/admin_assistant/v1/api/search.html): Settings that apply to how searches work.
+* [Show](/admin_assistant/v1/api/show.html): Settings that apply to how the show view.
+
+
+### Configuration overview
+
+
+There are a number of ways to configure admin\_assistant:
+
+#### Through builder objects
+
+`admin_assistant_for` takes a block that yields a core builder object:
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost do |aa|
+        aa.model_class_name = 'post'
+      end
+    end
+
+For the actions `form` and `index`, you can get a nested builder from the core builder, which can be used to configure those individual action types.
+
+    admin_assistant_for BlogPost do |aa|
+      aa.index do |index|
+        index.sort_by "name asc"
+      end
+    end
+
+The nesting is intended to help organize your configuration code, but if you're in a hurry, you can also just chain the calls:
+
+    admin_assistant_for BlogPost do |aa|
+      aa.index.sort_by "name asc"
+    end
+
+Since `search` is really a subset of `index`, its configuration builder is reached through the index builder.
+
+    admin_assistant_for BlogPost do |aa|
+      aa.index do |index|
+        index.search do |search|
+          search.columns :id, :title, :body
+        end
+      end
+    end
+
+#### Columns on builder objects
+
+Columns are specified on the action-types `index`, `form`, or `search`:
+
+    admin_assistant_for BlogPost do |aa|
+      aa.index.columns :id, :title, :body
+    end
+    
+There is no global `columns` setting.
+
+These columns can be accessed with `[]`, either globally, or specific to an action-type, depending on what sort of setting is being altered.
+
+    admin_assistant_for BlogPost do |aa|
+      # this will apply to the :title column, both on form and index views
+      aa[:title].label = "Headline"  
+    
+      aa.form do |form|
+        form.columns :id, :title, :body
+        
+        # This will only apply to the :title column in the form view
+        form[:title].description = "Enter the headline of your blog post here."
+      end
+    end
+
+If you're dealing with an association, generally speaking, you'll use the column of the association name, not the foreign key ID in the database.
+
+    admin_assistant_for BlogPost do |aa|
+      aa.index.columns :id, :title, :user   # as opposed to :user_id
+    end
+
+#### Protected controller methods
+
+For certain types of settings, the `form` and `index` action types can be customized through protected methods on the controller.
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost
+      
+      protected
+      
+      # The index action only shows unpublished blog posts, unless somebody has
+      # clicked the custom "Show All" link
+      def conditions_for_index
+        "published_at is null" unless params[:all]
+      end
+    end
+
+Remember to make these methods protected so that Rails won't try to use them as public-facing actions, i.e. `http://www.example.com/admin/blog_posts/conditions_for_index`.
+
+In a number of cases, you can get the same customization by passing a block to the builder object. For example, the code below works the same as the previous example:
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost do |aa|
+        aa.index.conditions do |params|
+          "published_at is null" unless params[:all]
+        end
+      end
+    end
+
+The trade-off here is that customizing this behavior through a block is probably a little neater---fewer methods scattered all over your controller---but isn't bound to the controller. So if you find yourself needing some convenience methods on, say, `ApplicationController`, you'll be better off using a protected controller method.
+
+#### Helper methods and partials
+
+Other behaviors can be set by creating certain methods on the helper. Usually these behaviors have to do with presentation.
+
+    class Admin::UsersHelper
+      def password_input(user)
+        password_field_tag("user[password]", user.password, :disabled => true)
+      end
+    end
+
+Often you can accomplish the same thing with a partial. For example, the functionality in the above example could also be accomplished with the following saved in `app/views/admin/users/_password_input.html.erb`.
+
+    <%= password_field_tag("user[password]", user.password, :disabled => true) %>
+    
+#### Model methods
+
+admin\_assistant can also look for methods to be defined on models, themselves. This is generally for behaviors that would apply across all admin controllers.
+
+    class ProductCategory < ActiveRecord::Base
+      def name_for_admin_assistant
+        self.category_name
+      end
+    end
+
+Generally speaking there won't be many of these hooks, because in practice this can make the admin\_assistant API sort of invasive. Unless your Rails project is 99% the admin interface, it's going to get annoying to keep tripping over admin\_assistant-specific hooks when you're trying to write some front-facing code.
+

data/website/v1/api/search.markdown

@@ -0,0 +1,110 @@
+---
+layout: default
+title:  "Version 1 API: Search"
+subtitle: Form
+subnav:   api1
+---
+
+![index](/admin_assistant/img/blog_posts-search.png)
+
+Search restricts the records viewed in [Index] by various criteria. By default, search presents a single text field, and text entered in this field will be compared to all string and text fields in the table. By setting #columns you can have the search form specify which fields are being searched on.
+
+Since search is closely related to [Index], its configuration is reached through the index builder:
+
+    class Admin::BlogPostsController < ApplicationController
+      admin_assistant_for BlogPost do |a|
+        a.index do |index|
+          index.search do |search|
+            search.columns :title, :user
+          end
+        end
+      end
+    end
+
+You can chain calls to get to the search builder more quickly:
+
+    class Admin::BlogPostsController < ApplicationController
+      admin_assistant_for BlogPost do |a|
+        a.index.search do |search|
+          search.columns :title, :user
+        end
+      end
+    end
+
+### Search config options
+
+#### columns
+<a name="builder_columns"> </a>
+
+    search.columns :title, :user
+
+Call this method to set the search to supply one input for each column. When you set multiple search columns, users get the option of searching on all entered columns or any of them.
+
+You can also call this with Index#search:
+
+    index.search :title, :user
+    
+#### default\_search\_matches\_on
+
+If you don't specify any columns, the search form is simply one field, and whatever text is entered in that field will be compared to every text and string field on the database table. If there are other fields you'd like the default search to compare with, you can add them using `default_search_matches_on`. For example, to give users the ability to search by ID:
+
+      index.search.default_search_matches_on :id
+
+You can also pass in SQL fragments:
+
+      index.search.default_search_matches_on \
+            "concat_ws(' ', users.first_name, users.last_name)"
+
+#### include\_params\_in\_form
+            
+      index.search.include_params_in_form = true
+      
+This will put any custom page params in the search form to be posted with the search parameters. You might use this if you've got another way of filtering, say, blog posts by user, and you want the search form on that page to only search within blog posts by that user.
+
+      
+### Column config options
+
+These are configurations that can be applied to specific columns in the search.
+
+#### comparators
+
+    search[:price].comparators = false
+    
+By default, integer and datetime fields are presented with a list of options for comparing to the entered value: "greater than", "greater than or equal to", "equal to", "less than or equal to", and "less than". This way the user can do a search like "show me all products that cost more than $100."
+
+To turn this off, set `comparators` to false.
+
+#### compare\_to\_range
+
+    search[:price].compare_to_range = true
+    
+If you want to offer a ranged search, set `compare_to_range` to true. This will render two fields for greater-than and less-than in the search.
+    
+#### conditions
+
+    search[:has_short_title].field_type = :boolean
+    search[:has_short_title].conditions do |has_short_title|
+      if has_short_title
+        "length(title) < 10"
+      elsif has_short_title == false
+        "length(title) >= 10"
+      end
+    end
+    
+To be used with a virtual column in search. The block should return a SQL fragment to add to the final query, or nil to not change anything.
+
+#### match\_text\_fields\_for\_association
+
+    search[:user].match_text_fields_for_association
+
+Only applies to belongs-to associations. By default, belongs-to associations will be searchable using a dropdown of the associated records that currently exist. Calling `match_text_fields_for_association` will mean the input for that association will be a text input instead, and that text will be matched against all text or string fields on the associated record.
+
+For example, let's say you have a BlogPost that belongs to a User. With this configuration on Admin::BlogPostsController:
+
+    search.columns :user
+    search[:user].match_text_fields_for_association
+
+... the search form will be one field, a text input labeled "User". If the user enters "an" in that field, it will match against all blog posts by the users with the username field of "Andy", "Andrew", and "Frank".
+
+
+[Index]: /admin_assistant/v1/api/idx.html

data/website/v1/api/show.markdown

@@ -0,0 +1,24 @@
+---
+layout: default
+title:  "Version 1 API: Show"
+subtitle: Show
+subnav:   api1
+---
+
+Show configuration affects what is displayed in a show page, e.g. `/admin/blog_posts/show/5`.
+
+### Show config options
+
+#### columns
+
+    admin_assistant_for BlogPost do |aa|
+      aa.show.columns :user, :title, :body
+    end
+
+Shows only these columns in the show page.
+
+### Partials
+
+#### \_\[column\]\_for_show.html.erb
+
+If this partial is present, it will be rendered instead of the default HTML for the column.

data/website/v1/index.markdown

@@ -0,0 +1,10 @@
+---
+layout:   default
+title:    Version 1 documentation
+---
+
+Below are the documents for admin\_assistant 1, which supports Rails 2.1.x through 2.3.x. Note that admin\_assistant 1 is deprecated, and that will only see bugfixes from now on.
+
+* [Quick start](/admin_assistant/v1/quick_start.html)
+* [Tutorial](/admin_assistant/v1/tutorial.html)
+* [API](/admin_assistant/v1/api/)

data/website/v1/quick_start.markdown

@@ -0,0 +1,48 @@
+---
+layout: default
+title:  "Quick start: admin_assistant 1"
+---
+
+<div class="note">
+This document assumes you are highly familiar with Ruby and Rails; if you are a beginning Rails user you might want to start with our  <a href="/admin_assistant/v1/tutorial.html">tutorial</a>.
+</div>
+
+1) Include the gem in `config/environment.rb`.
+
+    config.gem 'admin_assistant', :version => '1.0.2'
+
+2) Install the gem and dependencies into `vendor/gems`.
+
+    rake gems:unpack:dependencies
+
+3) admin\_assistant comes packaged with standard CSS and Javascript that you should include in whatever layout your admin controllers will be using. You'll also need to make sure to include prototype.js, effects.js, and controls.js, if you're not including them already.
+
+    <html>
+      <head>
+        <%= javascript_include_tag("prototype", "effects", "controls") %>
+        <%= admin_assistant_includes %>
+      </head>
+      ...
+    </html>
+
+4) Setup an admin controller by attaching it to a model and using the admin layout:
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost
+    end
+
+That's it for the basic version. You should now be able to go to /admin/blog\_posts in your app and search, paginate, create, and edit blog posts.
+
+![index](/admin_assistant/img/blog_posts-index.png)
+
+Depending on the model you're using, you might notice a few things:
+
+* Boolean values can be toggled on and off in the index view.
+* Any belongs-to associations are handled in the form by either a drop-down, or an Ajax autocompleter, depending on how many choices there are for the association.
+* There is no `destroy` action out of the box. This is intended as a safe default, but you can add it if you like.
+* If you have more than 10 pages of a given model, the pagination at the bottom includes a jump form to let you automatically jump to a page you enter.
+
+For more, check out the [API reference](/admin_assistant/v1/api/).
+

data/website/v1/tutorial.markdown

@@ -0,0 +1,60 @@
+---
+layout: default
+title:  "Tutorial: admin_assistant 1"
+---
+
+<div class="note">
+This document assumes you are a beginning Rails user; if you are very familiar with Rails you might want to check out our <a href="/admin_assistant/v1/quick_start.html">quick start</a>.
+</div>
+
+1) Include the gem in `config/environment.rb`.
+
+    config.gem 'admin_assistant', :version => '1.0.2'
+
+2) Install the gem and dependencies `vendor/gems`.
+
+    rake gems:unpack:dependencies
+
+3) If you don't have any admin controllers in your Rails project yet, you probably need to create a separate admin layout. Create a file called `app/views/layouts/admin.html.erb` like this:
+
+    <html>
+      <head>
+        <%= javascript_include_tag("prototype", "effects", "controls") %>
+        <%= admin_assistant_includes %>
+      </head>
+      <body>
+        <%=yield %>
+      </body>
+    </html>
+    
+If you've already created an admin layout, you should add the javascript references, and the call to `admin_assistant_includes`. This includes the standard CSS and Javascript that are packed with admin\_assistant.
+    
+4) Create your new admin controller for a pre-existing model. We'll be using a BlogPost as an example but you should be able to use any model in your Rails app.
+
+    ./script/generate controller admin/blog_posts
+    
+5) Open `app/controllers/admin/blog_posts_controller.rb` and set it up to use the admin layout and to use admin\_assistant for the BlogPost model:
+
+    class Admin::BlogPostsController < ApplicationController
+      layout 'admin'
+
+      admin_assistant_for BlogPost
+    end
+
+6) If you were already running your Rails app with `./script/server` etc, you should restart it.
+
+7) Visit `/admin/blog_posts` in your browser and you'll see something like this:
+
+![index](/admin_assistant/img/blog_posts-index.png)
+
+You can now search, paginate, create, and edit blog posts.
+
+Depending on the model you're using, you might notice a few things:
+
+* Boolean values can be toggled on and off in the index view.
+* Any belongs-to associations are handled in the form by either a drop-down, or an Ajax autocompleter, depending on how many choices there are for the association.
+* There is no `destroy` action out of the box. This is intended as a safe default, but you can add it if you like.
+* If you have more than 10 pages of a given model, the pagination at the bottom includes a jump form to let you automatically jump to a page you enter.
+
+For more, check out the [API reference](./api/).
+