moar 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c1b234cea1895e80c38ebe0568b780d05af5dab2bbff91aa02a43d30ac624b0
+  data.tar.gz: 44c2c5379aeb4b18fcbc4e5d5d957a48157228038567137f6316459d664fdb9c
+SHA512:
+  metadata.gz: 5e6fb50987247ca2c73fe35ac359f56e0c854d641e0e5ad8448f05381c7788196df96bcefbe49dedd538bac13cf855998870049482e36e823b047932e7a58496
+  data.tar.gz: '068724bbd447a433e309c7eedf5d7ef6c21d64cf001107815e8e2ed8765fb091d57f68b482bbc69acc48446a0b0b799959fcbb35e6678732fed59f40ee3806c5'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# moar
+
+More-style pagination for Rails.  As an example, consider the following
+story:
+
+* There are 175 posts in the database.
+* User visits the posts index page; the first 10 posts are listed.
+* User clicks a "More posts" link; the next 20 posts are appended to the
+  list (30 total) without refreshing the page.
+* User clicks the "More posts" link again; the next 30 posts are
+  appended to the list (60 total) without refreshing the page.
+* User clicks the "More posts" link again; the browser navigates to a
+  new page listing the next 60 posts.
+* User clicks a "More posts" link; the browser navigates to a new page
+  listing the final 55 posts.  No "More posts" link is rendered.
+* At any point the user can manually refresh the page, and the same set
+  of posts will be shown.  Likewise, the page can navigated away from
+  and back to, or bookmarked and returned to later, and the same set of
+  posts will be shown.  (Assuming the database remains unchanged.)
+* If JavaScript is disabled, the first and second "More posts" links
+  will simply navigate to a new page listing only the posts that would
+  have been fetched via Ajax.
+
+With *moar*, this story can be realized using the following code:
+
+```ruby
+## app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  # Step 1 (optional): set controller-specific pagination increments
+  moar_increments [10, 20, 30]
+
+  def index
+    # Step 2: apply pagination increments
+    @posts = moar(Post).order(:created_at)
+  end
+end
+```
+
+```erb
+<!-- app/views/posts/index.html.erb -->
+<h1>Posts</h1>
+<ul id="list-of-posts">
+<% @posts.each do |post| %>
+  <li><%= link_to post.title, post %></li>
+<% end %>
+</ul>
+
+<!-- Step 3: render pagination link -->
+<%= link_to_more @posts, "#list-of-posts" %>
+```
+
+A few things to note:
+
+* No special code is required to perform the fetch and render of
+  incremental paginated results via Ajax.
+* The maximum number of results per page (60, in this example) is the
+  sum of all pagination increments (10 + 20 + 30).
+* The `link_to_more` helper automatically infers the link text ("More
+  posts") from the paginated results.  This can be configured; see the
+  [Configuration](#configuration) section below.
+* The second argument of the `link_to_more` helper is a CSS selector
+  which points to the paginated results container element.  Results
+  fetched via Ajax are appended directly to that element, so the
+  selector must point to the rendered results' immediate container.  For
+  example, if the paginated results are rendered as rows in a table, the
+  selector should point to the `<tbody>` element rather than the
+  `<table>` element.
+* The `link_to_more` helper will render nothing when there are no more
+  paginated results &mdash; no `if` required.
+
+For complete usage details, see the documentation for
+[`moar_increments`](http://www.rubydoc.info/gems/moar/Moar/Controller/ClassMethods:moar_increments),
+[`moar`](http://www.rubydoc.info/gems/moar/Moar/Controller:moar), and
+[`link_to_more`](http://www.rubydoc.info/gems/moar/Moar/Helper:link_to_more).
+
+
+## Configuration
+
+The *moar* install generator will create two configuration files in your
+project directory: "config/initializers/moar.rb" and
+"config/locales/moar.en.yml".
+
+"config/initializers/moar.rb" can be edited to change the default
+pagination increments used when `moar_increments` is not called, and to
+change the query param used to indicate page number.
+
+"config/locales/moar.en.yml" can be edited to change the link text
+rendered by `link_to_more`.  Translations listed in this file are
+provided a `results_name` interpolation argument which contains the
+humanized translated pluralized downcased name of the relevant model.
+For example, if the translation string is `"Need more %{results_name}!"`
+and the paginated results consist of `CowBell` models, the rendered text
+will be "Need more cow bells!".
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "moar"
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+And finally, run the installation generator:
+
+```bash
+$ rails generate moar:install
+```
+
+
+## Contributing
+
+Run `rake test` to run the tests.
+
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT)

data/Rakefile

@@ -0,0 +1,23 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+end
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/javascripts/moar.js

@@ -0,0 +1,32 @@
+document.addEventListener("ajax:success", function(event){
+  var link = event.target;
+  var containerSelector = link.getAttribute("data-paginates");
+  if (containerSelector) {
+    var response = event.detail[0];
+
+    // insert response elements
+    var container = document.querySelector(containerSelector);
+    if (!container) {
+      console.error("Invalid pagination target: " + containerSelector);
+      return;
+    }
+    var responseContainer = response.querySelector(containerSelector);
+    if (responseContainer) {
+      while (responseContainer.hasChildNodes()) {
+        container.appendChild(responseContainer.firstChild);
+      }
+    }
+
+    // update browser URL
+    var newUrl = link.href + "&" + link.getAttribute("data-accumulation-param") + "=1";
+    history.replaceState(history.state, "", newUrl);
+
+    // update pagination link
+    var responseLink = response.querySelector("a[data-paginates]");
+    if (responseLink) {
+      link.parentNode.replaceChild(responseLink, link);
+    } else {
+      link.parentNode.removeChild(link);
+    }
+  }
+});

data/lib/generators/moar/install/install_generator.rb

@@ -0,0 +1,30 @@
+#require "rails/generators/base"
+
+module Moar
+  # @!visibility private
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.join(__dir__, "templates")
+
+      def inject_javascript
+        inside do
+          manifest = Dir["app/assets/javascripts/application.js{,.coffee}"].first
+          raise Thor::Error.new("Could not find application.js") unless manifest
+
+          before, eq = File.read(manifest).match(%r"^(//=|\s*\*=|#=) require_tree.*").to_a
+          raise Thor::Error.new("Unable to inject `require moar` into #{manifest}") unless before
+
+          inject_into_file manifest, "#{eq} require moar\n", before: before
+        end
+      end
+
+      def copy_initializer
+        template "config/initializers/moar.rb"
+      end
+
+      def copy_locales
+        copy_file "config/locales/moar.en.yml"
+      end
+    end
+  end
+end

data/lib/generators/moar/install/templates/config/initializers/moar.rb.tt

@@ -0,0 +1,12 @@
+Moar.config.tap do |config|
+  # Default pagination increments.  Controller-specific increments can
+  # also be set via the `moar_increments` controller class method.
+  config.increments = <%= Moar.config.increments.inspect %>
+
+  # Name of query param used to indicate page number.
+  config.page_param = <%= Moar.config.page_param.inspect %>
+
+  # Name of query param used to indicate when paginated results are
+  # accumulative.
+  config.accumulation_param = <%= Moar.config.accumulation_param.inspect %>
+end

data/lib/generators/moar/install/templates/config/locales/moar.en.yml

@@ -0,0 +1,12 @@
+# All translations below are provided a `results_name` interpolation
+# argument which contains the humanized translated pluralized downcased
+# name of the relevant model.  For example, if the paginated results
+# consist of GeographicLocation models, the `results_name` argument will
+# be "geographic locations".
+
+en:
+  moar:
+    # Link text rendered by `link_to_more`.
+    more: "More %{results_name}"
+    # Disabled link text shown when fetching paginated results via Ajax.
+    loading: "Loading..."

data/lib/moar.rb

@@ -0,0 +1,6 @@
+require "moar/version"
+require "moar/config"
+require "moar/context"
+require "moar/controller"
+require "moar/helper"
+require "moar/engine"

data/lib/moar/config.rb

@@ -0,0 +1,43 @@
+module Moar
+
+  class Config
+    # Pagination increments used by {Moar::Controller#moar}.  Defaults
+    # to +[12,24,24]+.  Controller-specific increments can also be set
+    # via {Moar::Controller::ClassMethods#moar_increments}.
+    #
+    # @return [Array<Integer>]
+    attr_accessor :increments
+
+    # Name of query param used to indicate page number.  Defaults to
+    # +:page+.
+    #
+    # @return [Symbol]
+    attr_accessor :page_param
+
+    # Name of query param used to indicate when paginated results are
+    # accumulative.  Defaults to +:accum+.
+    #
+    # @return [Symbol]
+    attr_accessor :accumulation_param
+
+    def initialize
+      @increments = [12, 24, 24]
+      @page_param = :page
+      @accumulation_param = :accum
+    end
+  end
+
+  # Moar global configuration object.
+  #
+  # @return [Moar::Config]
+  def self.config
+    @config ||= Moar::Config.new
+  end
+
+  # @param c [Moar::Config]
+  # @return [Moar::Config]
+  def self.config=(c)
+    @config = c
+  end
+
+end

data/lib/moar/context.rb

@@ -0,0 +1,26 @@
+module Moar
+  class Context
+
+    attr_reader :increments, :page, :accumulative, :offset, :limit
+
+    # @!visibility private
+    def initialize(increments, page, accumulative)
+      @increments = increments
+      @page = [page, 1].max
+      @accumulative = accumulative
+
+      if @page <= @increments.length
+        @limit = @increments[@page - 1]
+        @offset = @increments.take(@page - 1).sum
+        if @accumulative
+          @limit += @offset
+          @offset = 0
+        end
+      else
+        @limit = @increments.sum
+        @offset = @limit * (@page - @increments.length)
+      end
+    end
+
+  end
+end

data/lib/moar/controller.rb

@@ -0,0 +1,55 @@
+module Moar
+  module Controller
+    extend ActiveSupport::Concern
+
+    # Paginates +relation+, returning an +ActiveRecord::Relation+ with
+    # an offset and limit applied.  The offset and limit are calculated
+    # based on pagination increments (as specified by either
+    # {Moar::Controller::ClassMethods#moar_increments} or
+    # {Moar::Config#increments}), and the current page number (parsed
+    # from the request query param specified by
+    # {Moar::Config#page_param}).
+    #
+    # If the current page number is less than or equal to the number of
+    # pagination increments, the limit will be the pagination increment
+    # corresponding to the current page number.  Otherwise, the limit
+    # will be the sum of all increments.  For example, if the pagination
+    # increments are +[15,20,25]+, the offsets and limits are:
+    #
+    # * page 1: offset 0, limit 15
+    # * page 2: offset 15, limit 20
+    # * page 3: offset 35, limit 25
+    # * page 4: offset 60, limit 60
+    # * page 5: offset 120, limit 60
+    # * page 6: offset 180, limit 60
+    # * ...
+    #
+    # @param relation [ActiveRecord::Relation]
+    # @return [ActiveRecord::Relation]
+    def moar(relation)
+      @moar = Moar::Context.new(
+        _moar_increments || Moar.config.increments,
+        params[Moar.config.page_param].to_i,
+        params[Moar.config.accumulation_param].present?
+      )
+
+      relation.offset(@moar.offset).limit(@moar.limit)
+    end
+
+    included do
+      # @!visibility private
+      class_attribute :_moar_increments
+    end
+
+    module ClassMethods
+      # Sets controller-specific pagination increments to be used by
+      # {Moar::Controller#moar}.  Pagination increments set this way
+      # take precedence over {Moar::Config#increments}.
+      #
+      # @param increments [Array<Integer>]
+      def moar_increments(increments)
+        self._moar_increments = increments
+      end
+    end
+  end
+end

data/lib/moar/engine.rb

@@ -0,0 +1,14 @@
+module Moar
+  # @!visibility private
+  class Engine < ::Rails::Engine
+    initializer "moar" do |app|
+      ActiveSupport.on_load :action_controller do
+        include Moar::Controller
+      end
+
+      ActiveSupport.on_load :action_view do
+        include Moar::Helper
+      end
+    end
+  end
+end

data/lib/moar/helper.rb

@@ -0,0 +1,73 @@
+module Moar
+  module Helper
+
+    # Generates an anchor element that links to more paginated results.
+    # If JavaScript is active, and the current page number is less than
+    # the number of pagination increments (see {Moar::Config#increments}
+    # or {Moar::Controller::ClassMethods#moar_increments}), the link
+    # will use Ajax to fetch the results and inject them into the
+    # element matching the CSS selector specified by +target+.
+    # Otherwise, the link will behave normally and navigate to the next
+    # page of results.
+    #
+    # The text of the link is determined via I18n using translation key
+    # +:"moar.more"+.  A +results_name+ interpolation argument is
+    # provided containing the humanized translated pluralized downcased
+    # name of the relevant model.  For example, if the translation
+    # string is <code>"Need more %{results_name}!"</code> and +results+
+    # is an array of +CowBell+ models, the link text will be "Need more
+    # cow bells!".
+    #
+    # This helper method accepts an +html_options+ Hash, and passes it
+    # to Rails' +ActionView::Helpers::UrlHelper#link_to+.  See its
+    # documentation for information about available options.
+    #
+    # If no more results are available, this helper method will return
+    # nil so that no link is rendered.  Whether there are more results
+    # is estimated by comparing +results.length+ with the limit applied
+    # by {Moar::Controller#moar}.  This technique eliminates the need
+    # for an extra database query, but can result in a false positive
+    # (i.e. rendering a link to an empty page) when the actual last page
+    # of results is also a full page.  This is deemed an acceptable
+    # trade-off because with a large number of pages and a large total
+    # number of results per page it is an unlikely occurrence, and
+    # because an extra database query cannot entirely prevent a link to
+    # an empty page, in the case where records are deleted before the
+    # user can click through to the final page.
+    #
+    # @param results [ActiveRecord::Relation, Array<ActiveModel::Naming>]
+    # @param target [String]
+    # @param html_options [Hash]
+    # @return [String, nil]
+    # @raise [RuntimeError]
+    #   if controller action did not invoke {Moar::Controller#moar}
+    def link_to_more(results, target, html_options = {})
+      raise "#{controller.class}##{action_name} did not invoke #moar" unless defined?(@moar)
+
+      unless results.length < @moar.limit
+        params = request.query_parameters.except(Moar.config.accumulation_param.to_s)
+        params[Moar.config.page_param.to_s] = @moar.page + 1
+
+        options = { controller: controller_path, action: action_name, params: params }
+
+        i18n_options = {
+          results_name: results.first.model_name.human(
+            count: 2, default: results.first.model_name.human.pluralize(I18n.locale)
+          ).downcase,
+        }
+
+        html_options = html_options.dup
+        html_options["data-paginates"] = target
+        if @moar.page < @moar.increments.length
+          html_options["data-accumulation-param"] = Moar.config.accumulation_param.to_s
+          html_options["data-remote"] = true
+          html_options["data-type"] = "html"
+          html_options["data-disable-with"] = I18n.t(:"moar.loading", i18n_options)
+        end
+
+        link_to I18n.t(:"moar.more", i18n_options), options, html_options
+      end
+    end
+
+  end
+end

data/lib/moar/version.rb

@@ -0,0 +1,3 @@
+module Moar
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: moar
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonathan Hefner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: chromedriver-helper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: turbolinks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email:
+- jonathan.hefner@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/moar.js
+- lib/generators/moar/install/install_generator.rb
+- lib/generators/moar/install/templates/config/initializers/moar.rb.tt
+- lib/generators/moar/install/templates/config/locales/moar.en.yml
+- lib/moar.rb
+- lib/moar/config.rb
+- lib/moar/context.rb
+- lib/moar/controller.rb
+- lib/moar/engine.rb
+- lib/moar/helper.rb
+- lib/moar/version.rb
+homepage: https://github.com/jonathanhefner/moar
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: More-style pagination for Rails
+test_files: []