admin_assistant 1.0.0 → 1.0.1

data/website/api/index.markdown

@@ -0,0 +1,147 @@
+---
+layout: api
+---
+
+### Reference sections
+
+The API reference is broken down into a few sections:
+
+* [Core](./core.html): Settings that apply to an admin controller in general.
+* [Destroy](./destroy.html): Settings that apply to destroying records. Note that `destroy` is turned off by default. To turn it on, use the core [actions](./core.html#builder_actions) method.
+* [Form](./form.html): Settings that apply to creating or updating records.
+* [Index](./idx.html): Settings that apply to the index view, which you use to view records, paginate, and sort.
+* [Search](./search.html): Settings that apply to how searches work.
+* [Show](./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/api/search.markdown

@@ -0,0 +1,108 @@
+---
+layout: api
+title:  Search
+---
+
+![index](../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]: ./idx.html

data/website/api/show.markdown

@@ -0,0 +1,22 @@
+---
+layout: api
+title:  Show
+---
+
+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/community.markdown

@@ -0,0 +1,27 @@
+---
+layout:   default
+title:    Community
+---
+
+### Mailing list
+
+We have a mailing list over at [Google Groups](http://groups.google.com/group/admin_assistant). If you have a question, please consider asking it there instead of a direct email, in the hopes that the  next person who has the same question might find the answer by just Googling it.
+
+<a name="whos_using"></a>
+### Who's using admin\_assistant?
+
+admin\_assistant is being used on the following sites:
+
+* [boundlessny.com](http://www.boundlessny.com/) by [Michael Celona][mcelona]
+* [casahelga.com](http://casahelga.com) by [Alex Farrill][afarrill]
+* [fhwang.net](http://fhwang.net) by [Francis Hwang][fhwang]
+* [sling.com](http://www.sling.com) by [Diversion Media](http://www.diversionmedia.com/)
+* [stockblotter.com](http://stockblotter.com) by [Alex Farrill][afarrill]
+
+If you're also using admin\_assistant, and would like to be listed here, please get in touch with us on the mailing list.
+
+
+
+[afarrill]: http://www.linkedin.com/in/alexfarrill
+[fhwang]: http://fhwang.net/
+[mcelona]: http://www.linkedin.com/in/mcelona

data/website/css/lightbox.css

@@ -0,0 +1,29 @@
+#lightbox{	position: absolute;	left: 0; width: 100%; z-index: 100; text-align: center; line-height: 0;}
+#lightbox img{ width: auto; height: auto;}
+#lightbox a img{ border: none; }
+
+#lightboxImage { border: 1px solid #008; }
+
+#outerImageContainer{ position: relative; background-color: #fff; width: 250px; height: 250px; margin: 0 auto; }
+#imageContainer{ padding: 10px; }
+
+#loading{ position: absolute; top: 40%; left: 0%; height: 25%; width: 100%; text-align: center; line-height: 0; }
+#hoverNav{ position: absolute; top: 0; left: 0; height: 100%; width: 100%; z-index: 10; }
+#imageContainer>#hoverNav{ left: 0;}
+#hoverNav a{ outline: none;}
+
+#prevLink, #nextLink{ width: 49%; height: 100%; background-image: url(data:image/gif;base64,AAAA); /* Trick IE into showing hover */ display: block; }
+#prevLink { left: 0; float: left;}
+#nextLink { right: 0; float: right;}
+#prevLink:hover, #prevLink:visited:hover { background: url(../img/lightbox/prevlabel.gif) left 15% no-repeat; }
+#nextLink:hover, #nextLink:visited:hover { background: url(../img/lightbox/nextlabel.gif) right 15% no-repeat; }
+
+#imageDataContainer{ font: 10px Verdana, Helvetica, sans-serif; background-color: #fff; margin: 0 auto; line-height: 1.4em; overflow: auto; width: 100%	; }
+
+#imageData{	padding:0 10px; color: #666; }
+#imageData #imageDetails{ width: 70%; float: left; text-align: left; }	
+#imageData #caption{ font-weight: bold;	}
+#imageData #numberDisplay{ display: block; clear: left; padding-bottom: 1.0em;	}			
+#imageData #bottomNavClose{ width: 66px; float: right;  padding-bottom: 0.7em; outline: none;}	 	
+
+#overlay{ position: absolute; top: 0; left: 0; z-index: 90; width: 100%; height: 500px; background-color: #000; }

data/website/css/main.css

@@ -0,0 +1,70 @@
+body {
+  margin: 0;
+	font-family: Verdana, "Bitstream Vera Sans", sans-serif;
+}
+
+h1 {
+  width: 900px;
+  margin: auto;
+  padding: 10px;
+}
+
+h1 a, h1 a:visited {
+  text-decoration: none;
+  color: black;
+}
+
+h1 a:hover {
+  background: #ff3;
+}
+
+code {
+  background: #ffd;
+  border: #ff6 1px solid;
+  font-size: large;
+}
+
+pre {
+  background: #ffd;
+  border: #ff6 1px solid;
+  padding: 5px;
+  font-size: large;
+}
+
+pre code {
+  border: none;
+}
+
+#body {
+  width: 900px;
+  margin: auto;
+  padding-bottom: 25px;
+}
+
+#page_header {
+  background: #ffc
+}
+
+#page_header .nav {
+  width: 900px;
+  margin: auto;
+  padding-bottom: 10px;
+}
+
+#page_header .nav a, #page_header .nav a:visited {
+  text-decoration: none;
+  color: black;
+}
+
+#page_header .nav a:hover {
+  background: #ff3;
+}
+
+.subnav {
+  margin-top: -20px;
+  font-size: small;
+}
+
+.thumb {
+  margin-right: 10px;
+}

data/website/design_principles.markdown

@@ -0,0 +1,50 @@
+---
+layout:   default
+title:    Design principles
+---
+
+admin\_assistant is built with a few design principles in mind:
+
+### Relentless full-stack testing
+
+admin\_assistant is tested against a complete, self-contained Rails app in the `test_rails_app` directory. This app serves as the reference implementation of admin\_assistant, so new features can be added with minimal worry of breaking old features.
+
+In addition, this test suite can be run against multiple versions of Rails, making multi-version support possible.
+
+
+### Wide support of Rails versions
+
+admin\_assistant currently supports six versions of Rails: 2.1.0, 2.1.2, 2.2.2, 2.3.2, 2.3.3, and 2.3.4. We offer this support by writing a test suite that can be run with different versions of Rails. After all, it doesn't make any sense to release a plugin intended for other programmers' convenience, and then tell them to drop everything and spend the next two weeks upgrading their whole app.
+
+
+### Deeply customizable API
+
+It's great to be able to do the quick boilerplate CRUD operations, but it doesn't take long before you need a lot of custom functionality. So, while admin\_assistant can be set up in a few lines, its real strength is all the hooks it offers you:
+
+* Labeling of models and columns
+* Links at a page level, record level, or field level
+* Selection of columns to include in index views and in forms
+* Field value display in index views
+* Custom inputs, submit buttons, descriptions in forms
+* Partials can be rendered before or after forms, or column inputs.
+* Custom options for date selects, datetime selects, textarea tags, etc. can be set up on a per-column level and passed through to the underlying Rails method.
+* Custom redirecting after successful saves
+
+If you're copying and pasting something out of `vendor/plugins/admin_assistant`, that's a design flaw.
+
+
+### Minimally invasive
+
+If you like, you can use admin\_assistant in a very self-contained way, meaning that any admin functionality you add to your application doesn't have to affect any other parts of the code.
+
+For example, standard ActiveRecord callbacks like `after_save` and `before_create` can be mimicked in the admin controller, in case you want to contain that code to one particular controller, instead of having to think about how it might affect other code that's using that model.
+
+In addition, admin\_assistant doesn't override or `alias_method_chain` anything in Rails core, which greatly reduces the possibility that admin\_assistant would conflict with another plugin.
+
+
+### Safe defaults
+
+admin\_assistant is opinionated in its own way, much of which has to do with picking the most safe default behavior possible.
+
+* The `destroy` action is turned off by default, since the decision to allow a way to erase production data should be taken seriously.
+* Date selects and datetime selects in forms are blank by default, not the current date or time. This helps avoid a situation on models with many fields where dates and datetimes can be set by accident, changing the site's behavior in unexpected ways. The current date or time is usually not a useful default, anyway.

data/website/getting_started.markdown

@@ -0,0 +1,10 @@
+---
+layout: default
+title:  Getting started
+---
+
+This page has been [moved](/admin_assistant/quick_start.html).
+
+<script>
+window.location.href = "/admin_assistant/quick_start.html";
+</script>

data/website/index.markdown

@@ -0,0 +1,35 @@
+---
+layout:   default
+---
+
+admin\_assistant is a Rails plugin that automates a lot of features typically needed in admin controllers. It is written and maintained by [Francis Hwang][fhwang].
+
+admin\_assistant is in beta, meaning that it is stable, and being used in production sites, but there may be small API changes in the future.
+
+It currently supports Rails 2.1.0, 2.1.2, 2.2.2, 2.3.2, 2.3.3, and 2.3.4. There are no plans to support Rails 2.0 or earlier.
+
+
+## Features
+
+* Built-in model creation, updating, and deletion.
+* Live querying of models, which allows incremental development of controllers without the maintenance problems of generated code.
+* Paginated indexes with built field-ordering.
+* Highly customizable search that allows customization of individual fields, numerical comparators, and boolean operators.
+* Built-in Ajax autocompleters for handling belongs-to associations.
+* Built-in widgets for handling polymorphic belongs-to associations.
+* Built-in support for images with either [Paperclip](http://thoughtbot.com/projects/paperclip) or [FileColumn](http://www.kanthak.net/opensource/file_column/).
+* Heavily hookable interface allows customization of columns, search parameters, form inputs, parameter handling, and model creation.
+
+
+## Still not convinced?
+
+Check out our [screenshots](./screenshots.html), [who's using admin\_assistant](./community.html#whos_using), or our [design principles](./design_principles.html).
+
+
+## Ready to give it a try?
+
+[Getting started](./getting_started.html) is easy.
+
+[afarrill]: http://github.com/alexfarrill
+[fhwang]: http://fhwang.net/
+[mcelona]: http://github.com/mcelona