• Stars
    star
    130
  • Rank 277,575 (Top 6 %)
  • Language SCSS
  • License
    MIT License
  • Created over 8 years ago
  • Updated almost 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Custom responsive grids in Sass that work in older browsers.

Column Setter

Column Setter is a Sass tool that lets you easily set up a custom responsive grid for your website and build a float- or flexbox-based layout that aligns to it. It uses one simple function and a small handful of optional mixins to generate CSS widths based on your settings. And for the most part, it leaves the structure of your HTML and CSS entirely up to you.

v2.0 Updates

  • Unit values are now supported in the grid property variables ($mar, $col, $gut, $pad) in _column-settings.scss.
  • All grid properties can now be customized per breakpoint in the $breakpoints map in _column-settings.scss.
  • colspan() can now natively generate negative width values (-) and add a gutter to width values (+g).
  • A wider range of errors now can be detected, including missing or incorrectly formatted settings.

Table of Contents

Setup

Begin by saving _column-settings.scss and _column-setter.scss in the same directory as your main Sass file.

Grid proportions

In _column-settings.scss, customize your grid’s proportions by editing the values of the four variables at the top of the file ($mar, $col, $gut, $pad). These establish the spatial relationship between the grid’s properties. For an entirely fluid grid, use all unitless numbers (e.g. “$mar: 4; $col: 3;”). These will cause colspan(), Column Setter’s central function, to generate % values. Otherwise, units are allowed (e.g. “$gut: 1em;”), as is a mix of unitless and units (e.g. “$col: 3; $gut: 1em;”). Mixed units will cause colspan() to generate calc() values. When using units, keep these caveats in mind:

  • Giving $col a unit value is allowed but not recommended.
  • If $mar and $gut both have unit values, giving $col any unitless value will make columns fill the available space, as if they were 1fr in CSS Grid. Likewise, if $mar and $col both have unit values, giving $gut any unitless value will make gutters fill the available space.
  • Making $mar or $pad unitless will have no effect unless $col and/or $gut are also unitless.

However you decide to define their values, don’t delete any of these variables. For any you don’t need to use, just assign a value of 0. The Column Setter demo (demo.html) creates a completely fluid grid by using all unitless values:

$mar: 4; // Margin width
$col: 4; // Column width
$gut: 2; // Gutter width
$pad: 1; // Padding width

Breakpoints

Once you’ve chosen values for the grid proportions, customize the layout’s breakpoints by editing the $breakpoints map. You can define as many (or as few) breakpoints as you like, and name them whatever you want. Just be sure to:

  • use the syntax shown below
  • keep the breakpoints in order (smallest to largest)
  • include a name (e.g. xl), number of columns (cols, unitless) and minimum width (min-width, with units, such as em or px) for each breakpoint

Any or all of the grid’s proportions can optionally be customized per breakpoint, using the keys margin, column, gutter, and padding. Breakpoints without those customizations will use the same proportions specified in the variables above. Here’s a sample $breakpoints map with five breakpoints:

$breakpoints: (
  xs: ( cols:  4, min-width:  0,   padding: 2em ), // Includes optional custom padding
  sm: ( cols:  6, min-width: 30em, margin: 5 ),    // Includes optional custom margin
  md: ( cols:  8, min-width: 40em ),
  lg: ( cols: 12, min-width: 50em ),
  xl: ( cols: 16, min-width: 60em )
);

Implementation

Once your settings are in place, import _column-settings.scss and _column-setter.scss (in that order) into your main Sass file:

@import "_column-settings.scss";
@import "_column-setter.scss";

Usage

To get the most out of Column Setter, using it in conjunction with * { box-sizing: border-box; } is strongly recommended. Column Setter is lean and mean, packing a lot of power into just one function and five optional mixins.

colspan()

colspan() is a function used to generate width values that align with the grid. To use it on an element, you’ll need to know how many columns wide the element’s container is. For example, to specify a width of six columns for an element inside a container that’s 12 columns wide:

.example {
  width: colspan( 6, 12 ); // 6 columns wide out of 12
}

Depending on your grid settings, the above code might compile to something like this:

.example {
  width: 48.82033%;
}

Or something like this:

.example {
  width: calc((((100% - 11em) / 12) * 6) + 5em);
}

colspan() will also take the arguments p (padding) and g (gutter):

