breakup 0.2.0 → 0.2.1
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +1 -0
- data/README.md +207 -6
- data/breakup.gemspec +1 -1
- data/examples/example_allblocks.css +14 -0
- data/examples/example_allblocks.scss +6 -0
- data/examples/example_oldie.css +7 -0
- data/examples/example_oldie.scss +14 -0
- data/examples/example_wideonly.css +5 -0
- data/examples/example_wideonly.scss +6 -0
- data/examples/partials/_component.scss +11 -0
- data/examples/partials/_global_variables.scss +5 -0
- data/lib/breakup/version.rb +1 -1
- data/script/examples-watch +3 -0
- data/stylesheets/_breakup.scss +67 -71
- metadata +12 -4
data/.gitignore
CHANGED
data/README.md
CHANGED
@@ -2,16 +2,217 @@ Breakup
|
|
2
2
|
=======
|
3
3
|
|
4
4
|
Breakup is a Sass component that allows you to create multiple CSS files from a
|
5
|
-
single Sass partial by wrapping your code within breakpoint blocks. It
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
5
|
+
single Sass partial by wrapping your code within breakpoint blocks. It allows
|
6
|
+
you to abstract what your Sass partials folder looks like from what CSS files
|
7
|
+
you create. Because of this you can easily create per-breakpoint CSS files (e.g.
|
8
|
+
base, mobile, tablet and desktop) and fallback files where no styles are wrapped
|
9
|
+
(e.g. for oldIE which does not support media queries).
|
10
|
+
|
11
|
+
|
12
|
+
## The Problem(s)
|
13
|
+
|
14
|
+
The current trend towards OOCSS using Sass results in many small partials -- one
|
15
|
+
per object. This is excellent for readability and reducing mental overhead until
|
16
|
+
the complication of creating per-media query stylesheets, and oldIE stylesheets
|
17
|
+
(where media queries are unsupported) appears. The simplest solution is to
|
18
|
+
create even more partials named for each component's breakpoint (e.g.
|
19
|
+
_component.scss & _component_wide.scss) but this results in a proliferation of
|
20
|
+
partials which shall rapidly introduce noise to your partials folder.
|
21
|
+
|
22
|
+
|
23
|
+
## Breakup's Solution
|
24
|
+
|
25
|
+
Breakup allows you to write a single partial per object. By isolating each
|
26
|
+
breakpoint's code inside a mixin block your output stylesheets can choose what
|
27
|
+
blocks should be included within them and whether or not those blocks should
|
28
|
+
even be wrapped inside a media query (for oldIE stylesheets you can serve the
|
29
|
+
basic styles and the unwrapped wide styles so oldIE is given the wide view).
|
30
|
+
|
31
|
+
|
32
|
+
## Installation
|
33
|
+
|
34
|
+
Breakup is distributed as a Compass plugin (though it is written in pure SCSS,
|
35
|
+
so works as a stand-alone file without a dependancy on Compass).
|
36
|
+
|
37
|
+
* Run `gem install breakup` or add breakup to your Gemfile.
|
38
|
+
* Add `require "breakup"` to the top of your compass.rb
|
39
|
+
* Add `@import 'breakup';` to your base stylesheets
|
40
|
+
|
41
|
+
Alternatively, if you don't want to be dependant upon Compass, you can copy
|
42
|
+
[stylesheets/_breakup.scss](stylesheets/_breakup.scss) into your project and
|
43
|
+
`@import` it from there.
|
44
|
+
|
45
|
+
|
46
|
+
## Usage
|
47
|
+
|
48
|
+
The following examples can also be found in the [examples/](examples) folder
|
49
|
+
|
50
|
+
### Setup: Named Blocks & Breakpoints
|
51
|
+
|
52
|
+
Blocks are chunks of SCSS to be output, they have arbitrary names. Breakpoints
|
53
|
+
are blocks that have an attached media query that they shall be wrapped in.
|
54
|
+
|
55
|
+
First of all identify where your major breakpoints shall be and define them as a
|
56
|
+
list of lists (where the sub-list contains two items: the breakpoint name and
|
57
|
+
its media query it represents):
|
58
|
+
|
59
|
+
```SCSS
|
60
|
+
// _global_variables.scss
|
61
|
+
$breakup-breakpoints: (
|
62
|
+
'thin' '(max-width: 35.999em)',
|
63
|
+
'wide' '(min-width: 36em)',
|
64
|
+
'full' '(min-width: 61em)'
|
65
|
+
);
|
66
|
+
```
|
67
|
+
|
68
|
+
Then in your component define the blocks and breakpoints that make up your
|
69
|
+
component. In this example we want the 'basic' block to be output without any
|
70
|
+
wrappers, but the 'wide' breakpoint shall be wrapped in an @media block.
|
71
|
+
|
72
|
+
```SCSS
|
73
|
+
// _component.scss
|
74
|
+
@include breakup-block('basic') {
|
75
|
+
.component { background-color: red; }
|
76
|
+
}
|
77
|
+
|
78
|
+
@include breakup-breakpoint('thin') {
|
79
|
+
.component { background-color: blue; }
|
80
|
+
}
|
81
|
+
|
82
|
+
@include breakup-breakpoint('wide') {
|
83
|
+
.component { background-color: green; }
|
84
|
+
}
|
85
|
+
```
|
86
|
+
|
87
|
+
### A Single Output File
|
88
|
+
|
89
|
+
In your root scss file define what blocks should be rendered by defining the
|
90
|
+
list `$breakup-included-blocks`:
|
91
|
+
|
92
|
+
```SCSS
|
93
|
+
// example_allblocks.scss
|
94
|
+
@import 'breakup';
|
95
|
+
$breakup-included-blocks: ('basic' 'thin' 'wide' 'full');
|
96
|
+
|
97
|
+
@import 'partials/global_variables';
|
98
|
+
@import 'partials/component';
|
99
|
+
```
|
100
|
+
|
101
|
+
This shall output:
|
102
|
+
|
103
|
+
```CSS
|
104
|
+
.component {
|
105
|
+
background-color: red;
|
106
|
+
}
|
107
|
+
|
108
|
+
@media (max-width: 35.999em) {
|
109
|
+
.component {
|
110
|
+
background-color: blue;
|
111
|
+
}
|
112
|
+
}
|
113
|
+
@media (min-width: 36em) {
|
114
|
+
.component {
|
115
|
+
background-color: green;
|
116
|
+
}
|
117
|
+
}
|
118
|
+
```
|
119
|
+
|
120
|
+
|
121
|
+
### Per Media Query Blocks
|
122
|
+
|
123
|
+
By changing `$breakpoint-included-blocks` we can change what boxes to include.
|
124
|
+
To create a stylesheet that contains only our wide styles we can specify just
|
125
|
+
the 'wide' block:
|
126
|
+
|
127
|
+
|
128
|
+
```SCSS
|
129
|
+
// example_wideonly.scss
|
130
|
+
@import 'breakup';
|
131
|
+
$breakup-included-blocks: ('wide');
|
132
|
+
|
133
|
+
@import 'partials/global_variables';
|
134
|
+
@import 'partials/component';
|
135
|
+
```
|
136
|
+
|
137
|
+
This shall output:
|
138
|
+
|
139
|
+
```CSS
|
140
|
+
@media (min-width: 36em) {
|
141
|
+
.component {
|
142
|
+
background-color: green;
|
143
|
+
}
|
144
|
+
}
|
145
|
+
```
|
146
|
+
|
147
|
+
### Stripping Media Queries (for oldIE)
|
148
|
+
|
149
|
+
OldIE doesn't understand media queries so we need to not wrap our breakpoints
|
150
|
+
with an @media block, just output their contents as-is. This is controlled with
|
151
|
+
`$breakup-naked` and `$breakup-breakpoints-allow-naked`. `$breakup-naked: true`
|
152
|
+
tells breakup that it should not not wrap breakpoints up.
|
153
|
+
`$breakup-breakpoints-allow-naked` is a list of breakpoints that should be
|
154
|
+
output when `$breakup-naked` is true. By default this is empty and any
|
155
|
+
breakpoints not specified shall be not be output, even if they are referenced in
|
156
|
+
`$breakup-included-blocks`.
|
157
|
+
|
158
|
+
```SCSS
|
159
|
+
// example_oldie.scss
|
160
|
+
@import 'breakup.scss';
|
161
|
+
|
162
|
+
$breakup-included-blocks: ('basic' 'wide' 'full');
|
163
|
+
$breakup-naked: true;
|
164
|
+
$breakup-breakpoints-allow-naked: ('wide' 'full');
|
165
|
+
|
166
|
+
@import 'partials/global_variables';
|
167
|
+
@import 'partials/component';
|
168
|
+
```
|
169
|
+
|
170
|
+
This shall output:
|
171
|
+
|
172
|
+
```CSS
|
173
|
+
.component {
|
174
|
+
background-color: red;
|
175
|
+
}
|
176
|
+
|
177
|
+
.component {
|
178
|
+
background-color: green;
|
179
|
+
}
|
180
|
+
```
|
181
|
+
|
182
|
+
### Tweakpoints
|
183
|
+
|
184
|
+
Often we want smaller changes to occur at points between our major breakpoints.
|
185
|
+
Instead of breaks in layout they are minor adjustments --
|
186
|
+
[tweakpoints](http://adactio.com/journal/6044/). This can be accomplished by
|
187
|
+
wrapping a `breakup-media` within a `breakup-block`:
|
188
|
+
|
189
|
+
```SCSS
|
190
|
+
// _component.scss
|
191
|
+
@include breakup-block('wide') {
|
192
|
+
@include breakup-media('(min-width: 40em)') {
|
193
|
+
.component {
|
194
|
+
background-color: green;
|
195
|
+
}
|
196
|
+
}
|
197
|
+
}
|
198
|
+
```
|
199
|
+
|
200
|
+
Breakup provides a convenience method for this so the following is a shorthand
|
201
|
+
equivalent:
|
202
|
+
|
203
|
+
```SCSS
|
204
|
+
// _component.scss
|
205
|
+
@include breakup-tweakpoint('(min-width: 40em)', 'wide') {
|
206
|
+
.component {
|
207
|
+
background-color: green;
|
208
|
+
}
|
209
|
+
}
|
210
|
+
```
|
10
211
|
|
11
212
|
|
12
213
|
## TODO
|
13
214
|
|
14
|
-
|
215
|
+
More usage examples and tests coming soon.
|
15
216
|
|
16
217
|
|
17
218
|
## Prior Art
|
data/breakup.gemspec
CHANGED
@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
|
|
17
17
|
breakpoint CSS files (e.g. base, mobile, tablet and desktop) and fallback
|
18
18
|
files where no styles are wrapped (e.g. for oldIE which does not support media
|
19
19
|
queries).'
|
20
|
-
gem.homepage = '
|
20
|
+
gem.homepage = 'https://github.com/bpscott/breakup'
|
21
21
|
|
22
22
|
# Gem Files
|
23
23
|
gem.files = `git ls-files`.split($/)
|
data/lib/breakup/version.rb
CHANGED
data/stylesheets/_breakup.scss
CHANGED
@@ -4,49 +4,49 @@
|
|
4
4
|
// A tool for defining breakpoints and conditionally loading them.
|
5
5
|
//////////////////////////////////////////////////////////////////
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
7
|
+
|
8
|
+
// Global Variables
|
9
|
+
//
|
10
|
+
// $breakup-breakpoints: List of many named breakpoints that can be called with
|
11
|
+
// breakup-breakpoint. Each breakpoint is a list containing the breakpoint
|
12
|
+
// name and the media query it describes. Example:
|
13
|
+
//
|
14
|
+
// $breakup-breakpoints: (
|
15
|
+
// 'palm' '(max-width: 480px)',
|
16
|
+
// 'lap' '(min-width: 481px) and (max-width: 1023px)',
|
17
|
+
// 'portable' '(max-width: 1023px)',
|
18
|
+
// 'desk' '(min-width: 1024px)'
|
19
|
+
// );
|
20
|
+
//
|
21
|
+
//
|
22
|
+
// $breakup-included-blocks: A list of blocks to render in your stylesheet
|
23
|
+
//
|
24
|
+
//
|
25
|
+
// $breakup-naked: Should breakpoint/tweakpoint blocks be wrapped in an @media
|
26
|
+
// declaration? You should set this to true within stylesheets for browsers
|
27
|
+
// which don't support @media, such as oldIE.
|
28
|
+
//
|
29
|
+
//
|
30
|
+
// $breakup-allow-naked: List of named breakpoints and if they should be output
|
31
|
+
// when $breakup-naked is true (by default this is false). This is separate
|
32
|
+
// to $breakup-breakpoints because you may want to configure what
|
33
|
+
// breakpoints are unwrapped on a per stylesheet basis.
|
34
|
+
///
|
35
35
|
$breakup-breakpoints: () !default;
|
36
36
|
$breakup-included-blocks: () !default;
|
37
37
|
$breakup-naked: false !default;
|
38
38
|
$breakup-breakpoints-allow-naked: () !default;
|
39
39
|
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
40
|
+
|
41
|
+
|
42
|
+
// Search a list of lists ($haystack) for value ($needle) at a given position
|
43
|
+
// ($offset). Returns that item in the list, or false if not found.
|
44
|
+
//
|
45
|
+
// Example:
|
46
|
+
// list-key-search((
|
47
|
+
// ('key1' 'value1'),
|
48
|
+
// ('key2' 'value2')
|
49
|
+
// ), 'key1', 1) => (key1 value1)
|
50
50
|
@function breakup-list-key-search($haystack, $needle, $offset: 1) {
|
51
51
|
@each $haystack-item in $haystack {
|
52
52
|
@if $needle == nth($haystack-item, $offset) {
|
@@ -58,16 +58,15 @@ $breakup-breakpoints-allow-naked: () !default;
|
|
58
58
|
}
|
59
59
|
|
60
60
|
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
*/
|
61
|
+
|
62
|
+
// Wrapper around a @media block. if $breakup-naked is true then the
|
63
|
+
// content is output directly if the declaration has been marked as a fallback
|
64
|
+
// breakpoint.
|
65
|
+
//
|
66
|
+
// $declaration: A @media declaration to wrap the content block in.
|
67
|
+
// $allow-naked: Should this content should be rendered if the we are
|
68
|
+
// displaying naked content (i.e. not wrapped in a media
|
69
|
+
// query).
|
71
70
|
@mixin breakup-media($declaration, $allow-naked: false) {
|
72
71
|
@if not $breakup-naked {
|
73
72
|
@media #{$declaration} {
|
@@ -84,12 +83,11 @@ $breakup-breakpoints-allow-naked: () !default;
|
|
84
83
|
}
|
85
84
|
|
86
85
|
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
*/
|
86
|
+
|
87
|
+
// Include a block in the page if it is included in within
|
88
|
+
// $breakup-included-blocks
|
89
|
+
//
|
90
|
+
// $block-name: The block name to render
|
93
91
|
@mixin breakup-block($block-name) {
|
94
92
|
@if index($breakup-included-blocks, $block-name) != false {
|
95
93
|
@content;
|
@@ -97,13 +95,12 @@ $breakup-breakpoints-allow-naked: () !default;
|
|
97
95
|
}
|
98
96
|
|
99
97
|
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
*/
|
98
|
+
|
99
|
+
// Look up a named breakpoint from $breakup-breakpoints, and wrap it in a block
|
100
|
+
// so that it only appears if it is in the current stylesheet's
|
101
|
+
// $breakup-included-blocks.
|
102
|
+
//
|
103
|
+
// $breakpoint-name: The breakpoint name to render
|
107
104
|
@mixin breakup-breakpoint($breakpoint-name) {
|
108
105
|
$breakpoint: breakup-list-key-search($breakup-breakpoints, $breakpoint-name, 1);
|
109
106
|
|
@@ -132,16 +129,15 @@ $breakup-breakpoints-allow-naked: () !default;
|
|
132
129
|
}
|
133
130
|
|
134
131
|
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
139
|
-
|
140
|
-
|
141
|
-
|
142
|
-
|
143
|
-
|
144
|
-
*/
|
132
|
+
|
133
|
+
// Create an unnamed tweakpoint and wrap it in a block so that it only appears
|
134
|
+
// if it is in the current stylesheet's $breakup-included-blocks.
|
135
|
+
//
|
136
|
+
// $declaration: A media query that the content shall be wrapped in
|
137
|
+
// $block-name: The block name to display
|
138
|
+
// $allow-naked: Should this content should be rendered if the we are
|
139
|
+
// displaying naked content (i.e. not wrapped in a media
|
140
|
+
// query).
|
145
141
|
@mixin breakup-tweakpoint($declaration, $block-name, $allow-naked: false) {
|
146
142
|
@include breakup-block($block-name) {
|
147
143
|
@include breakup-media($declaration, $allow-naked) {
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: breakup
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.2.
|
4
|
+
version: 0.2.1
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2013-
|
12
|
+
date: 2013-09-01 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: sass
|
@@ -54,10 +54,19 @@ files:
|
|
54
54
|
- LICENSE.txt
|
55
55
|
- README.md
|
56
56
|
- breakup.gemspec
|
57
|
+
- examples/example_allblocks.css
|
58
|
+
- examples/example_allblocks.scss
|
59
|
+
- examples/example_oldie.css
|
60
|
+
- examples/example_oldie.scss
|
61
|
+
- examples/example_wideonly.css
|
62
|
+
- examples/example_wideonly.scss
|
63
|
+
- examples/partials/_component.scss
|
64
|
+
- examples/partials/_global_variables.scss
|
57
65
|
- lib/breakup.rb
|
58
66
|
- lib/breakup/version.rb
|
67
|
+
- script/examples-watch
|
59
68
|
- stylesheets/_breakup.scss
|
60
|
-
homepage:
|
69
|
+
homepage: https://github.com/bpscott/breakup
|
61
70
|
licenses: []
|
62
71
|
post_install_message:
|
63
72
|
rdoc_options: []
|
@@ -87,4 +96,3 @@ summary: Breakup is a Sass component that allows you to create multiple CSS file
|
|
87
96
|
mobile, tablet and desktop) and fallback files where no styles are wrapped (e.g.
|
88
97
|
for oldIE which does not support media queries).
|
89
98
|
test_files: []
|
90
|
-
has_rdoc:
|