Yuki Nishijima's Blog

5 Major Changes in Kaminari 1.0.0

14 January ’17


Today, I'm pleased to announce that kaminari has it's first major release! Because 1.0.0 has a number of major changes, I would like to summarize the main changes.

Support for Old Versions of Ruby and Rails Have Been Dropped

In Kaminari 1.0.0, we decided to discontinue support for the following versions:

  • Ruby 1.9.3
  • JRuby 1.7
  • Rails 3.2 and 4.0

If you are using one or more of these versions, make sure to upgrade them first before upgrading to Kaminari 1.0.0.

Breaking up Gems

The most significant change in Kaminari 1.0.0 is the gem has now been split up into separate gems, e.g., kaminari-activerecord. If you are using kaminari with Rails and ActiveRecord, which is the most common use for kaminari, in 1.0.0 Kaminari can be used the same way as before so long as...

gem 'kaminari'

...is present in the Gemfile, with no change being necessary. But if you are using Kaminari with another framework like Sinatra or a different ORM like Mongoid (or both together), then you’d need to add the individual gems for them. For example, if you are using Rails and Mongoid, then you should have:

gem 'kaminari-core'
gem 'kaminari-mongoid'
gem 'kaminari-actionview'

But if you are using Sinatra and ActiveRecord, then you should have:

gem 'kaminari-core'
gem 'kaminari-activerecord'
gem 'kaminari-sinatra'

(kaminari-core can be omitted, since it is referred to by the other gems.)

The gems that are currently supported can be found at https://github.com/kaminari. Also, if you are maintaining a gem for a specific DB which implements an interface to Kaminari and would like to move the repo to our organization, we would be more than happy to do so. That way everyone will be able to keep up-to-date when we make a breaking API change in the kaminari-core repo.

Experimental Pagination without Count

In order to display the links needed for pagination, Kaminari issues a count query to the db. However, if there is an enormous amount of data in the DB, then calculating the count could take a great deal of time (depending on the RDBMS), creating a major performance bottleneck.

To work around this issue, starting 1.0.0 the #without_count method has been added. This method obtains records for the number of elements displayed on the page — plus one. Then it figures out whether or not we need a next page if additional elements still exist. The downside to this is, it becomes theoretically impossible to display the total number of pages, although the #link_to_next_page method and the #link_to_previous_page methods can be used without a count query.

@users = User.page(params[:page]).without_count

In 1.0.0, this has been introduced as an experimental feature, so a #without_count call needs to be invoked explicitly. If no major problems are reported, then in the future we plan to make this the default. Please try this out if you are having difficulty with count queries.

The -e haml/slim Options for rails g kaminari:views Have Been Deprecated

Up until now haml, slim, and erb templates have all been organized in the repository, and it has been possible to generate haml or slim templates for your app using the -e option. Yet, while it’s possible to change erb to haml or slim with a single command like html2haml, the cost of maintaining the haml and slim templates in the repository is extremely high. Regardless of the situation with haml, none of the maintainers understand slim syntax, so if a pull request is filed to kaminari_themes, maintainers have been unable to judge what is correct. What is more, if there is a change in haml or slim syntax, then there is no way to manage templates for multiple versions — or it is a great deal of work. In addition, in the remote chance that a new template engine is implemented, it would probably be necessary to add new template files for all themes.

We decided to deal with this situation by deprecating the -e haml/slim option and having users make changes locally when they want to use haml or slim in the future. In other words, we are treating the erb templates as something like a single source of truth. In addition, our policy, as of 1.0.0, will be to only have erb when new templates are added, and only accept bugfix patches to the existing haml/slim templates.

params_on_first_page Config Has Been Added

Up until now, the link to the first page shown by the #paginate method ignored all params. However, there has been a problem that if, for example, a feature such as filtering is implemented using params, and if you return to the first page, then all of the filters would vanish. To fix this, the params_on_first_page config was added.

