Skip to content
Generate the right number of columns for a grid layout for a page with variable numbers of columns
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
.gitignore
Gemfile
LICENSE.txt
README.md
Rakefile
generate-column-widths.gemspec
gitignore

README.md

GenerateColumnWidths

This gem allows you to calculate the number of columns to span in a css grid when your site may have a variable number of columns of data to display.

It allows you to generate the number of columns you need, and to have them automatically be the correct widths to fit your page, based on the data you have to display. You don't need to know a priori how many columns your data will produce, and you don't need to fill your html with a bunch of centering divs to try to make it look ok.

It also allows you to accommodate a situation when the columns being generated need to fit alongside columns that are already on the page.

You use the generated variable to create columns automatically in your views. For example, in this snippet, which generates a 4 column layout for screen sizes small and above (a Bootstrap concept):

<% @your_collection.each do |item| %>
  <div class="col-sm-3">
  ...
<% end %>

The variable generated by the gem replaces the "3" in the col-sm-3. As your view iterates through the items in the collection and renders them in the view, it will generate only the number of columns you need for the data you have. The columns will automatically be the right width to accommodate your data. If you have fewer than expected, your columns won't all be clumped together to one side - and you can accomplish that without having to add a bunch of centering divs to wrap the content.

This doc is largely implementation oriented. If you need a bit more of a plain English description of what it does, check out my blog post: lianeallen.com/home/2014/09/module-to-auto-generate-column-widths-in-a-grid-system/

Installation

Add this line to your application's Gemfile:

gem 'generate-column-widths'

And then execute:

$ bundle

Or install it yourself as:

$ gem install generate-column-widths

Usage

Once it's installed, it's easy to use:

###1. Include the Module in the Model that Needs It

In the model whose views will need auto-generated column widths:

include GenerateColumnWidths

Example

Since I'm using this for views that contain lists of project categories, I put it in my Category model, category.rb:

class Category < ActiveRecord::Base
  include GenerateColumnWidths
  ...
end

###2. Determine How Many Columns are in Your Data From the controller where the view is generated, calculate the number of columns you need.

####Example: In my case, I needed to get a count of the number of meta-category headings I'd have in my view by finding out how many of those meta-categories contained any associated projects:

@category_types = # code to find which meta categories contain projects
@category_types_count = category_types.count

###3. Call the Generator In your controller, call the generator.

Simply call the generate_widths method with your new variable. Call it via the model into which you placed it. In my case, that's Category.

This is the code in my categories_controller.

@column_width = Category.new.generate_widths(
  @category_types_count
)

I use @column_width in the Bootstrap div in my categories index view (see below).

###5. Use it in Your View Replace the number in the div that defines the column span in your view. Here's what it looks like in a Bootstrap column div for small views and higher:

<% @category_types.each do |type| %>
  <div class="col-sm-<%= @column_width %>">
  ...
<% end %>

Be sure to put the div inside the iterator, or you're going to end up with just one narrow column.

###You Can Change the Defaults The generator has several defaults built in. It assumes you want a maximum of 4 columns in your view, using a 12 column Bootstrap3 grid. You can change the defaults by specifying a different value for any or all of the optional variables.

You need only include those options you want to change. Any option you don't include will automatically use the default.

####Option: total_grid_columns The number of columns in your grid system. Bootstrap3 uses 12, others may use 9 or some other number.

Default:

total_grid_columns: 12

####Option: existing_columns The number of columns already in the view, that will share a row with your new columns. In the vast majority of cases, you won't need to change this, but it's here in case you do.

Default:

existing_columns: 0

####Option: min_column_span The minimum span you want to use. This is one of those counter-intuitive things in Bootstrap. It's not the number of columns you want, it's:

How many of the 12 columns in the grid do you want this column to span?

So, you divide the total number of columns in the grid by this number to get the number of columns you're trying to span.

The result is how many columns you'll end up with in your row, before Bootstrap wraps to a new line to display the next set of columns.

The default is to span 3 columns, at a minimum, which means (12 / 3 = 4) you'll get a maximum of 4 columns in the view.

Default:

min_column_span: 3

Unless you're fond of seeing divide by zero errors, don't set this to zero.

####Option: max_column_span This is the maximum number of columns you want to span. It's the opposite of the above. The default is 12, so divide 12/12, and you get ... 1. That's the minimum number of columns that will be shown.

Default:

max_column_span: 12

Unless you're fond of seeing divide by zero errors, don't set this to zero.

####Example 1 On one page, I need to accomodate an extra column of data that's generated elsewhere. So my categories columns will appear in the same row as an extra column. To deal with this, I can call:

@column_width = Category.new.generate_widths(
  @category_types_count,
  existing_columns: 1
)

####Example 2 Alternatively, if I were using a 9 grid, instead of a 12 grid, I could specify:

@column_width = Category.new.generate_widths(
  @category_types_count,
  total_grid_columns: 9,
  max_column_span: 9
)

In this case, the default min_column_span (3) would be divided into 9, giving me a maximum of 3 columns in my view before Bootstrap wraps to a new line for additional columns.

Contributing

  1. Fork it ( https://github.com/[my-github-username]/generate-column-widths/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
You can’t perform that action at this time.