img.inset {
  float: left;
  width: colspan( 2, 8 );
  padding: colspan( p, 8 );
  margin-right: colspan( g, 8 );
  margin-bottom: colspan( g, 8 );
}

A gutter width can optionally be added by including +g:

.example {
  margin-left: colspan( 6+g, 12 ); // 6 columns wide out of 12, plus an extra gutter
}

Widths can also be made negative (useful for negative margins) by including -:

.example {
  margin-left: colspan( -6+g, 12 );
}

grid()

grid() is a mixin used to establish the context for your grid. It sets the vertical margins for your layout at all breakpoints. The first (and only required) argument it takes is the class name of the layout’s container. If, for example, your layout is wrapped in a div with a class of main-content, you’ll invoke grid() like so:

@include grid( main-content );

This establishes the container’s horizontal margins for each of the breakpoints you specified in _column-settings.scss, and it compiles to something like this:

@media screen and (min-width: 0) {
  .content {
    margin: 0 3.38638%;
  }
}
@media screen and (min-width: 30em) {
  .content {
    margin: 0 4.36194%;
  }
}

You can also optionally include overlay as a second argument, which will put a translucent overlay of the grid on top of your layout so you can make sure everything is lining up correctly:

@include grid( main-content, overlay );

Please note that the overlay will only show padding widths if the grid is completely fluid (i.e. the initial variables in the settings are all unitless).

breakpoint-min(), breakpoint-max(), breakpoint-range()

The three breakpoint mixins generate media queries based on the $breakpoints settings specified in _column-settings.scss.

@include breakpoint-min( xs ) { ... }
@include breakpoint-max( sm ) { ... }
@include breakpoint-range( md, lg ) { ... }

The above code compiles to something like this:

@media screen and (min-width: 0) { ... }
@media screen and (max-width: 30em) { ... }
@media screen and (min-width: 40em) and (max-width: 50em) { ... }

full-width

full-width is a mixin used to break an element out of the layout and take up the full width of the viewport. It doesn’t take any arguments; its output is always the same. Use it like so:

.example {
  @include full-width;
}

The above code compiles to:

.example {
  width: auto;
  margin-left: calc(-50vw + 50%);
  margin-right: calc(-50vw + 50%);
}

Please note that full-width() only works on grids that are centered in the viewport.

Tips and tricks

  • For the most part, Column Setter code will compile even if you make a mistake—the invalid code will simply be ignored. If something isn’t working the way you expected, look for a WARNING on the command line. Column Setter can recognize common mistakes and help you troubleshoot them.

    WARNING: 'breakpoint-min(Gerald)' is invalid because 'Gerald' is not a valid breakpoint name. A 'breakpoint-min' mixin call must contain a valid breakpoint name, e.g. 'breakpoint-min(small)'. Current valid breakpoint names: xs, sm, md, lg, xl.
  • Elements are not confined to the width of their containers. Want an eight-column element inside a six-column container? No problem:

    width: colspan( 8, 6 );

    Want to center it? Remember, colspan() values can be made negative:

    margin-left: colspan( -1+g, 8 );
  • Each breakpoint is required to specify a number of columns, but those column counts don’t all have to be unique. You might want certain elements to change at a certain breakpoint without changing the rest of the layout. Just add another breakpoint in _column-settings.scss with the same number of columns as the one before or after it.

    $breakpoints: (
      small:  ( cols:  6, min-width:  0 ),
      medium: ( cols: 10, min-width: 30em ),
      large:  ( cols: 10, min-width: 35em )
    );

More Repositories

1

upton

A batteries-included framework for easy web-scraping. Just add CSS! (Or do more.)
HTML
1,614
star
2

guides

ProPublica's News App and Data Style Guides
1,163
star
3

compas-analysis

Data and analysis for 'Machine Bias'
Jupyter Notebook
600
star
4

weepeople

A typeface of people sillhouettes, to make it easy to build web graphics featuring little people instead of dots.
489
star
5

stateface

A typeface of U.S. state shapes to use in web apps.
HTML
359
star
6

timeline-setter

A tool to create HTML timelines from spreadsheets of events.
JavaScript
328
star
7

nyc-dna-software

The source code, acquired by ProPublica, for New York City's Forensic Statistical Tool.
C#
318
star
8

facebook-political-ads

Monitoring Facebook Political Ads
HTML
237
star
9

daybreak

A simple-dimple key value store for ruby.
HTML
236
star
10

sunlight-congress

