RubyGems - admin_assistant - Versions diffs - 2.0.0 → 2.0.1 - Mend

admin_assistant 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (418) hide show

data/website/quick_start.markdown CHANGED Viewed

@@ -3,25 +3,25 @@ layout: default
 title:  Quick start
 ---
-*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 [tutorial](./tutorial.html).*
+<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/tutorial.html">tutorial</a>.
+</div>
-1) First, install the plugin from Github.
+1) Add the gem to your Gemfile, and install it with `bundle install`.
-    ./script/plugin install git://github.com/fhwang/admin_assistant.git
+    gem 'admin_assistant'
-2) If you don't have the popular will\_paginate gem, you'll need that too. See [http://wiki.github.com/mislav/will_paginate/installation](http://wiki.github.com/mislav/will_paginate/installation) for more info.
-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.
+2) 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 jquery, if you're not including it already.
     <html>
       <head>
-        <%= javascript_include_tag("prototype", "effects", "controls") %>
+        <%= javascript_include_tag("jquery-1.6.2.min") %>
         <%= admin_assistant_includes %>
       </head>
       ...
     </html>
-4) Setup an admin controller by attaching it to a model and using the admin layout:
+3) Setup an admin controller by attaching it to a model and using the admin layout:
     class Admin::BlogPostsController < ApplicationController
       layout 'admin'
@@ -31,7 +31,7 @@ title:  Quick start
 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](./img/blog_posts-index.png)
+![index](/admin_assistant/img/blog_posts-index.png)
 Depending on the model you're using, you might notice a few things:
@@ -40,5 +40,5 @@ Depending on the model you're using, you might notice a few things:
 * 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/).
+For more, check out the [API reference](/admin_assistant/api/).

data/website/screenshots.markdown CHANGED Viewed

@@ -3,25 +3,25 @@ layout: default
 title:  Screenshots
 ---
-<a href="./img/screen1.png" rel="lightbox[screens]" class="thumb" title="With a few lines of code, admin_assistant gives you a lot of default functionality for one model, including an index view with pagination and sorting, search, creating, and editing."><img src="./img/screen1-thumb.png"></a>
+<a href="/admin_assistant/img/screen1.png" rel="lightbox[screens]" class="thumb" title="With a few lines of code, admin_assistant gives you a lot of default functionality for one model, including an index view with pagination and sorting, search, creating, and editing."><img src="/admin_assistant/img/screen1-thumb.png"></a>
-<a href="./img/screen2.png" rel="lightbox[screens]" class="thumb" title="Sorting is built-in, and done in the URL for easy bookmarking, etc."><img src="./img/screen2-thumb.png"></a>
+<a href="/admin_assistant/img/screen2.png" rel="lightbox[screens]" class="thumb" title="Sorting is built-in, and done in the URL for easy bookmarking, etc."><img src="/admin_assistant/img/screen2-thumb.png"></a>
-<a href="./img/screen3.png" rel="lightbox[screens]" class="thumb" title="If there are many results, the pagination section will include a form for jumping to a specific page quickly."><img src="./img/screen3-thumb.png"></a>
+<a href="/admin_assistant/img/screen3.png" rel="lightbox[screens]" class="thumb" title="If there are many results, the pagination section will include a form for jumping to a specific page quickly."><img src="/admin_assistant/img/screen3-thumb.png"></a>
-<a href="./img/screen4.png" rel="lightbox[screens]" class="thumb" title="By default, any boolean field on the model can be toggled in the index view with an Ajax link."><img src="./img/screen4-thumb.png"></a>
+<a href="/admin_assistant/img/screen4.png" rel="lightbox[screens]" class="thumb" title="By default, any boolean field on the model can be toggled in the index view with an Ajax link."><img src="/admin_assistant/img/screen4-thumb.png"></a>
-<a href="./img/screen5.png" rel="lightbox[screens]" class="thumb" title="New and edit pages render default widgets for each column on the model. Datetime fields, for example, each get a &quot;Clear&quot; javascript link by default."><img src="./img/screen5-thumb.png"></a>
+<a href="/admin_assistant/img/screen5.png" rel="lightbox[screens]" class="thumb" title="New and edit pages render default widgets for each column on the model. Datetime fields, for example, each get a &quot;Clear&quot; javascript link by default."><img src="/admin_assistant/img/screen5-thumb.png"></a>
-<a href="./img/screen6.png" rel="lightbox[screens]" class="thumb" title="If the model has a belongs-to association, and there are too many records on that associated table to be usable in a dropdown, admin_assistant renders an autocompleter instead."><img src="./img/screen6-thumb.png"></a>
+<a href="/admin_assistant/img/screen6.png" rel="lightbox[screens]" class="thumb" title="If the model has a belongs-to association, and there are too many records on that associated table to be usable in a dropdown, admin_assistant renders an autocompleter instead."><img src="/admin_assistant/img/screen6-thumb.png"></a>
-<a href="./img/screen7.png" rel="lightbox[screens]" class="thumb" title="On the form, individual column inputs on the form can be overridden with custom logic. On this admin controller for the Product model, the column &quot;price&quot; is being rendered with the ERB template _price_input.html.erb. The submitted parameters are then pre-processed with a protected controller method called price_from_form."><img src="./img/screen7-thumb.png"></a>
+<a href="/admin_assistant/img/screen7.png" rel="lightbox[screens]" class="thumb" title="On the form, individual column inputs on the form can be overridden with custom logic. On this admin controller for the Product model, the column &quot;price&quot; is being rendered with the ERB template _price_input.html.erb. The submitted parameters are then pre-processed with a protected controller method called price_from_form."><img src="/admin_assistant/img/screen7-thumb.png"></a>
-<a href="./img/screen8.png" rel="lightbox[screens]" class="thumb" title="A customized search form can give you searching by specific columns. The user can choose to match all or any of the conditions. Also, numerical fields include comparators by default, so, for example, you can search for all products costing greater than $100."><img src="./img/screen8-thumb.png"></a>
+<a href="/admin_assistant/img/screen8.png" rel="lightbox[screens]" class="thumb" title="A customized search form can give you searching by specific columns. The user can choose to match all or any of the conditions. Also, numerical fields include comparators by default, so, for example, you can search for all products costing greater than $100."><img src="/admin_assistant/img/screen8-thumb.png"></a>
-<a href="./img/screen9.png" rel="lightbox[screens]" class="thumb" title="The same autocompleting for belongs-to associations is also available in the search form. In this example, the user is searching for blog posts by author."><img src="./img/screen9-thumb.png"></a>
+<a href="/admin_assistant/img/screen9.png" rel="lightbox[screens]" class="thumb" title="The same autocompleting for belongs-to associations is also available in the search form. In this example, the user is searching for blog posts by author."><img src="/admin_assistant/img/screen9-thumb.png"></a>
-<a href="./img/screen10.png" rel="lightbox[screens]" class="thumb" title="There is an optional theme that mimics ActiveScaffold, which may come in handy if you're in the process of transitioning away from ActiveScaffold. admin_assistant does not conflict with ActiveScaffold; you can use the two in different controllers of the same Rails app."><img src="./img/screen10-thumb.png"></a>
+<a href="/admin_assistant/img/screen10.png" rel="lightbox[screens]" class="thumb" title="There is an optional theme that mimics ActiveScaffold, which may come in handy if you're in the process of transitioning away from ActiveScaffold. admin_assistant does not conflict with ActiveScaffold; you can use the two in different controllers of the same Rails app."><img src="/admin_assistant/img/screen10-thumb.png"></a>
-<a href="./img/screen11.png" rel="lightbox[screens]" class="thumb" title="admin_assistant handles images out of the box through either Paperclip or FileColumn."><img src="./img/screen11-thumb.png"></a>
+<a href="/admin_assistant/img/screen11.png" rel="lightbox[screens]" class="thumb" title="admin_assistant handles images out of the box through Paperclip."><img src="/admin_assistant/img/screen11-thumb.png"></a>

