tenon 1.1.8 → 2.0.0

data/README.rdoc

@@ -1,5 +1,7 @@
 = Tenon
 
+Tenon 2.0 runs on Rails 5 and you should probably use at least Ruby 2.3.0. Stay fresh.
+
 == License
 
 This project uses the MIT-LICENSE.  Do whatever you want with it as long as you
@@ -10,58 +12,58 @@ depends.
 
 In your Gemfile
 
-    gem 'tenon'
+  gem 'tenon'
 
 and then bundle install.
 
 in config/application.rb:
 
-    require 'active_record/railtie'
+  require 'active_record/railtie'
 
 
 in config/routes.rb:
 
-    mount Tenon::Engine => '/tenon'
+  mount Tenon::Engine => '/tenon'
 
 
 Run command:
 
-    $ rake tenon:install:migrations
-    $ rake db:migrate
+  $ rake tenon:install:migrations
+  $ rake db:migrate
 
 
 You will need to have a database set up at this point.  Currently Tenon requires that you use postgres.
 
 Running rake db:migrate probably threw up a devise error.  Create config/initializers/devise.rb and paste:
 
-    Devise.setup do |config|
-      ## paste the secret key line from the error output ##
-    end
+  Devise.setup do |config|
+    ## paste the secret key line from the error output ##
+  end
 
 
 Run that command again:
 
-    $ rake db:migrate
+  $ rake db:migrate
 
 
 Install the Tenon helpers in app/controllers/application_controller.rb:
 
-    helper Tenon::Engine.helpers
+  helper Tenon::Engine.helpers
 
 Install the necessary files to run and customize Tenon (this is now required):
 
-    $ rails generate tenon:install
+  $ rails generate tenon:install
 
 To run seed data (such as creating an admin user) from Tenon, open console and run:
 
-    ENV['PASSWORD'] = 'password' # or something at least 8 chars long
-    Tenon::Engine.load_seed
+  ENV['PASSWORD'] = 'password' # or something at least 8 chars long
+  Tenon::Engine.load_seed
 
 Restart your app and navigate to /tenon
 
 If you want to be able to use rspec, which would be good, you will also need to run:
 
-    bundle exec rails generate rspec:install
+  bundle exec rails generate rspec:install
 
 ==== Note about CKEditor
 
@@ -69,12 +71,69 @@ Currently options for serving CKEditor via the asset pipeline are limited.  For
 
 == Scaffolding
 
-TODO: Write this section
+Tenon comes with a powerful scaffold generator that makes it easy for you to prototype new resources.  The scaffold generator sits on top of Rails' built in resource generators and creates everything you need for a working CRUD interface in Tenon.
+
+Let's create an imaginary +Post+ resource as an example:
+
+    $ rails generate tenon:scaffold Post title:string excerpt:text
+
+This task will create the following files:
+
+    app/controllers/tenon/posts_controller.rb
+    app/decorators/post_decorator.rb
+    app/policies/post_policy.rb
+    app/serializers/post_serializer.rb
+    app/models/post.rb
+    app/views/tenon/posts/index.html.haml
+    app/views/tenon/posts/new.html.haml
+    app/views/tenon/posts/edit.html.haml
+    app/views/tenon/posts/_form.html.haml
+    db/migrate/<timestamp>_create_posts.rb
+
+It will also add the necessary routes to <tt>config/routes.rb</tt>.  If you navigate to <tt>/tenon/posts</tt> within your app you will see that you have a fully functioning section with the ability to index, search, add, edit, and delete posts.
+
+On top of the typical Rails generator column types like +string+, +text+, or +integer+, Tenon adds a few new options.
+
++asset+:: Use this to create an asset field that integrates with Tenon's asset library.
++content+:: Use this to create a TenonContent field.
++date+:: Automatically links up a date picker widget in your form.
++datetime+:: Automatically links up a date and time picker widget in your form.
+
+There are also a handful of column names that you can define to trigger special behaviour in the generator:
+
++title+:: This field is required for your scaffolded resource to work out of the box.  You'll need to override part of the +ResourceIndex+ React component tree (more on this below) if you want to use a different field name.
++publish_at+:: Adds special publishing fields to your form and adds a scope called +published+ to your model.
++list_order+:: Includes <tt>Tenon::Reorderable</tt> in your model, adds a +reorder+ action to your controller, adds a default scope to your model to sort by +list_order+, and makes the items in your index view drag and drop sortable.
++seo_title+, +seo_keywords+, +seo_description+:: Adds a special SEO fields panel to your form with explanatory text.  Useful for public-facing websites.
+
+With these features in mind, let's regenerate our +Post+ resource with all of our special features.
+
+  $ rails generate tenon:scaffold Post title:string excerpt:text content:content banner_photo:asset written_on:date publish_at:datetime list_order:integer seo_title:string seo_keywords:string seo_description:text
+
+Out of the box this will give us a working +Post+ model with functional views.  Typically you'll want to reorganize the fields found in <tt>app/views/tenon/posts/_form.html.haml</tt>, but otherwise your work is done!
 
 == Item Revisions/History
 
 TODO: Write this section
 