# Typically this file is located at `config/initializers/kaminari_config.rb`
Kaminari.configure do |config|
  config.params_on_first_page = true
end

If params_on_first_page is set to true, all query parameters will also be present in the link to the first page just like in other links.

Give Us Your Feedback

There are many other changes not mentioned here. To find out more, please check the CHANGELOG. If you run across anything unusual while using Kaminari or discover anything like a bug, please be sure to file an issue on GitHub issues.

"Did you mean?" Experience in Ruby

21 October ’14

Everytime I misspelled a method name or a class name and got an error but didn't realize the typo, I kept saying,

"Weird, nothing looks weird..."

Sometimes I wasted hours and hours just because there is one character difference. I hate it.

This is why I created did_you_mean gem. With it, whenever you get NoMethodError or NameError, it'll automatically look for what you really wanted to call and tell it to you.

gem 'did_you_mean', group: [:development, :test]

So what will happen when you misspell ActiveSupport's Hash#with_indifferent_access? Here is what it looks like:

hash.with_inddiferent_access
# => NoMethodError: undefined method `with_inddiferent_access' for {}:Hash
#
#     Did you mean? #with_indifferent_access
#

Look! Now you can just copy and paste what was suggested and it'll just work.

did_you_mean gem automagically puts method suggestions into the error message. This means you'll have the "Did you mean?" experience almost everywhere. Here is a good example of a suggestion from my real development:

Example of a method suggestion in real development

You can find more examples on the project page on GitHub: yuki24/did_you_mean

Start using did_you_mean gem and stop worrying about misspelling. Ruby will just read your mind.

Kaminari + Bootstrap = <3

17 November ’12

As you can notice on an everyday basis, twitter bootstrap is being used in many services today. If you've developed a web application with Ruby on Rails and needed to implement pagination, you've probably used kaminari or will_paginate as well.

Even so, applying twitter bootstrap to kaminari's default template, while not technically difficult, requires several tedious operations. There are also lots of blog posts explaining different methods and gems that make the process easier. However, the problem is that bootstrap development moves at a bleeding-edge pace, so those posts quickly become obsolete. These changes also create a steep hurdle for beginners.

In order to eliminate these complexities, kaminari started supporting twitter bootstrap several weeks ago. This integration will make the process much easier. All that's required is just issuing a one-line command. No need to use other gems.

Background

About a month ago at the Asakusa.rb meetup, the kaminari author, Matsuda-san, told me that there had been as many as eight pull requests for support for twitter bootstrap on kaminari themes' Github Issues. a few weeks later, Hibariya-san and I tested all of the requests and merged @jweslley's pull reuqest.

Installation

When using twitter bootstrap with Ruby on Rails, installing via gem is the standard approach. The obvious choices are twitter-bootstrap-rails and bootstrap-sass -- both will immediately adapt to changes to bootstrap proper, so there should be no issue with choosing one over the other. For the purposes of this tutorial, I'll use twitter-bootstrap-rails because it offers some convenient commands that let you easily change existing templates to the bootstrap format.

First, make sure your Gemfile contains the following lines.

gem 'kaminari'
gem 'twitter-bootstrap-rails', :group => :assets 

If bootstrap is not installed, use the following command to install it.

bundle install
rails g bootstrap:install
rails g bootstrap:layout application fluid

Once installed, you can issue the following command to generate a bootstrap-compatible template.

rails g kaminari:views bootstrap

That's it! You should reboot rails server and make sure everything is working as expected.

Demo

I build a simple demo application running on heroku: https://kaminari-bootstrap-demo.herokuapp.com/

The source code is on GitHub..

We were able to merge @jweslley's request without any changes to his code, letting us create clean layouts with this update. Even so, bootstrap is updated on an almost daily basis, so this template will probably be deprecated before long. If your layout breaks or you notice your templates need updating, please send those changes on kaminari_themes on github. If you run into other non-layout issues, try posting a question on stackoverflow -- you'll probably be able to get a response right away, so it's worth trying as a method of first resort.