data/website/tutorial.markdown CHANGED Viewed

@@ -1,35 +1,44 @@
 ---
 layout: default
-title:  Quick start
+title:  Tutorial
 ---
-*This document assumes you are a beginning Rails user; if you are very familiar with Rails you might want to check out our [quick start](./quick_start.html).*
+<div class="note">
+This document assumes you are a beginning Rails user; if you are familiar with Rails you might want to check out our <a href="/admin_assistant/quick_start.html">quick start</a>.
+</div>
-1) First, install the plugin from Github.
+1) Add the gem to `Gemfile` in the root of your Rails project.
-    ./script/plugin install git://github.com/fhwang/admin_assistant.git
+    gem 'admin_assistant'
+2) Install the gem locally.
+    $ bundle install
+3) admin\_assistant uses jQuery. You may already have jQuery installed for your project, but if not, you can get it like so:
-2) If you don't have the popular will\_paginate gem, you'll need that too. See [http://wiki.github.com/mislav/will_paginate/installation](http://wiki.github.com/mislav/will_paginate/installation) for more info.
+    $ curl http://code.jquery.com/jquery-1.6.2.min.js > \
+        public/javascripts/jquery-1.6.2.min.js
-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:
+4) 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") %>
+        <%= javascript_include_tag("jquery-1.6.2.min") %>
         <%= admin_assistant_includes %>
       </head>
       <body>
-        <%=yield %>
+        <%= 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.
+5) 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:
+6) 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'
@@ -37,11 +46,11 @@ If you've already created an admin layout, you should add the javascript referen
       admin_assistant_for BlogPost
     end
-6) If you were already running your Rails app with `./script/server` etc, you should restart it.
+7) 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:
+8) Visit `/admin/blog_posts` in your browser and you'll see something like this:
-![index](./img/blog_posts-index.png)
+![index](/admin_assistant/img/blog_posts-index.png)
 You can now search, paginate, create, and edit blog posts.