+== Access Control / ACL
+
+Tenon uses Pundit for ACL, see https://github.com/elabs/pundit for documentation.
+
+Have your policies inherit from <tt>Tenon::ApplicationPolicy</tt> to get default authorization.  Override <tt>app/policies/tenon/application_policy.rb</tt> if you want to override the default authorization scheme.  Write custom policies as per Pundit standards.
+
+Any controller that inherits from <tt>Tenon::ResourcesController</tt> will have ACL applied on all CRUD methods.  ACL is enforced on all actions so ensure that you +authorize+ any time you add a new action or override an existing one.  Policy scoping is enforced on the index action, so ensure that if you override the +filterer+ method that you are using Pundit's +policy_scope+ method.  For example:
+
+  module Tenon
+    class PostsController < ResourcesController
+      private
+
+      def filterer
+        PostFilterer.new(policy_scope(Post), params)
+      end
+    end
+  end
+
 == Internationalization
 
 Although Tenon is currently anglocentric it supports the inclusion of additional
@@ -84,76 +143,716 @@ To add internationalized fields, follow these steps:
 
 1. Add our 'translates' gem to your Gemfile and then bundle install
 
-    gem 'translates', git: 'https://github.com/factore/translates.git'
+  gem 'translates', git: 'https://github.com/factore/translates.git'
 
 2. Tell Tenon which languages you want to support in config/initializers/tenon.rb (You don't need to add English, Tenon always assumes its in use.)
 
-    config.languages = {
-      "French" => :fr,
-      "German" => :de
-      # etc.
-    }
+  config.languages = {
+    "French" => :fr,
+    "German" => :de
+    # etc.
+  }
 
 3. Add a language yml file in config/locales/ for each language defined above, or rails will have a fit, eg 'config/locales/fr.yml'
 
 4. Create or update config/i18n_fields.yml to tell Tenon which fields you would like to have internationalized.
 
-    tables:
-      cars:
-        - title
-        - description
-
-      events:
-        - title
-        - location
-        - description
-        
-    If you want to add internationalization to the default Tenon models you should make your i18n_fields.yml look like this:
-
-    tables:
-      tenon/events:
-        - title
-        - location
-
-      tenon/pages:
-        - title
-        - seo_title
-        - seo_keywords
-        - seo_description
-
-      tenon/posts:
-        - title
-        - excerpt
-        - seo_title
-        - seo_keywords
-        - seo_description
-        
+  tables:
+    cars:
+    - title
+    - description
+
+    events:
+    - title
+    - location
+    - description
+
+  If you want to add internationalization to the default Tenon models you should make your i18n_fields.yml look like this:
+
+  tables:
+    tenon/events:
+    - title
+    - location
+
+    tenon/pages:
+    - title
+    - seo_title
+    - seo_keywords
+    - seo_description
+
+    tenon/posts:
+    - title
+    - excerpt
+    - seo_title
+    - seo_keywords
+    - seo_description
+
 5. Generate and run the internationalization migration.  The generator will only try to create columns that don't already exist, so you can use this generator multiple times throughout the development of your application.
 
-    rails generate tenon:i18n_migrations
-    rake db:migrate
+  rails generate tenon:i18n_migrations
+  rake db:migrate
 
 6. Update your models to make sure your attributes are translated
 
-    class MyModel < ActiveRecord::Base
-        include Translates
-        # plain old rails attributes
-        translates :title
-        # tenon_content
-        tenon_content :description, i18n: true
-    end
-    
+  class MyModel < ApplicationRecord
+    include Translates
+    # plain old rails attributes
+    translates :title
+    # tenon_content
+    tenon_content :description, i18n: true
+  end
+
 7. Update your tenon views to add the language navigation helper, where needed:
-    # app/views/tenon/cars/_form.html.haml
-    - content_for :sidebar do
-        .sidebar
-            .content
-                ...
-            = i18n_language_nav(:cars)
-    ...
-    
+  # app/views/tenon/cars/_form.html.haml
+  - content_for :sidebar do
+    .sidebar
+      .content
+        ...
+      = i18n_language_nav(:cars)
+  ...
+
 8. While there, make sure you are using 'autosaving_form_for' instead of 'form_for' to create your forms.  By doing this, Tenon will automatically update the labels when the different languages are selected.
 
 9. Make sure your routes are configured according to your needs and the I18n.locale is being set somehow (see Rails documentation for more info: http://guides.rubyonrails.org/i18n.html)
 
 Once you've done this and restarted your app you will see a language selection nav in the sidebar of each Tenon form that has internationalized fields.  On the front end, attributes on your Tenon models will be translated correctly, based on I18n.locale.
+
+== Using and Customizing the ResourceIndex React App
+
+One of the biggest changes in Tenon 2.0 is the replacement of the index view for each resource with a common ResourceIndex ReactJS/Redux app.  Listing, paginating, filtering, sorting, deleting, editing, and all other tasks typically done on the index route of a resource are managed through this mounted React app.
+
+Rather than scaffolding new code for every resource, code is shared for all resources.  If you find yourself needing to customize the index view, individual components of the React app can easily be replaced with custom components.  This allows for a high level of customization without creating a lot of repetitive code.
+
+=== The simplest thing that could possibly work
+
+The bare minimum code to get a fully functioning resource index view is as follows.  (For an imagined +Post+ resource this code would be the entirety of <tt>app/views/tenon/posts/index.html.haml</tt>)
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path
+
+This code will instantiate the +ResourceIndexRoot+ React component, and pass it the following required props:
+
++title+:: The pluralized title of the resource.
++breadcrumb_links+:: An array of Ruby hashes in the format of <tt>[{ title: 'A Title', path: '/path/to/somewhere' }]</tt>.  Use the built-in +breadcrumb_links+ Rails helper to automatically generate this for your current resource, or supply your own.
++recordsPath+:: The path where the JSON dump of your resource can be found.  Typically just the +index+ path with the +format+ of <tt>'json'</tt> specified.
++newPath+:: The path to the +new+ action for your resource.
+
+=== Customizing the app
+
+At some point you will need to make changes to how the ResourceIndex app looks and behaves for a specific resource.  Rather than copying the entire app and changing the relevant portions, the app can be instantiated with specific child-components swapped out for your own custom components.
+
+In order to do this first we need to understand the composition of the app.  The app is broken up into several smaller child-components, each of which can be swapped out when the app is instantiated in your +index+ view.  The component tree is as follows:
+
+  - ResourceIndexRoot
+    - App
+      - QuickSearchToolbar
+        - QuickSearchInput
+        - ActionButtons
+          - FilterToggle
+          - SortOrder
+            - SortOrderItem
+      - QuickSearchOverlay
+        - (Same Children as QuickSearchToolbar)
+      - Filtering
+        - FilterDrawer
+        - FilterOverlay
+      - List
+        - Record
+          - RecordTitle
+          - RecordActions
+          - RecordExpandedContent
+        - LoadMoreButton
+
+
+A common task when creating index views is changing the way the title of each individual record is displayed.  Let's change our imagined +Post+ resource to display not only the post's title, but also its publish date.
+
+The first step to replacing a child-component is changing the instantiation call to the +ResourceIndex+ component and passing in the name of our new component.  In this case, we want to replace +RecordTitle+ with a custom component, which we'll call +PostsRecordTitle+.  Pass it in as a prop like so:
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path,
+      childComponentNames: { RecordTitle: 'PostsRecordTitle' }
+
+This prop tells the top-level component to render +PostsRecordTitle+ instead of +DefaultRecordTitle+ in the component tree.
+
+The next step is to create our +PostsRecordTitle+ component.  Start by copying the code of the +DefaultRecordTitle+ component, found at <tt>app/assets/javascripts/tenon/components/resource-index/components/default/record-title.es6</tt>.  The code will look something like this.
+
+    Tenon.RI.DefaultRecordTitle = ({ record }) => {
+      return (
+        <p className="record__title">{record.title}</p>
+      );
+    };
+
+Copy this code and create the new component at <tt>app/assets/javascripts/tenon/components/posts-record-title.es6</tt>.  In our case we simply want to change the name of the component, and add a second line with the record's +publish_at+ method.  Our finished component looks like this:
+
+  Tenon.RI.PostsRecordTitle = ({ record }) => {
+    return (
+      <div>
+        <p className="record__title">
+          {record.title}
+        </p>
+
+        <p className="record__title--smallest">
+          Published on {record.publish_at}
+        </p>
+      </div>
+    );
+  };
+
+Upon saving this component our imagined +Post+ resource's index page will now display a customized title including the publish date/time of the post.
+
+=== Triggering actions and making changes
+
+It's not enough to just display custom information in the index view, often we need to give users the ability to make changes or interact with data as well.  You can trigger actions in your custom components that allow you to change the state of the app and update the database.  The two most common actions you will want to take are making updates to an individual record, and changing how your records are filtered and sorted.  These two actions are known as +updateRecord+ and +updateQuery+ and are passed down as methods on the +handlers+ prop available in any custom component.
+
+<tt>updateRecord(event, record, changeObject)</tt>:: Updates the record in question and sends the changes to the server.
+
+                                                     * +record+ - The record object.  At minimum it must have +id+, +update_path+, and +resource_type+ methods.  (Any resource generated with a Tenon scaffold will have these.)
+
+                                                     * +changeObject+ - An object describing the changes to the object, eg. <tt>{ title: 'My New Title', featured: true }</tt>
+
+<tt>updateQuery(event, changeObject [, appendRecords])</tt>:: Changes the query sent to the server when fetching records, re-fetches records with new query, and updates query string in address bar.
+
+                                                              * +changeObject+ - An object describing the changes to the query, eg. <tt>{ q: 'my search', page: 1 }</tt>.  (You should always include <tt>page: 1</tt> in your query unless you are appending records.)
+
+                                                              * +appendRecords+ - Boolean.  True: Append new records to the bottom of the list.  False: Clear record list before getting new records.  Default: false.
+
+Let's create a simple button on our imagined posts index that allows us to toggle whether a given post is featured or not.
+
+The first thing we need to do is update our call to the +ResourceIndex+ component in <tt>index.html.haml</tt> to tell it that we're going to be passing in our custom set of +RecordActions+.
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path,
+      childComponentNames: {  RecordTitle: 'PostsRecordTitle',
+                              RecordActions: 'PostsRecordActions' }
+
+Next, we'll want to make a copy of the +DefaultRecordActions+ component found at <tt>app/assets/javascripts/components/resource-index/components/default/record-actions.es6</tt>.  The default component looks like this:
+
+  Tenon.RI.DefaultRecordActions = (props) => {
+    const editPath = props.record.edit_path;
+    const onDelete = props.onDelete;
+
+    return (
+      <div className="record__actions">
+        <a
+          className="record__action-icon"
+          href={editPath}
+          title="Edit">
+          <i className="material-icon">edit</i>
+        </a>
+
+        <a
+          className="record__action-icon"
+          href="#!"
+          onClick={onDelete}
+          title="Delete">
+          <i className="material-icon">delete</i>
+        </a>
+      </div>
+    );
+  };
+
+We'll make our new component at <tt>app/assets/javascripts/tenon/components/posts-record-actions.es6</tt> and add a new icon.
+
+  Tenon.RI.PostsRecordActions = (props) => {
+    const editPath = props.record.edit_path;
+    const onDelete = props.onDelete;
+
+    return (
+      <div className="record__actions">
+        <!-- copied edit and delete buttons -->
+
+        <a
+          className="record__action-icon"
+          href="#!"
+          onClick={<we need something here>}
+          title="Toggle Featured">
+          <i className="material-icon">star_border</i>
+        </a>
+      </div>
+    );
+  };
+
+Next we need to tap into the +onClick+ action of the link to toggle the featured state of the record.
+
+  <a
+    className="record__action-icon"
+    href="#!"
+    onClick={(e) => {
+      props.handlers.updateRecord(e, props.record, !props.record.featured)
+    }}
+    title="Toggle Featured">
+    <i className="material-icon">star_border</i>
+  </a>
+
+This is a little bit lengthy, so let's extract some constants up above.
+
+  Tenon.RI.PostsRecordActions = (props) => {
+    const editPath = props.record.edit_path;
+    const { onDelete, record } = props;
+    const { updateRecord } = props.handlers;
+
+    return (
+      <div className="record__actions">
+        <!-- copied edit and delete buttons -->
+
+        <a
+          className="record__action-icon"
+          href="#!"
+          onClick={(e) => {
+            updateRecord(e, record, { featured: !record.featured });
+          }}
+          title="Toggle Featured">
+          <i className="material-icon">star_border</i>
+        </a>
+      </div>
+    );
+  };
+
+Finally, let's add some feedback to show the user that something happened.  We'll have the component display an empty star for regular posts, and a full star for featured ones.
+
+  <a
+    className="record__action-icon"
+    href="#!"
+    onClick={(e) => {
+      updateRecord(e, record, { featured: !record.featured });
+    }}
+    title="Toggle Featured">
+    <i className="material-icon">
+      {record.featured ? 'star' : 'star_border'}
+    </i>
+  </a>
+
+Your users can now click on the star to toggle the post's featured state.
+
+Read on through the next section to understand how <tt>updateQuery()</tt> and the query object interacts with the server to filter and return records.
+
+=== Adding and editing using a modal window
+
+Very basic resources, such as lists of categories, may be easier to manage if their add and edit actions are presented in a modal window rather than on a new page.  This can be easily accomplished with the addition of two options and one custom component.
+
+First, change the call to +ResourceIndexRoot+ to include the modal options, as well as the name of the custom form component you'll be providing.  In this case we'll use an imagined +PostCategory+ list as our example:
+
+  = react_component 'ResourceIndexRoot',
+    title: 'Categories',
+    breadcrumbs: breadcrumb_links,
+    recordsPath: post_categories_path(format: 'json'),
+    newPath: new_post_category_path,
+    addWithModal: true,
+    editWithModal: true,
+    childComponentNames: { ModalFields: 'PostCategoryFields' }
+
+Note the addition of +addWithModal+, +editWithModal+, and the name of the +ModalFields+ child component.
+
+Next we need to create the +PostCategoryFields+ child component.  This file can be created at <tt>app/assets/javascripts/tenon/components/post-category-fields.es6</tt> and should look something like this:
+
+    Tenon.RI.PostCategoryFields = (props) => {
+      const { currentRecord, currentRecordErrors } = props.data;
+      const { onChange } = props;
+
+      return (
+        <div>
+          <TextField
+            name="title"
+            value={currentRecord.title}
+            onChange={onChange}
+            errors={currentRecordErrors.title}
+            label="Title" />
+          <button type="submit" className="btn">Save</button>
+        </div>
+      );
+    };
+
+The important things to note about this are as follows:
+
+* It uses the handy +TextField+ component to generate standard Tenon <tt>input-block</tt> HTML. Other available components include +SelectField+, +CheckBoxField+, and +DatepickerField+.  You can use standard HTML and supply the <tt>input-block</tt> tags yourself if you need something custom.
+* It pulls +currentRecord+, +currentRecordErrors+, and +onChange+ out of the supplied props.  These will always be available.
+* It passes +name+, +value+, +onChange+, +errors+, and +label+ along to the +TextField+ component.
+* +name+, +value+, and +errors+ are consistent with the field that's being presented (in this case they all reference +title+.)
+* The save button is added, but other modal markup is handled automatically further up the chain.
+
+By supplying these options and this custom component, our +PostCategory+ resource can now be managed completely from the index page without having to visit a secondary form page.
+
+== Using the StandaloneList component
+
+Occasionally you may want to render a list of records inside an existing view, for example if you wanted to embed a list of records inside/alongside a form.  You can accomplish this by rendering the +StandaloneList+ component.  It functions identically to the +ResourceIndexRoot+ component.
+
+This is especially useful for lists that have in-place editing (eg. the feature toggle we just added to posts).  You can replace any of the child components in the chain, just as with the +ResourceIndexRoot+ component.
+
+  = react_component 'StandaloneList',
+    recordsPath: posts_path(format: 'json')
+    childComponentNames: {  RecordTitle: 'PostsRecordTitle',
+                            RecordActions: 'PostsRecordActions' }
+
+== Searching and Filtering Records
+
+=== Setting up your Rails Controllers and Filterers
+
+Often you will need to provide various different ways to filter records that are returned
+in your controllers' +index+ action.  The standard <tt>Tenon::ResourcesController#index</tt>
+action provides a hook to allow the returned records to pass through a Filterer.
+Filterers receive, at minimum, a scope (eg. an <tt>ActiveRecord::Relation</tt>) and a set of params.
+They can then apply their own internal logic to filter the passed scope.  For example, consider the
+following call to an imagined <tt>PostFilterer</tt>:
+
+  filterer = PostFilterer.new(Post.all, { q: 'Tenon' })
+  @posts = filterer.filter
+
+The <tt>PostFilterer</tt> could use its internal logic to, for
+example, return only posts that are called "Tenon":
+
+  class PostFilterer < Tenon::BaseFilterer
+    def filter
+      if params[:q].present?
+        @scope = scope.where(title: params[:q])
+      end
+      super # Returns the scope
+    end
+  end
+
+or it could use its internal logic to return only posts that are
+in a +Category+ called "Tenon":
+
+  class PostFilterer < Tenon::BaseFilterer
+    def filter
+      if params[:q].present?
+        @scope = scope.includes(:category)
+        @scope = scope.where(category: { title: params[:q] })
+      end
+      super # Returns scope
+    end
+  end
+
+By default, records in the +index+ action of any controller that inherits from
+<tt>Tenon::ResourcesController</tt> will be filtered by
+<tt>Tenon::GenericFilterer</tt>.  While <tt>Tenon::BaseFilterer</tt> takes
+a scope and a params object as its initialization arguments,
+<tt>Tenon::GenericFilterer</tt> also takes as a third argument a list of
+fields to run a basic text search on.  The <tt>#quick_search_fields</tt> method
+on any controller is used to set these fields, like in the following example
+of a basic controller for posts:
+
+  class PostsController < Tenon::ResourcesController
+    private
+
+    def quick_search_fields
+      ['posts.title', 'posts.excerpt', 'posts.content']
+    end
+  end
+
+As it's a convention for all resources in Tenon to respond to a <tt>#title</tt>
+method the default behaviour is to filter on this field.
+
+In order to provide searching and filtering capabilities beyond what the
++GenericFilterer+ provides, simply create a a new filterer in the
+<tt>app/filterers</tt> directory.  It is usually best to have this custom
+filterer inherit from <tt>Tenon::GenericFilterer</tt> in order to keep the quick search
+functionality, but a filterer can also inherit from <tt>Tenon::BaseFilterer</tt>.
+
+After creating the new filterer, it can be inserted into the controller
+by defining the <tt>#filterer</tt> method.
+
+  class PostsController < Tenon::ResourcesController
+    private
+
+    def quick_search_fields
+      ['posts.title', 'posts.excerpt', 'posts.content']
+    end
+
+    def filterer
+      PostFilterer.new(Post.all, params, quick_search_fields)
+    end
+  end
+
+(Note that in reality you would want to perform an ACL check on the scope you pass into the filterer, replacing <tt>Post.all</tt> with <tt>policy_scope(Post)</tt>.)
+
+Here is an example of what an imagined +PostFilterer+ that inherits from
+<tt>Tenon::GenericFilterer</tt> with some date-filtering logic might look like:
+
+  class PostFilterer < Tenon::GenericFilterer
+    def filter
+      @scope = filter_start_date
+      @scope = filter_end_date
+      super
+    end
+
+    private
+
+    def filter_start_date
+      return scope unless params[:start_date].present?
+      scope.where('publish_at >= ?', params[:start_date])
+    end
+
+    def filter_end_date
+      return scope unless params[:end_date].present?
+      scope.where('publish_at <= ?', params[:end_date])
+    end
+  end
+
+The +filter_start_date+ and +filter_end_date+ methods allow custom filtering
+of the collection that's passed in, while the call to +super+ on the
+<tt>#filter</tt> method also allows for the +quick_search_fields+ to be
+searched.
+
+Because many filtering tasks are similar, filterers that inherit from <tt>Tenon::BaseFilterer</tt> (and thus <tt>Tenon::GenericFilterer</tt>) have access to a few convenience methods for easier filtering.  These methods are:
+
+<tt>eq(field, value)</tt>:: Used to check if +field+ is equal to +value+
+<tt>ilike(field, value)</tt>:: Used to check if +field+ <em>ILIKE matches</em> +value+
+<tt>gt(field, value)</tt>:: Used to check if +field+ is greater than +value+
+<tt>lt(field, value)</tt>:: Used to check if +field+ is less than +value+
+<tt>gte(field, value)</tt>:: Used to check if +field+ is greater than or equal to +value+
+<tt>lte(field, value)</tt>:: Used to check if +field+ is less than or equal to +value+
+<tt>order(field, direction)</tt>:: Used to order your scope by +field+ in +direction+, eg. <tt>order('books.title', 'asc')</tt>.  Define a method called +allowed_order_fields+ on your Filterer and return an array of allowed fields, eg. <tt>['books.title', 'created_at', 'authors.title']</tt>.  Direction must be <tt>'asc'</tt> or <tt>'desc'</tt>.
+<tt>reorder(field, direction)</tt>:: Same as +order+ but uses <tt>#reorder</tt> instead of <tt>#order</tt> on the scope.
+
+These methods will always simply return the current scope if +value+ is not +.present?+, so there's no need to check for the presence of a param.
+
+Here is an example of the imagined +PostFilterer+ rewritten using these convenience methods:
+
+  class PostFilterer < Tenon::GenericFilterer #:nodoc:
+    def filter
+      @scope = gte('posts.publish_at', params[:start_date])
+      @scope = lte('posts.publish_at', params[:end_date])
+      super
+    end
+  end
+
+A custom filterer is just a plain old Ruby object and can use any kind of
+internal logic to filter a collection.  The only requirement is that the
+<tt>#filter</tt> method returns a chainable <tt>ActiveRecord::Relation</tt>.
+
+=== Creating the Filtering UI for your Resource
+
+The ResourceIndex component's toolbar contains a search input that automatically sends its value as <tt>params[:q]</tt> when a user types in it.  This hook into <tt>Tenon::GenericFilterer</tt> on the Rails end and provide basic filtering of a resource.  For many resources this all the filtering that's required, and no customization is necessary.
+
+However, it's often necessary to build more advanced filtering features, as demonstrated in the above example using the PostFilterer to filter posts on params like <tt>:start_date</tt> and <tt>:end_date</tt>.  In order to expose these options to the end user, we need to create a React component and inject it into our ResourceIndex component.  These custom components are called <b>Filter Drawers</b>.
+
+Here is an example of what an imagined +PostsFilterDrawer+ component, living at <tt>/app/assets/javascripts/tenon/components/posts-filter-drawer.es6</tt>, might look like.
+
+    Tenon.RI.PostsFilterDrawer = (props) => {
+      const query = props.data.query;
+      const onChange = props.onChange;
+
+      return (
+        <div className="panel--block">
+          <TextField
+            label="Keywords"
+            name="q"
+            value={query.q}
+            onChange={onChange} />
+
+          <DatepickerField
+            label="Start Date"
+            name="start_date"
+            value={query.start_date}
+            onChange={onChange} />
+
+          <DatepickerField
+            label="End"
+            name="end_date"
+            value={query.end_date}
+            onChange={onChange} />
+        </div>
+      );
+    };
+
+This stateless React component (https://toddmotto.com/stateless-react-components/) is passed the entire state tree from the top-level +ResourceIndex+ component, but only uses the <tt>data.query</tt> object (responsible for which params are passed to the server when fetching records) and an +onChange+ function passed down from the parent component.  Also, notice that the component is set within the <tt>Tenon.RI</tt> object.  All custom components intended to be passed into the ResourceIndex component tree must be set this way.
+
+The component uses JSX needed to build three simple form controls: a text field for a general query, a datepicker for the start date, and a datepicker for the end date.  Each input is passed four props:
+
+label:: The visible label for the field
+name:: The name of the +param+ being changed (eg. <tt>name="start_date"</tt> -> <tt>params[:start_date]</tt>)
+value:: The initial value of input, almost always <tt>query.<param_name></tt>
+onChange:: The +onChange+ prop passed in from the parent component.
+
+As long as +name+, +value+, and +onChange+ are present you can use any HTML elements and form inputs you like to build your Filter Drawer.  There are a handful of simple pre-built components available as conveniences for building form elements, including:
+
+* +TextField+
+* +DatepickerField+
+* +SelectField+
+* +CheckBoxField+
+
+To inject this component into the top-level +ResourceIndex+ component for your particular resource its name needs to be passed in as part of the +childComponentNames+ prop in your index view.  Here is an example of what it might look like in an imagined posts index, located at <tt>app/views/tenon/posts/index.html.haml</tt>:
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path,
+      childComponentNames: { FilterDrawer: 'PostsFilterDrawer' }
+
+When the top-level +ResourceIndex+ is rendered with a +FilterDrawer+, the Filter Drawer will be available to your users, and you can provide as much or as little advanced filtering as you like.
+
+=== Creating the Ordering UI for your Resource
+
+(This section glosses over the process of adding and editing components to the ResourceIndex app.  Make sure you read <b>Using and Customizing the ResourceIndex React App</b> before reading this.)
+
+While it's certainly possible to add the UI for ordering the returned records into the +FilterDrawer+ component, the recommend approach is to  separate it from filtering and instead use a button with a dropdown menu in the toolbar.  To add this button, we're going to supply our own custom +ActionButtons+ child-component to the +ResourceIndex+ app.
+
+The first step is initializing the +ResourceIndex+ app with the name of our custom +ActionButtons+ component.  We'll continue working on our imagined +Post+ resource, and so this component will be called +PostsActionButtons+.
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path,
+      childComponentNames: {  FilterDrawer: 'PostsFilterDrawer',
+                              ActionButtons: 'PostsActionButtons' }
+
+
+Next, copy the +DefaultActionButtons+ component, found at <tt>app/assets/javascripts/tenon/components/resource-index/components/default/action-buttons.es6</tt>.  The default component looks like this:
+
+  Tenon.RI.DefaultActionButtons = (props) => {
+    const { FilterDrawerToggle } = props.childComponents;
+
+    return (
+      <div className="toolbar__actions toolbar__actions--right">
+        <FilterDrawerToggle {...props} />
+      </div>
+    );
+  };
+
+We'll create our new component at <tt>app/assets/javascripts/tenon/components/posts-action-buttons.es6</tt>.  We want to be able to order our posts from oldest to newest, and from newest to oldest, so let's paste the code from the +DefaultActionButtons+ component and add some markup that creates a dropdown menu with these options.
+
+  Tenon.RI.PostsActionButtons = (props) => {
+    const { FilterDrawerToggle } = props.childComponents;
+
+    return (
+      <div className="toolbar__actions toolbar__actions--right">
+        <FilterDrawerToggle {...props} />
+
+        <div className="toolbar__action">
+          <a
+            className="action-icon dropdown-button"
+            href="#!"
+            title="Sort Order">
+            <i className="material-icons">tune</i>
+          </a>
+
+          <ul className="dropdown">
+            <li className="dropdown__item dropdown__item--label">Order By</li>
+            <li className="dropdown__item">
+              <a
+                href="#!"
+                className="dropdown__action action-icon">
+                  <span>Oldest to Newest</span>
+              </a>
+            </li>
+            <li className="dropdown__item">
+              <a href="#!" className="dropdown__action action-icon">
+                <span>Newest to Oldest</span>
+              </a>
+            </li>
+          </ul>
+        </div>
+
+
+      </div>
+    );
+  };
+
+Next we need to set up the links to update the query.  There is an +orderBy+ handler that takes +field+ and +direction+ as arguments available in our props.  This handler is just a convenient wrapper around the +updateQuery+ wrapper.  We'll extract it and then call it in the +onClick+ prop of our links.
+
+  Tenon.RI.PostsActionButtons = (props) => {
+    const { FilterDrawerToggle } = props.childComponents;
+    const { orderBy } = props.handlers;
+
+    return (
+      <div className="toolbar__actions toolbar__actions--right">
+        <FilterDrawerToggle {...props} />
+
+        <div className="toolbar__action">
+          <a
+            className="action-icon dropdown-button"
+            href="#!"
+            title="Sort Order">
+            <i className="material-icons">sort</i>
+          </a>
+
+          <ul className="dropdown">
+            <li className="dropdown__item dropdown__item--label">Order By</li>
+            <li className="dropdown__item">
+              <a
+                href="#!"
+                className="dropdown__action"
+                onClick={(e) => orderBy(e, 'publish_at', 'asc')}>
+                  <span>Oldest to Newest</span>
+              </a>
+            </li>
+            <li className="dropdown__item">
+              <a
+                href="#!"
+                className="dropdown__action"
+                onClick={(e) => orderBy(e, 'publish_at', 'desc')}>
+                  <span>Newest to Oldest</span>
+              </a>
+            </li>
+          </ul>
+        </div>
+      </div>
+    );
+  };
+
+Finally, let's give some feedback to the user so they can see which item is currently selected.  We'll pull the +order_direction+ out from the +query+ object and then use it to set the +active+ class on the correct <tt><li></tt>.
+
+  Tenon.RI.PostsActionButtons = (props) => {
+    const { FilterDrawerToggle } = props.childComponents;
+    const { orderBy } = props.handlers;
+    const { order_direction } = props.data.query;
+
+    return (
+      <div className="toolbar__actions toolbar__actions--right">
+        <FilterDrawerToggle {...props} />
+
+        <div className="toolbar__action">
+          <a
+            className="action-icon dropdown-button"
+            href="#!"
+            title="Sort Order">
+            <i className="material-icons">sort</i>
+          </a>
+
+          <ul className="dropdown">
+            <li className="dropdown__item dropdown__item--label">Order By:</li>
+            <li
+              className={order_direction === 'asc' ? 'dropdown__item active' : 'dropdown__item'}>
+              <a
+                href="#!"
+                className="dropdown__action action-icon"
+                onClick={(e) => orderBy(e, 'publish_at', 'asc')}>
+                  <span>Oldest to Newest</span>
+              </a>
+            </li>
+            <li
+              className={order_direction === 'desc' ? 'active dropdown__item' : 'dropdown__item'}>
+              <a
+                href="#!"
+                className="dropdown__action action-icon"
+                onClick={(e) => orderBy(e, 'publish_at', 'desc')}>
+                  <span>Newest to Oldest</span>
+              </a>
+            </li>
+          </ul>
+        </div>
+      </div>
+    );
+  };
+
+If you think all this seems a bit effortful for a very common requirement, you're not wrong.  This same behaviour can be replicated by going back to the +DefaultActionButtons+ component and passing an +orderOptions+ array as a prop to the +ResourceIndex+, like this:
+
+  = react_component 'ResourceIndexRoot',
+      title: 'Posts',
+      breadcrumbs: breadcrumb_links,
+      recordsPath: posts_path(format: 'json'),
+      newPath: new_post_path,
+      childComponentNames: {  FilterDrawer: 'PostsFilterDrawer' }
+      orderOptions: [ { title: 'Oldest to Newest', order: 'publish_at:asc' },
+                      { title: 'Newest to Oldest', order: 'publish_at:desc'} ]