admino 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e26dee36252bba0db083897fc29ced0358ab2046
-  data.tar.gz: 0efed84c06512abd26698ea33479d7ed1a7b4746
+  metadata.gz: c15fcada38f4aa3e23bbc6b1a460565a632fb7aa
+  data.tar.gz: 2420006c1f8910d432cd5a3da44776ff8a9fc94b
 SHA512:
-  metadata.gz: f036deab369232c67daf274146a06d1173a82ec26f77d444faf2e4bf66d550adce7224a6f0fe92d486b4eba44b5b9880a8fd216dd39309d3182178d083c69d19
-  data.tar.gz: 1342bbb40cea481a7e4459f74381746a64f6d12c54809a87aad7315fd247d602c5f60ce74bb2ab1fef9aca5ec1e68c51733f62a26aeeea659255fb769478a317
+  metadata.gz: f3a34ac25cf486afeb7beb851dd6eecec93de4d7d6f47371570b0451cc533ed423c53a6a47ad5b6f9a80595533e5a0b6940a8b3da754f44e3793dc16fca330f9
+  data.tar.gz: 08c7f2fc10cb1762680895ce7cb18b257c20528a42de033d4e0c148ce8bf3360e07bc0c6d7ab08ae945af30cf3842eabf1a995f4707e3fcd3cfddfec9ac32940

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# v0.0.5
+
+* Rename Field into SearchField
+* Admino::Table::Presenter no longer presents collection by default
+
 # v0.0.4
 
 * Rename Group into FilterGroup

data/README.md

@@ -19,7 +19,7 @@ So yes, if you're starting a small, short-lived project, go ahead with them, it
 
 ### A modular approach to the problem
 