@@ -52,5 +61,5 @@ Depending on the model you're using, you might notice a few things:
 * 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/).
+For more, check out the [API reference](/admin_assistant/api/).

data/website/v1/api/core.markdown ADDED Viewed

@@ -0,0 +1,108 @@
+---
+layout: default
+title:  "Version 1 API: Core"
+subtitle: Core
+subnav:   api1
+---
+### Includes
+admin\_assistant comes with its own Javascript and CSS. Call `admin_assistant_includes` in your admin layout to use them:
+    <html>
+      <head>
+        <%= admin_assistant_includes %>
+      </head>
+      ...
+    </html>
+You also have the option of making admin\_assistant look very similar to activescaffold CSS-wise, which might come in handy if you're in the process of transition from one to the other:
+    <%= admin_assistant_includes :theme => 'activescaffold' %>
+Submissions of other themes are welcome.
+### Configuring the core builder object
+<a name="builder_actions"> </a>
+#### actions
+admin\_assistant uses the old-fashioned seven Rails actions: index, show, new/create, edit/update, and destroy. By default, you get all of them except destroy. To add destroy, you can simply append it to the `actions` method:
+    admin_assistant_for User do |aa|
+      aa.actions << :destroy
+    end
+You can also send `actions` a list of actions and it will only allow those:
+    # I only want to create or index images, not edit, show or destroy
+    admin_assistant_for Image do |aa|
+      aa.actions :create, :index
+    end
+### model\_class\_name
+Use this to override what the model is named in the interface, in links like "New blog post" or "50 blog posts found". The string passed in should be lowercase.
+    aa.model_class_name = 'post'
+### Column config options
+#### boolean\_labels
+    aa[:textile].boolean_labels = %w(Yes No)
+For a boolean fields, will change how the values get displayed, instead of simply "true" and "false".
+#### label
+    aa[:user].label = 'Author'
+Overrides the default label for that column in index, search, and form views.
+#### polymorphic\_types
+    aa[:bookmarkable].polymorphic_types = [BlogPost, Comment, Product, User]
+If a column is a polymorphic association, admin\_assistant will offer specific widgets for searching and editing this column. With `polymorphic_types` you can tell it what possible types the association can be set to.
+#### strftime\_format
+    aa[:published_at].strftime_format = "%b %d, %Y %H:%M:%S"
+If the column is a date or time, this will use the given strftime format for displaying the column in index and shows views.
+### Helper methods
+#### \[column\]\_value
+Determines what value is passed to form inputs, index views, etc, for the individual column. This is most useful for a virtual column.
+### Model methods
+#### name\_for\_admin\_assistant
+When dealing with associations, admin\_assistant needs a convenient way to display a given record. By default, it will look for a method with the name `name`, `title`, `login`, or `username`. If you'd like to provide custom functionality across all admin\_assistant controllers, define the method `name_for_admin_assistant` on the model.
+For example, let's say you have a ProductCategory class with a field `category_name`. With the code below, any time a product category is referred to through an association, admin\_assistant will display the `category_name`, in index views, form selects, etc.
+    class ProductCategory < ActiveRecord::Base
+      def name_for_admin_assistant
+        self.category_name
+      end
+    end
+#### sort\_value\_for\_admin\_assistant
+When showing associated records, admin\_assistant will sort by the method `sort_value_for_admin_assistant` if it's defined on the model. This comes in handy if you want to specify sorting on form drop-downs for belongs-to associations.
+    class Appointment < ActiveRecord::Base
+      def sort_value_for_admin_assistant
+        self.time
+      end
+    end

data/website/v1/api/destroy.markdown ADDED Viewed

@@ -0,0 +1,27 @@
+---
+layout: default
+title:  "Version 1 API: Destroy"
+subtitle: Destroy
+subnav:   api1
+---
+Note that the `destroy` action is turned off by default. To turn it on, use the core [actions](/admin_assistant/v1/api/core.html#builder_actions) method.
+By default, `destroy` simply retrieves the model instance, and calls `ActiveRecord::Base#destroy`. If you'd like to define your own custom deletion semantics, you can set a block that will be called instead of the model's built-in `destroy` method:
+    admin_assistant_for Product do |a|
+      a.actions << :destroy
+      a.destroy do |product|
+        product.update_attribute :deleted, true
+        product.notify_admins_of_deletion
+      end
+    end
+You may also find plugins such as [as\_paranoid] or [acts\_as\_paranoid] useful here. If you're using a plugin such as that, which changes the behavior of `ActiveRecord::Base#destroy`, it means that you will probably not need to customize admin\_assistant in this way.
+[acts_as_paranoid]: http://ar-paranoid.rubyforge.org/
+[as_paranoid]: http://github.com/semanticart/is_paranoid/tree/master

data/website/v1/api/form.markdown ADDED Viewed

@@ -0,0 +1,293 @@
+---
+layout: default
+title:  "Version 1 API: Form"
+subtitle: Form
+subnav:   api1
+---
+![form](/admin_assistant/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