The Sunlight Foundation's Congress API. Shut down on Oct. 1, 2017.
Ruby
169
star
11

landline

Simple SVG maps that work everywhere.
HTML
166
star
12

qis

Quick Instagram search tool
HTML
158
star
13

Capitol-Words

Scraping, parsing and indexing the daily Congressional Record to support phrase search over time, and by legislator and date
Python
121
star
14

politwoops-tweet-collector

Python workers that collect tweets from the twitter streaming api and track deletions
Python
120
star
15

simple-tiles

Simple tile generation for maps.
C
106
star
16

django-collaborative

ProPublica's collaborative tip-gathering framework. Import and manage CSV, Google Sheets and Screendoor data with ease.
Python
99
star
17

transcribable

Drop in crowdsourcing for your Rails app. Extracted from Free the Files.
Ruby
84
star
18

schooner-tk

A collection of (hopefully) useful utilities for working with satellite images.
C++
71
star
19

newsappmodel

Conceptual Model for News Applications
58
star
20

table-setter

Easy Peasy CSV to HTML
JavaScript
57
star
21

ilcampaigncash

Load Illinois political contribute and spending data efficiently
TSQL
57
star
22

congress-api-docs

Documentation for the ProPublica Congress API
HTML
54
star
23

campaign_cash

A Ruby client for interacting with ProPublica Campaign Finance API
Ruby
52
star
24

politwoops_sunlight

Politwoops web front end
CSS
44
star
25

data-institute-2019

Materials for the ProPublica Data Institute 2019
43
star
26

table-fu

A utility for spreadsheet-style handling of arrays (e.g. filtering, formatting, and sorting)
Ruby
35
star
27

fakenator

PHP
27
star
28

staffers

Interactive and searchable House staffer directory, based on House disbursement data.
HTML
26
star
29

data-institute-2018

For students of https://projects.propublica.org/graphics/ida-propublica-data-institute
26
star
30

vid-skim

Transcripts and commentary for long boring videos on YouTube!
Ruby
26
star
31

simpler-tiles

Ruby bindings for Simple Tiles
HTML
25
star
32

cookcountyjail2

A new version of the cook county jail scraper, inspired by the Supreme Chi-Town Coding Crew
HTML
23
star
33

disbursements

Data and scripts relating to the publishing of the House expenditure reports, and hopefully the Senate's in future.
Ruby
23
star
34

pixel-pong

Interface and data-collection backend for PixelPing.
JavaScript
22
star
35

propertyassessments

Analysis behind the "How the Cook County Assessor Failed Taxpayers"
R
22
star
36

data-nicar-2019

Nicar ML/NLP workshop by J Kao
Jupyter Notebook
19
star
37

thinner

Slow purges for varnish useful on app deploys.
Ruby
17
star
38

data-institute-2021

13
star
39

transcript-audio-sync

Tools for synchronizing audio and text on a webpage
JavaScript
12
star
40

pac-donor-similarity

Cosine similarity scores for PAC donors to federal candidates
10
star
41

capitol_words_nlp

Experimenting with parsing the congressional record using NLP techniques and tools
Python
9
star
42

redactor

Tool to remove email addresses, person entities, and phone numbers from a text
Python
9
star
43

auditData

data and scripts for https://projects.propublica.org/graphics/eitc-audit
R
9
star
44

il-tickets-notebooks

Explore Chicago ticket data.
Jupyter Notebook
9
star
45

il-ticket-loader

Load and analyze Chicago parking and camera ticket data
Jupyter Notebook
7
star
46

fbpac-api-public

API supporting more complex queries on the database of ads gathered by github.com/propublica/facebook-political-ads
Ruby
6
star
47

data-institute-2022

6
star
48

collaborative-playbook

5
star
49

northern-il-federal-gun-cases

Jupyter Notebook
5
star
50

d4dPartD-analysis

analysis of doctors' promotional payments from drug companies and their prescribing behavior
R
4
star
51

table-setter-generator

A rails generator for table-setter
JavaScript
4
star
52

institute-files

Data Institute Lessons
4
star
53

pentagon

CartoCSS
3
star
54

campaign-finance-api-docs

Documentation for campaign finance API
3
star
55

collaborative-playbook-pt

Collaborative Playbook in Portuguese
2
star
56

vital-signs-hackathon

1
star
57

political-ad-collector

web landing page for propublica's political ad collector
CSS
1
star