-The great thing is that you don't need to write a lot of code to get a more maintainable and modular administrative area. 
+The great thing is that you don't need to write a lot of code to get a more maintainable and modular administrative area.
 Gems like [Inherited Resources](https://github.com/josevalim/inherited_resources) and [Simple Form](https://github.com/plataformatec/simple_form), combined with [Rails 3.1+ template-inheritance](http://railscasts.com/episodes/269-template-inheritance) already give you ~90% of the time-saving features and the same super-DRY, declarative code that administrative interfaces offer, but with a far more relaxed contract.
 
 If a particular controller or view needs something different from the standard CRUD/REST treatment, you can just avoid using those gems in that specific context, and fall back to standard Rails code. No workarounds, no facepalms. It seems easy, right? It is.
@@ -38,68 +38,163 @@ And then execute:
 
 ## Admino::Query::Base
 
-A subclass of `Admino::Query::Base` represents a [Query object](http://martinfowler.com/eaaCatalog/queryObject.html), that is, an object responsible for returning a result set (ie. an `ActiveRecord::Relation`) based on business rules (ie. action params).
+`Admino::Query::Base` implements the [Query object](http://martinfowler.com/eaaCatalog/queryObject.html) pattern, that is, an object responsible for returning a result set (ie. an `ActiveRecord::Relation`) based on business rules.
 
-Given a `Task` model with the following scopes:
+Given a `Task` model, we can generate a `TasksQuery` query object subclassing `Admino::Query::Base`:
 
 ```ruby
-class Task < ActiveRecord::Base
-  scope :text_matches, ->(text) { where(...) }
+class TasksQuery < Admino::Query::Base
+end
+```
 
-  scope :completed, -> { where(completed: true) }
-  scope :pending, -> { where(completed: false) }
+Each query object gets initialized with a hash of params, and features a `#scope` method that returns the filtered/sorted result set. As you may have guessed, query objects can be great companions to index controller actions:
 
-  scope :by_due_date, ->(direction) { order(due_date: direction) }
-  scope :by_title, ->(direction) { order(title: direction) }
+```ruby
+class TasksController < ApplicationController
+  def index
+    @query = TasksQuery.new(params)
+    @tasks = @query.scope
+  end
 end
 ```
 
-The following `TasksQuery` class can be created:
+### Building the query itself
+
+You can specify how a `TaskQuery` must build a result set through a simple DSL.
+
+#### `starting_scope`
+
+The `starting_scope` method is in charge of defining the scope that will start the filtering/ordering chain:
 
 ```ruby
 class TasksQuery < Admino::Query::Base
-  starting_scope { ProjectTask.all }
+  starting_scope { Task.all }
+end
+
+Task.create(title: 'Low priority task')
+
+TaskQuery.new.scope.count # => 1
+```
+
+#### `search_field`
+
+Once you define the following field:
 
-  field :text_matches
+```ruby
+class TasksQuery < Admino::Query::Base
+  # ...
+  search_field :title_matches
+end
+```
+The `#scope` method will check the presence of the `params[:query][:title_matches]` key. If it finds it, it will augment the query with a
+named scope called `:title_matches`, expected to be found within the `Task` model, that needs to accept an argument.
+
+```ruby
+class Task < ActiveRecord::Base
+  scope :title_matches, ->(text) {
+    where('title ILIKE ?', "%#{text}%")
+  }
+end
+
+Task.create(title: 'Low priority task')
+Task.create(title: 'Fix me ASAP!!1!')
+
+TaskQuery.new.scope.count # => 2
+TaskQuery.new(query: { title_matches: 'ASAP' }).scope.count # => 1
+```
+
+#### `filter_by`
+
+```ruby
+class TasksQuery < Admino::Query::Base
+  # ...
   filter_by :status, [:completed, :pending]
-  sorting :by_due_date, :by_title
 end
 ```
 
-Every query object can declare:
+Just like a search field, with a declared filter group the `#scope` method will check the presence of a `params[:query][:status]` key. If it finds it (and its value corresponds to one of the declared scopes) it will augment the query the scope itself:
+
+```ruby
+class Task < ActiveRecord::Base
+  scope :completed, -> { where(completed: true) }
+  scope :pending,   -> { where(completed: false) }
+end
+
+Task.create(title: 'First task', completed: true)
+Task.create(title: 'Second task', completed: true)
+Task.create(title: 'Third task', completed: false)
+
+TaskQuery.new.scope.count # => 3
+TaskQuery.new(query: { status: 'completed' }).scope.count # => 2
+TaskQuery.new(query: { status: 'pending' }).scope.count # => 1
+TaskQuery.new(query: { status: 'foobar' }).scope.count # => 3
+```
+
+#### `sorting`
+
+```ruby
+class TasksQuery < Admino::Query::Base
+  # ...
+  sorting :by_due_date, :by_title
+end
+```
 
-* a **starting scope**, that is, the scope that will start the filtering/ordering chain;
-* a set of **search fields**, which represent model scopes that require an input to filter the result set;
-* a set of **filtering groups**, each of which is composed by a set of scopes that take no argument;
-* a set of **sorting scopes** that take a sigle argument (`:asc` or `:desc`) and thus are able to order the result set in both directions;
+Once you declare some sorting scopes, the query object looks for a `params[:sorting]` key. If it exists (and corresponds to one of the declared scopes), it will augment the query with the scope itself. The model named scope will be called passing an argument that represents the direction of sorting (`:asc` or `:desc`).
 
-Each query object instance gets initialized with a hash of params. The `#scope` method will then perform the chaining of the scopes based on the given params, returning the final result set:
+The direction passed to the scope will depend on the value of `params[:sort_order]`, and will default to `:asc`:
 
 ```ruby
-params = {
-  query: {
-    text_matches: 'ASAP'
-  },
-  status: 'pending',
-  sorting: 'by_title',
-  sort_order: 'desc'
-}
+class Task < ActiveRecord::Base
+  scope :by_due_date, ->(direction) { order(due_date: direction) }
+  scope :by_title, ->(direction) { order(title: direction) }
+end
+
+expired_task = Task.create(due_date: 1.year.ago)
+future_task = Task.create(due_date: 1.week.since)
 
-tasks = TasksQuery.new(params).scope
+TaskQuery.new(sorting: 'by_due_date', sort_order: 'desc').scope # => [ future_task, expired_task ]
+TaskQuery.new(sorting: 'by_due_date', sort_order: 'asc').scope  # => [ expired_task, future_task ]
+TaskQuery.new(sorting: 'by_due_date').scope                     # => [ expired_task, future_task ]
 ```
 
-As you may have guessed, query objects can be great companions to index controller actions:
+#### `ending_scope`
+
+It's very common ie. to paginate a result set. The block declared in the `ending_scope` block will be always appended to the end of the chain:
 
 ```ruby
-class ProjectTasksController < ApplicationController
-  def index
-    @query = TasksQuery.new(params)
-    @project_tasks = @query.scope
-  end
+class TasksQuery < Admino::Query::Base
+  ending_scope { |q| page(q.params[:page]) }
 end
 ```
 
-But that's not all.
+### Inspecting the query state
+
+A query object supports various methods to inspect the available search fields, filters and sortings, and their state:
+
+```ruby
+query = TaskQuery.new
+query.search_fields  # => [ #<Admino::Query::SearchField>, ... ]
+query.filter_groups  # => [ #<Admino::Query::FilterGroup>, ... ]
+
+search_field = query.search_field_by_name(:title_matches)
+
+search_field.name      # => :title_matches
+search_field.present?  # => true
+search_field.value     # => 'ASAP'
+
+filter_group = query.filter_group_by_name(:status)
+
+filter_group.name                        # => :status
+filter_group.scopes                      # => [ :completed, :pending ]
+filter_group.active_scope                # => :completed
+filter_group.is_scope_active?(:pending)  # => false
+
+sorting = query.sorting                  # => #<Admino::Query::Sorting>
+sorting.scopes                           # => [ :by_title, :by_due_date ]
+sorting.active_scope                     # => :by_due_date
+sorting.is_scope_active?(:by_title)      # => false
+sorting.ascending?                       # => true
+```
 
 ### Presenting search form and filters to the user
 
@@ -112,8 +207,8 @@ Admino also offers a [Showcase presenter](https://github.com/stefanoverna/showca
 <%# generate the search form %>
 <%= query.form do |q| %>
   <p>
-    <%= q.label :text_matches %>
-    <%= q.text_field :text_matches %>
+    <%= q.label :title_matches %>
+    <%= q.text_field :title_matches %>
   </p>
   <p>
     <%= q.submit %>
@@ -131,11 +226,25 @@ Admino also offers a [Showcase presenter](https://github.com/stefanoverna/showca
     <% end %>
   </ul>
 <% end %>
+
+<%# generate the sorting links %>
+<h6>Sort by</h6>
+<ul>
+  <% query.sorting.scopes.each do |scope| %>
+    <li>
+      <%= query.sorting.scope_link(scope) %>
+    </li>
+  <% end %>
+</ul>
 ```
 
-The great thing is that the search form gets automatically filled in with the last input the user submitted, and a CSS class `is-active` gets added to the currently active filter scopes.
+The great thing is that:
 
-If a particular filter has been clicked and is now active, it is possible to deactivate it by clicking it again.
+* the search form gets automatically filled in with the last input the user submitted
+* a `is-active` CSS class gets added to the currently active filter scopes
+* if a particular filter link has been clicked and is now active, it is possible to deactivate it by clicking on the link again
+* a `is-asc`/`is-desc` CSS class gets added to the currently active sorting scope
+* if a particular sorting scope link has been clicked and is now in ascending order, it is possible to make it descending by clicking on the link again
 
 ### Simple Form support
 
@@ -150,7 +259,7 @@ en:
   query:
     attributes:
       tasks_query:
-        text_matches: 'Contains text'
+        title_matches: 'Title contains'
     filter_groups:
       tasks_query:
         status:
@@ -158,13 +267,17 @@ en:
           scopes:
             completed: 'Completed'
             pending: 'Pending'
+    sorting_scopes:
+      task_query:
+        by_due_date: 'By due date'
+        by_title: 'By title'
 ```
 
-### Output customisation
+### Output customization
 
-The query object and its presenter implement a number of additional methods and optional arguments that allow a great amount of flexibility: please refer to the tests to see all the possibile customisations available.
+The presenter supports a number of optional arguments that allow a great amount of flexibility regarding customization of CSS classes, labels and HTML attributes. Please refer to the tests for the details.
 
-#### Overwriting the starting scope
+### Overwriting the starting scope
 
 Suppose you have to filter the tasks based on the `@current_user` work group. You can easily provide an alternative starting scope from the controller passing it as an argument to the `#scope` method:
 
@@ -175,9 +288,7 @@ def index
 end
 ```
 
-### Default sortings
-
-#### Coertions
+### Coertions
 
 Admino can perform automatic coertions from a param string input to the type needed by the model named scope:
 
@@ -204,17 +315,249 @@ If a specific coercion cannot be performed with the provided input, the scope wo
 
 Please see the [`Coercible::Coercer::String`](https://github.com/solnic/coercible/blob/master/lib/coercible/coercer/string.rb) class for details.
 
-### Ending the scope chain
+### Default sorting
 
-It's very common ie. to paginate the result set. `Admino::Query::Base` DSL makes it easy to append any scope to the end of the chain:
+If you need to setup a default sorting, you can pass some optional arguments to a `scoping` declaration:
 
 ```ruby
 class TasksQuery < Admino::Query::Base
-  ending_scope { |q| page(q.params[:page]) }
+  # ...
+  sorting :by_due_date, :by_title,
+          default_scope: :by_due_date,
+          default_direction: :desc
 end
 ```
 
 ## Admino::Table::Presenter
 
-WIP
+Admino offers a [Showcase collection presenter](https://github.com/stefanoverna/showcase) that makes it really easy to generate HTML tables from a set of records:
+
+```erb
+<%= Admino::Table::Presenter.new(@tasks, Task, self).to_html do |row, record| %>
+  <%= row.column :title %>
+  <%= row.column :completed do %>
+    <%= record.completed ? '✓' : '✗' %>
+  <% end %>
+  <%= row.column :due_date %>
+<% end %>
+```
+
+```html
+<table>
+  <thead>
+    <tr>
+      <th role='title'>Title</th>
+      <th role='completed'>Completed</th>
+      <th role='due_date'>Due date</th>
+    </tr>
+  <thead>
+  <tbody>
+    <tr id='task_1' class='is-even'>
+      <td role='title'>Call mum ASAP</td>
+      <td role='completed'>✓</td>
+      <td role='due_date'>2013-02-04</td>
+    </tr>
+    <tr id='task_2' class='is-odd'>
+      <!-- ... -->
+    </tr>
+  <tbody>
+</table>
+```
+
+### Record actions
+
+Often table rows needs to offer some kind of action associated with the record. The presenter implements the following DSL to support that:
+
+```erb
+<%= Admino::Table::Presenter.new(@tasks, Task, self).to_html do |row, record| %>
+  <%# ... %>
+  <%= row.actions do %>
+    <%= row.action :show, admin_task_path(record) %>
+    <%= row.action :edit, edit_admin_task_path(record) %>
+    <%= row.action :destroy, admin_task_path(record), method: :delete %>
+  <% end %>
+<% end %>
+```
+
+```html
+<table>
+  <thead>
+    <tr>
+      <!-- ... -->
+      <th role='actions'>Actions</th>
+    </tr>
+  <thead>
+  <tbody>
+    <tr id='task_1' class='is-even'>
+      <!-- ... -->
+      <td role='actions'>
+        <a href='/admin/tasks/1' role='show'>Show</a>
+        <a href='/admin/tasks/1/edit' role='edit'>Edit</a>
+        <a href='/admin/tasks/1' role='destroy' data-method='delete'>Destroy</a>
+      </td>
+    </tr>
+  <tbody>
+</table>
+```
+
+### Sortable columns
+
+Once a query object is passed to the presenter, columns can be associated to specific sorting scopes of the query object using the `sorting` option:
+
+```erb
+<% query = present(@query) %>
+
+<%= Admino::Table::Presenter.new(@tasks, Task, query, self).to_html do |row, record| %>
+  <%= row.column :title, sorting: :by_title %>
+  <%= row.column :due_date, sorting: :by_due_date %>
+<% end %>
+```
+
+This generates links that allow the visitor to sort the result set in ascending and descending direction:
+
+```html
+<table>
+  <thead>
+    <tr>
+      <th role='title'>
+        <a href="/admin/tasks?sorting=by_title&sort_order=desc" class='is-asc'>Title</a>
+      </th>
+      <th role='due_date'>
+        <a href="/admin/tasks?sorting=by_due_date&sort_order=asc" class='is-asc'>Due date</a>
+      </th>
+    </tr>
+  <thead>
+  <!-- ... -->
+</table>
+```
+
+### Customizing the output
+
+The `#column` and `#action` methods are very flexible, allowing youto change almost every aspect of the generated table cells:
+
+```erb
+<%= Admino::Table::Presenter.new(@tasks, Task, self).to_html(class: 'table-class') do |row, record| %>
+  <%= row.column :title, 'Custom title',
+                 class: 'custom-class', role: 'custom-role', data: { custom: 'true' },
+                 sorting: :by_title, sorting_html_options: { desc_class: 'down' }
+  %>
+  <%= row.action :show, admin_task_path(record), 'Custom label',
+                 class: 'custom-class', role: 'custom-role', data: { custom: 'true' }
+  %>
+<% end %>
+```
+
+If you need more power, you can also decide to subclass `Admino::Table::Presenter`. For each HTML element, there's a set of methods you can override to customize it's appeareance.
+Table cells are generated through two collaborator classes: `Admino::Table::HeadRow` and `Admino::Table::ResourceRow`. You can easily replace them with a subclass if you want. To grasp the idea here's an example:
+
+```ruby
+class CustomTablePresenter < Admino::Table::Presenter
+  private
+
+  def table_html_options
+    { class: 'table-class' }
+  end
+
+  def tbody_tr_html_options(resource_index)
+    { class: 'tr-class' }
+  end
+
+  def zebra_css_classes
+    %w(one two three)
+  end
+
+  def resource_row(resource, view_context)
+    ResourceRow.new(resource, view_context)
+  end
+
+  def head_row(collection_klass, query, view_context)
+    HeadRow.new(collection_klass, query, view_context)
+  end
+
+  class ResourceRow < Admino::Table::ResourceRow
+    private
+
+    def action_html_options(action_name)
+      { class: 'action-class' }
+    end
+
+    def show_action_html_options
+      { class: 'show-action-class' }
+    end
+
+    def column_html_options(attribute_name)
+      { class: 'column-class' }
+    end
+  end
+
+  class HeadRow < Admino::Table::ResourceRow
+    def column_html_options(attribute_name)
+      { class: 'column-class' }
+    end
+  end
+end
+```
+
+Please refer to the tests for all the details.
+
+### Inherited resources
+
+If the action URLs can be programmatically generated, it becomes even easier to specify the table actions:
+
+```erb
+<%= CustomTablePresenter.new(@tasks, Task, self).to_html do |row, record| %>
+  <%# ... %>
+  <%= row.actions :show, :edit, :destroy %>
+<% end %>
+```
+For instance, using [Inherited Resources](https://github.com/josevalim/inherited_resources) to generate controller actions, you can use its [helper methods](https://github.com/josevalim/inherited_resources#url-helpers) to build a custom subclass of `Admino::Table::Presenter`:
+
+```ruby
+class CustomTablePresenter < Admino::Table::Presenter
+  private
+
+  def resource_row(resource, view_context)
+    ResourceRow.new(resource, view_context)
+  end
+
+  class ResourceRow < Admino::Table::ResourceRow
+    def show_action_url
+      h.resource_url(resource)
+    end
+
+    def edit_action_url
+      h.edit_resource_url(resource)
+    end
+
+    def destroy_action_url
+      h.resource_url(resource)
+    end
+
+    def destroy_action_html_options
+      { method: :delete }
+    end
+  end
+end
+```
+
+### I18n
+
+Column titles are generated using the model [`#human_attribute_name`](http://apidock.com/rails/ActiveRecord/Base/human_attribute_name/class) method, so if you already translated the model attribute names, you're good to go. To translate actions, please refer to the following YAML file:
+
+```yaml
+en:
+  activerecord:
+    attributes:
+      task:
+        title: 'Title'
+        due_date: 'Due date'
+        completed: 'Completed?'
+  table:
+    actions:
+      task:
+        title: 'Actions'
+        show: 'Details'
+        edit: 'Edit task'
+        destroy: 'Delete'
+```
 

data/lib/admino/query.rb

@@ -1,7 +1,7 @@
 require 'admino/query/base'
 require 'admino/query/base_presenter'
 require 'admino/query/configuration'
-require 'admino/query/field'
+require 'admino/query/search_field'
 require 'admino/query/filter_group'
 require 'admino/query/filter_group_presenter'
 require 'admino/query/sorting'

data/lib/admino/query/base.rb

@@ -14,7 +14,7 @@ module Admino
 
       attr_reader :params
       attr_reader :filter_groups
-      attr_reader :fields
+      attr_reader :search_fields
       attr_reader :sorting
 
       def self.i18n_scope
@@ -26,7 +26,7 @@ module Admino
         @config = config
 
         init_filter_groups
-        init_fields
+        init_search_fields
         init_sorting
       end
 
@@ -39,11 +39,11 @@ module Admino
 
         scope_builder = starting_scope
 
-        scope_augmenters = fields + filter_groups
+        scope_augmenters = search_fields + filter_groups
         scope_augmenters << sorting if sorting
 
-        scope_augmenters.each do |field|
-          scope_builder = field.augment_scope(scope_builder)
+        scope_augmenters.each do |search_field|
+          scope_builder = search_field.augment_scope(scope_builder)
         end
 
         if config.ending_scope_callable
@@ -69,12 +69,12 @@ module Admino
         @filter_groups[name]
       end
 
-      def fields
-        @fields.values
+      def search_fields
+        @search_fields.values
       end
 
-      def field_by_name(name)
-        @fields[name]
+      def search_field_by_name(name)
+        @search_fields[name]
       end
 
       private
@@ -87,16 +87,17 @@ module Admino
         end
       end
 
-      def init_fields
-        @fields = {}
-        config.fields.each do |config|
-          @fields[config.name] = Field.new(config, params)
+      def init_search_fields
+        @search_fields = {}
+        config.search_fields.each do |config|
+          @search_fields[config.name] = SearchField.new(config, params)
         end
       end
 
       def init_sorting
         if config.sorting
-          @sorting = Sorting.new(config.sorting, params)
+          i18n_key = self.class.model_name.i18n_key
+          @sorting = Sorting.new(config.sorting, params, i18n_key)
         end
       end
     end

data/lib/admino/query/configuration.rb

@@ -1,7 +1,7 @@
 module Admino
   module Query
     class Configuration
-      class Field
+      class SearchField
         attr_reader :name
         attr_reader :coerce_to
 
@@ -47,20 +47,20 @@ module Admino
         end
       end
 
-      attr_reader :fields
+      attr_reader :search_fields
       attr_reader :filter_groups
       attr_reader :sorting
       attr_accessor :starting_scope_callable
       attr_accessor :ending_scope_callable
 
       def initialize
-        @fields = []
+        @search_fields = []
         @filter_groups = []
       end
 
-      def add_field(name, options = {})
-        Field.new(name, options).tap do |field|
-          self.fields << field
+      def add_search_field(name, options = {})
+        SearchField.new(name, options).tap do |search_field|
+          self.search_fields << search_field
         end
       end
 

data/lib/admino/query/dsl.rb

@@ -5,11 +5,11 @@ module Admino
         @config ||= Admino::Query::Configuration.new
       end
 
-      def field(name, options = {})
-        config.add_field(name, options)
+      def search_field(name, options = {})
+        config.add_search_field(name, options)
 
         define_method name do
-          field_by_name(name).value
+          search_field_by_name(name).value
         end
       end
 

data/lib/admino/query/filter_group_presenter.rb

@@ -56,7 +56,7 @@ module Admino
           scope: 'query.filter_groups',
           default: [
             :"#{i18n_key}.name",
-            i18n_key.to_s.titleize
+            i18n_key.to_s.titleize.capitalize
           ]
         )
       end

data/lib/admino/query/{field.rb → search_field.rb}

@@ -4,7 +4,7 @@ require 'active_support/core_ext/hash'
 
 module Admino
   module Query
-    class Field
+    class SearchField
       attr_reader :params
       attr_reader :config
 

data/lib/admino/query/sorting.rb

@@ -7,8 +7,9 @@ module Admino
     class Sorting
       attr_reader :params
       attr_reader :config
+      attr_reader :query_i18n_key
 
-      def initialize(config, params)
+      def initialize(config, params, query_i18n_key = nil)
         @config = config
         @params = ActiveSupport::HashWithIndifferentAccess.new(params)
       end

data/lib/admino/query/sorting_presenter.rb

@@ -3,9 +3,11 @@ require 'showcase'
 module Admino
   module Query
     class SortingPresenter < Showcase::Presenter
-      def scope_link(scope, label, *args)
+      def scope_link(scope, *args)
         options = args.extract_options!
 
+        label = args.first || scope_name(scope)
+
         desc_class = options.delete(:desc_class) { 'is-desc' }
         asc_class = options.delete(:asc_class) { 'is-asc' }
 
@@ -35,6 +37,14 @@ module Admino
 
         params
       end
+
+      def scope_name(scope)
+        I18n.t(
+          :"#{query_i18n_key}.#{scope}",
+          scope: 'query.sorting_scopes',
+          default: scope.to_s.titleize.capitalize
+        )
+      end
     end
   end
 end

data/lib/admino/table/head_row.rb

@@ -20,7 +20,10 @@ module Admino
         label = I18n.t(
           :"#{resource_klass.model_name.i18n_key}.title",
           scope: 'table.actions',
-          default: [ :title, 'Actions' ]
+          default: [
+            :title,
+            'Actions'
+          ]
         )
 
         @columns << h.content_tag(:th, label.to_s, default_options)
@@ -59,9 +62,7 @@ module Admino
       private
 
       def column_html_options(attribute_name)
-        if attribute_name
-          { role: attribute_name.to_s.gsub(/_/, '-') }
-        end
+        { role: attribute_name.to_s.gsub(/_/, '-') }
       end
     end
   end

data/lib/admino/table/presenter.rb

@@ -9,12 +9,12 @@ module Admino
       attr_reader :query
 
       def self.tag_helper(name, tag, options = {})
-        default_options_method = :"#{name}_html_options"
+        options_method = :"#{name}_html_options"
 
         define_method :"#{name}_tag" do |*args, &block|
           options = args.extract_options!
-          if respond_to?(default_options_method, true)
-            default_options = send(default_options_method, *args)
+          if respond_to?(options_method, true)
+            default_options = send(options_method, *args)
             html_options = Showcase::Helpers::HtmlOptions.new(default_options)
             html_options.merge_attrs!(options)
             options = html_options.to_h
@@ -50,11 +50,8 @@ module Admino
           end <<
           tbody_tag do
             collection.each_with_index.map do |resource, index|
-              tr_html_options = {
-                class: zebra_css_classes[index % zebra_css_classes.size],
-                id: resource.dom_id
-              }
-              tbody_tr_tag(resource, index, tr_html_options) do
+              html_options = base_tbody_tr_html_options(resource, index)
+              tbody_tr_tag(resource, index, html_options) do
                 row = resource_row(resource, view_context)
                 h.capture(row, resource, &block) if block_given?
                 row.to_html
@@ -67,7 +64,7 @@ module Admino
       private
 
       def collection
-        @collection ||= present_collection(object)
+        object
       end
 
       def head_row(collection_klass, query, view_context)
@@ -78,6 +75,18 @@ module Admino
         ResourceRow.new(resource, view_context)
       end
 
+      def base_tbody_tr_html_options(resource, index)
+        options = {
+          class: zebra_css_classes[index % zebra_css_classes.size]
+        }
+
+        if resource.respond_to?(:dom_id)
+          options[:id] = resource.dom_id
+        end
+
+        options
+      end
+
       def zebra_css_classes
         %w(is-even is-odd)
       end

data/lib/admino/table/resource_row.rb

@@ -119,15 +119,11 @@ module Admino
       private
 
       def action_html_options(action_name)
-        if action_name
-          { role: action_name.to_s.gsub(/_/, '-') }
-        end
+        { role: action_name.to_s.gsub(/_/, '-') }
       end
 
       def column_html_options(attribute_name)
-        if attribute_name
-          { role: attribute_name.to_s.gsub(/_/, '-') }
-        end
+        { role: attribute_name.to_s.gsub(/_/, '-') }
       end
     end
   end

data/lib/admino/version.rb

@@ -1,4 +1,4 @@
 module Admino
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end
 

data/spec/admino/query/base_spec.rb

@@ -19,18 +19,18 @@ module Admino
         end
       end
 
-      context 'with a declared field' do
+      context 'with a declared search_field' do
         let(:config) { Configuration.new }
-        let(:field_config) { config.add_field(:field) }
+        let(:search_field_config) { config.add_search_field(:search_field) }
 
         before do
-          field_config
+          search_field_config
         end
 
-        it 'returns a configured Field' do
-          field = query.field_by_name(:field)
-          expect(field.config).to eq field_config
-          expect(field.params).to eq params
+        it 'returns a configured SearchField' do
+          search_field = query.search_field_by_name(:search_field)
+          expect(search_field.config).to eq search_field_config
+          expect(search_field.params).to eq params
         end
       end
 
@@ -107,25 +107,25 @@ module Admino
           end
         end
 
-        context 'with a set of fields and filter_groups' do
-          let(:field_config) { config.add_field(:field) }
+        context 'with a set of search_fields and filter_groups' do
+          let(:search_field_config) { config.add_search_field(:search_field) }
           let(:filter_group_config) { config.add_filter_group(:filter_group, [:one, :two]) }
-          let(:scope_chained_with_field) { double('scope 1') }
+          let(:scope_chained_with_search_field) { double('scope 1') }
           let(:final_chain) { double('scope 2') }
 
           before do
-            field_config
+            search_field_config
             filter_group_config
             query
 
-            query.field_by_name(:field).
+            query.search_field_by_name(:search_field).
               stub(:augment_scope).
               with(starting_scope).
-              and_return(scope_chained_with_field)
+              and_return(scope_chained_with_search_field)
 
             query.filter_group_by_name(:filter_group).
               stub(:augment_scope).
-              with(scope_chained_with_field).
+              with(scope_chained_with_search_field).
               and_return(final_chain)
           end
 

data/spec/admino/query/dsl_spec.rb

@@ -6,10 +6,10 @@ module Admino
       let(:config) { TestQuery.config }
       let(:instance) { TestQuery.new }
 
-      it 'allows #field declaration' do
-        field = config.fields.last
-        expect(field.name).to eq :starting_from
-        expect(field.coerce_to).to eq :to_date
+      it 'allows #search_field declaration' do
+        search_field = config.search_fields.last
+        expect(search_field.name).to eq :starting_from
+        expect(search_field.coerce_to).to eq :to_date
       end
 
       it 'allows #filter_by declaration' do
@@ -33,13 +33,13 @@ module Admino
         expect(config.ending_scope_callable.call).to eq 'end'
       end
 
-      context 'with a field' do
-        let(:field) { double('Field', value: 'value') }
+      context 'with a search_field' do
+        let(:search_field) { double('SearchField', value: 'value') }
 
         before do
-          instance.stub(:field_by_name).
+          instance.stub(:search_field_by_name).
             with(:foo).
-            and_return(field)
+            and_return(search_field)
         end
 
         it 'it generates a getter' do

data/spec/admino/query/filter_group_presenter_spec.rb

@@ -123,7 +123,7 @@ module Admino
 
         context 'if no translation is available' do
           it 'falls back to a titleized version of the filter_group name' do
-            expect(presenter.name).to eq 'Filter Group'
+            expect(presenter.name).to eq 'Filter group'
           end
         end
       end

data/spec/admino/query/filter_group_spec.rb

@@ -37,7 +37,7 @@ module Admino
         let(:result) { filter_group.augment_scope(scope) }
         let(:scope) { ScopeMock.new('original') }
 
-        context 'if the field has a value' do
+        context 'if the search_field has a value' do
           let(:params) { { 'foo' => 'bar' } }
 
           it 'returns the original scope chained with the filter_group scope' do

data/spec/admino/query/{field_spec.rb → search_field_spec.rb}

@@ -2,36 +2,36 @@ require 'spec_helper'
 
 module Admino
   module Query
-    describe Field do
-      subject(:field) { Field.new(config, params) }
-      let(:config) { Configuration::Field.new(:foo) }
+    describe SearchField do
+      subject(:search_field) { SearchField.new(config, params) }
+      let(:config) { Configuration::SearchField.new(:foo) }
       let(:params) { {} }
 
       describe '#value' do
         context 'with a value' do
           let(:params) { { 'query' => { 'foo' => 'bar' } } }
 
-          it 'returns the param value for the field' do
-            expect(field.value).to eq 'bar'
+          it 'returns the param value for the search_field' do
+            expect(search_field.value).to eq 'bar'
           end
         end
 
         context 'else' do
           it 'returns nil' do
-            expect(field.value).to be_nil
+            expect(search_field.value).to be_nil
           end
         end
 
         context 'with coertion' do
           let(:config) {
-            Configuration::Field.new(:foo, coerce: :to_date)
+            Configuration::SearchField.new(:foo, coerce: :to_date)
           }
 
           context 'with a possible coertion' do
             let(:params) { { 'query' => { 'foo' => '2014-10-05' } } }
 
-            it 'returns the coerced param value for the field' do
-              expect(field.value).to be_a Date
+            it 'returns the coerced param value for the search_field' do
+              expect(search_field.value).to be_a Date
             end
           end
 
@@ -39,20 +39,20 @@ module Admino
             let(:params) { { 'query' => { 'foo' => '' } } }
 
             it 'returns nil' do
-              expect(field.value).to be_nil
+              expect(search_field.value).to be_nil
             end
           end
         end
       end
 
       describe '#augment_scope' do
-        let(:result) { field.augment_scope(scope) }
+        let(:result) { search_field.augment_scope(scope) }
         let(:scope) { ScopeMock.new('original') }
 
-        context 'if the field has a value' do
+        context 'if the search_field has a value' do
           let(:params) { { 'query' => { 'foo' => 'bar' } } }
 
-          it 'returns the original scope chained with the field scope' do
+          it 'returns the original scope chained with the search_field scope' do
             expect(result.chain).to eq [:foo, ['bar']]
           end
         end

data/spec/admino/query/sorting_presenter_spec.rb

@@ -5,7 +5,13 @@ module Admino
     describe SortingPresenter do
       subject(:presenter) { SortingPresenter.new(sorting, view) }
       let(:view) { RailsViewContext.new }
-      let(:sorting) { double('Sorting', default_scope: 'by_name') }
+      let(:sorting) do
+        double(
+          'Sorting',
+          default_scope: 'by_name',
+          query_i18n_key: 'query_name'
+        )
+      end
       let(:request_object) do
         double(
           'ActionDispatch::Request',
@@ -161,6 +167,27 @@ module Admino
           end
         end
       end
+
+      describe '#scope_name' do
+        context do
+          before do
+            I18n.backend.store_translations(
+              :en,
+              query: { sorting_scopes: { query_name: { by_name: 'Sort by name' } } }
+            )
+          end
+
+          it 'returns a I18n translatable name for the scope' do
+            expect(presenter.scope_name(:by_name)).to eq 'Sort by name'
+          end
+        end
+
+        context 'if no translation is available' do
+          it 'falls back to a titleized version of the scope name' do
+            expect(presenter.scope_name(:by_name)).to eq 'By name'
+          end
+        end
+      end
     end
   end
 end

data/spec/admino/query/sorting_spec.rb

@@ -73,7 +73,7 @@ module Admino
         context 'with "desc" value' do
           let(:params) { { 'sort_order' => 'desc' } }
 
-          it 'returns the param value for the field' do
+          it 'returns the param value for the search_field' do
             expect(sorting).not_to be_ascending
           end
         end
@@ -92,7 +92,7 @@ module Admino
         let(:result) { sorting.augment_scope(scope) }
         let(:scope) { ScopeMock.new('original') }
 
-        context 'if the field has a value' do
+        context 'if the search_field has a value' do
           let(:params) { { 'sorting' => 'by_title', 'sort_order' => 'desc' } }
 
           it 'returns the original scope chained with the current scope' do

data/spec/admino/table/presenter_spec.rb

@@ -11,20 +11,15 @@ module Admino
 
       let(:collection) { [ first_post, second_post ] }
       let(:first_post) { Post.new('1') }
-      let(:first_post_presenter) { double('PresentedPost', dom_id: 'post_1') }
       let(:second_post) { Post.new('2') }
-      let(:second_post_presenter) { double('PresentedPost', dom_id: 'post_2') }
 
       let(:head_row) { double('HeadRow', to_html: '<td id="thead_td"></td>'.html_safe) }
       let(:resource_row) { double('ResourceRow', to_html: '<td id="tbody_td"></td>'.html_safe) }
 
       before do
-        PostPresenter.stub(:new).with(first_post, view).and_return(first_post_presenter)
-        PostPresenter.stub(:new).with(second_post, view).and_return(second_post_presenter)
-
         HeadRow.stub(:new).with(Post, query, view).and_return(head_row)
-        ResourceRow.stub(:new).with(first_post_presenter, view).and_return(resource_row)
-        ResourceRow.stub(:new).with(second_post_presenter, view).and_return(resource_row)
+        ResourceRow.stub(:new).with(first_post, view).and_return(resource_row)
+        ResourceRow.stub(:new).with(second_post, view).and_return(resource_row)
       end
 
       describe '#.to_html' do
@@ -78,8 +73,8 @@ module Admino
           end
 
           it 'calls it once for each collection member passing the ResourceRow instance and the member itself' do
-            expect(block_call_args[1]).to eq [resource_row, first_post_presenter]
-            expect(block_call_args[2]).to eq [resource_row, second_post_presenter]
+            expect(block_call_args[1]).to eq [resource_row, first_post]
+            expect(block_call_args[2]).to eq [resource_row, second_post]
           end
         end
 

data/spec/spec_helper.rb

@@ -32,8 +32,8 @@ class ScopeMock
 end
 
 class TestQuery < Admino::Query::Base
-  field :foo
-  field :starting_from, coerce: :to_date
+  search_field :foo
+  search_field :starting_from, coerce: :to_date
 
   filter_by :bar, [:one, :two]
 
@@ -45,7 +45,7 @@ class TestQuery < Admino::Query::Base
   ending_scope { 'end' }
 end
 
-class Post < Struct.new(:key)
+class Post < Struct.new(:key, :dom_id)
   extend ActiveModel::Naming
   extend ActiveModel::Translation
 
@@ -64,12 +64,10 @@ class Post < Struct.new(:key)
   def to_key
     [key]
   end
-end
-
-require 'showcase/traits'
 
-class PostPresenter < Showcase::Presenter
-  include Showcase::Traits::Record
+  def dom_id
+    "post_#{key}"
+  end
 end
 
 require 'action_view'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: admino
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Stefano Verna
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-19 00:00:00.000000000 Z
+date: 2014-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: showcase
@@ -187,9 +187,9 @@ files:
 - lib/admino/query/base_presenter.rb
 - lib/admino/query/configuration.rb
 - lib/admino/query/dsl.rb
-- lib/admino/query/field.rb
 - lib/admino/query/filter_group.rb
 - lib/admino/query/filter_group_presenter.rb
+- lib/admino/query/search_field.rb
 - lib/admino/query/sorting.rb
 - lib/admino/query/sorting_presenter.rb
 - lib/admino/table.rb
@@ -201,9 +201,9 @@ files:
 - spec/admino/query/base_presenter_spec.rb
 - spec/admino/query/base_spec.rb
 - spec/admino/query/dsl_spec.rb
-- spec/admino/query/field_spec.rb
 - spec/admino/query/filter_group_presenter_spec.rb
 - spec/admino/query/filter_group_spec.rb
+- spec/admino/query/search_field_spec.rb
 - spec/admino/query/sorting_presenter_spec.rb
 - spec/admino/query/sorting_spec.rb
 - spec/admino/table/head_row_spec.rb
@@ -239,9 +239,9 @@ test_files:
 - spec/admino/query/base_presenter_spec.rb
 - spec/admino/query/base_spec.rb
 - spec/admino/query/dsl_spec.rb
-- spec/admino/query/field_spec.rb
 - spec/admino/query/filter_group_presenter_spec.rb
 - spec/admino/query/filter_group_spec.rb
+- spec/admino/query/search_field_spec.rb
 - spec/admino/query/sorting_presenter_spec.rb
 - spec/admino/query/sorting_spec.rb
 - spec/admino/table/head_row_spec.rb