skelJS Overview v0.4.9

skelJS
v0.4.9
Overview
skelJS is a lightweight frontend framework for building responsive sites and apps. Consisting of only a single JS file (weighing in at just 20kb as of this
version), it gives designers and developers access to four powerful components:
CSS Grid System
A sophisticated 12 column CSS grid system with a concise, uncluttered syntax, adjustable gutters, unlimited nesting support and
many more cool features.
Responsive Handler
A streamlined replacement for CSS media queries designed to handle all of your responsive needs. Simple to configure, built to
handle any number of breakpoints, and capable of doing much more than simply shu)le stylesheets.
CSS Shortcuts
Handy shortcuts to swi+ly deal with all manner of common CSS tasks, like normalizing browser CSS (via normalize.css) and changing
the global box model.
Plugin System
A platform for extending skelJS without compromising its lightweight footprint (see the Panels plugin for an example).
An Example
The best way to learn how skelJS works is to see it in action, so here's a very common use case: building a responsive homepage.
index.html
Stylesheets
style-wide.css
style-narrow.css
style-mobile.css
Global Stylesheet: Contains styles shared by all breakpoints. Always gets loaded.
The Output
narrow
mobile
Example
Home
About Me
Blog
Contact
Hello world.
Lorem ipsum dolor sit amet sed magna etiam adipiscing.
Heading
Heading
Heading
Lorem ipsum dolor sit amet sed magna
Lorem ipsum dolor sit amet sed magna
Lorem ipsum dolor sit amet sed magna
etiam adipiscing elit. adipiscing elit nec
etiam adipiscing elit. adipiscing elit nec
etiam adipiscing elit. adipiscing elit nec
fringilla urna tempor in. Cras et sodales
fringilla urna tempor in. Cras et sodales
fringilla urna tempor in. Cras et sodales
And that's all there is to it. For a more in depth look, download the actual example or continue on to Setting Up.
Setting Up
1. Pick a Configuration Style
skelJS uses a JSON-like configuration that can be defined in one of two ways:
Inline
Preconfigured
Inline is good for testing and smaller projects, while Preconfigured is better for production as it allows the configuration to live in a separate JS file. For
demonstration purposes we'll just stick to Inline.
2. Get Configured
The next step is to build your configuration. Two ways to go about this:
Option 1: Use a preset
Presets are, as the name implies, preset configurations. You can use one like this:
Where (name_of_preset) is any of the following:
default
•
No stylesheets
•
No breakpoints
•
40px gutters on all grids
•
960px containers
standard
•
Stylesheet prefix set to "style"
•
Breakpoints set to mobile (480px and below), 1000px (481px to 1000px), and desktop (481px and up)
•
40px gutters on all grids
•
1200px containers on desktop, 960px containers on 1000px, and fluid containers on mobile (with collapse enabled)
(more to come later)
Option 2: Use your own (recommended)
While slightly more involved, this approach gives you far more control over how skelJS does its thing. For example, here's a configuration with 5 entirely
custom breakpoints and a few additional options:
If you go this route, be sure to read up on the many configuration options you have at your disposal.
3. Profit?
And with that, skelJS is fully configured and ready to go. Head on down to Usage or hit the Configuration Reference if you want to further flesh out your
configuration.
Usage
Containers
Containers are special wrapper elements whose widths are determined by whatever breakpoint happens to be active. By setting a container width on
each breakpoint (using the containers option) and wrapping stu) in a container, like so:
Said stu) will automatically adjust to the active breakpoint's container width. In this case, it'll become 1140px wide when wide is active, 960px wide
when narrow is active, and fluid when mobile is active.
Modifiers
These alter the width of a particular container. To use one, simply include it in the container's
<div class="container big">
).
small
Decreases the container's width by 25%.
big
class
attribute (eg.
Increases the container's width by 25% (up to the viewport width, but no less than the default container width).
Grid System
One of the cornerstones of skelJS is its grid system. In case you've never used one before, it's basically a simple way to build page layouts (even complex
ones) without developing an unbridled hatred for CSS.
Overview
The skelJS grid system is based around 12 vertical columns of equal width, with gutters (also of equal width) separating each one. The width of a
column is, in skelJS terminology, a unit. The system uses two types of elements:
Cell
•
Basic building block of the grid system.
•
Used to contain your content.
•
Can be between 1 unit wide (1u) and 12 units wide (12u).
Row
•
All you need to start a grid (no parent "grid" element is required).
•
Fits up to 12u worth of cells in any combination (4u+8u, 3u+3u+3u, 1u+12u, and so on).
•
Fluid width (so it'll fit anywhere you need it).
•
Can be wrapped by other elements (including containers).
•
Can be placed inside cells to form complex nested grids.
And here's how one actually looks:
12u
8u
2u
4u
4u
4u
2u
More examples below.
Configuration
Certain aspects of the grid system's behavior (such as gutter size) can be configured on a global level as well as per-breakpoint. Check out the
configuration reference for more details.
Modifiers
These change the behavior of a particular row. To use one, simply include it in the row's
class
attribute (eg.
<div class="row flush">
).
flush
Removes the gutters between each cell (similar to setting gutters to 0 in your configuration, only localized to a single row).
quarter
Decreases gutter size to 25%.
half
Decreases gutter size to 50%.
oneandhalf
Increases gutter size to 150%.
double
Increases gutter size to 200%.
no-collapse
Retains grid structure even if collapse is enabled.
O.sets
O)sets can be used to nudge a cell to the right by a number of units. They're applied like a cell's width class only prefixed with a dash (eg.
which means "nudge this cell right by 3 units"). Here's an example:
-3u
,
12u
9u
6u
3u
3u
3u
6u
3u
Examples
1 Row (8u + 4u)
8u
4u
2 Rows (3u+6u+3u, 4u+4u+4u)
3u
6u
4u
4u
4 Rows (12u, 3u+9u, 6u+6u, 6u+6u)
12u
3u
4u
3u
9u
6u
6u
6u
6u
3 Rows (3u+6u+3u, 4u+4u+4u, 6u+6u), flush modifier
3u
6u
4u
3u
4u
4u
6u
6u
1 Row (4u+4u+4u), inside cell of another row (2 Rows (9u+3u, 6u+6u))
4u
4u
6u
4u
3u
6u
Conditionals
Conditionals are classes that hide or show elements based on what breakpoints are active.
not-(breakpoint name)
Hides the element when (breakpoint name) is active.
only-(breakpoint name)
Only shows the element when (breakpoint name) is active.
Here's an example:
<noscript> Fallback
skelJS, as you might have already guessed, needs JS to work. Users with JS disabled will therefore be greeted with something reminiscent of the WWW
circa 1993. To fix this:
1. Download the noscript stylesheet (skel-noscript.css).
2. Decide on which of your breakpoints best represents your site (hint: most likely the one targeting desktops).
3. Go through the noscript stylesheet and comment/uncomment stu) to match your breakpoint.
4. Add a
<noscript>
block to your
<head>
element that adds the noscript stylesheet, your global stylesheet, and all stylesheets that apply to
your breakpoint. For example
And there you go. Users with JS disabled will now have an experience almost identical to that of their JS-enabled counterparts (minus the
responsiveness).
Manual Initialization
For simplicity, skelJS will automatically initialize as soon as it sees a configuration (be it Inline or Preconfigured). If you'd rather initialize it manually,
simply load skelJS without one:
Then when you're ready to initialize, simply call
skel.init()
with your configuration as the first argument:
You can also include plugin configurations with the second argument:
<html> Breakpoint Classes
Just in case you need them, skelJS will automatically append a list of active breakpoints to the
desktop and wide breakpoints are active:
<html>
element's class attribute. For example, if the
API
skelJS exposes a handful of methods via the
skel
object that can be used to obtain information on its current state as well as alter its behavior:
skel.vars.key
Gets the value of an internal skelJS variable.
key
(String) Key of value to retrieve. Can be any of the following:
viewportWidth
(Integer) Calculated viewport width. Used to determine what breakpoints are active.
devicePixelRatio
(Float) Calculated device pixel ratio. Used to calculate viewportWidth.
stateId
(String) Current state ID (a space-delimited list of all active breakpoint names).
lastStateId
(String) Previous state ID.
IEVersion
(Integer) Client's version of Internet Explorer (set to 99 if they're not using IE).
deviceType
(String) Client's device type (android, ios, wp, or other).
deviceVersion
(Float) Client's device version.
isTouch
(Boolean) If true, client is using a device with touch capabilities.
skel.isActive( breakpointName )
Determines if a breakpoint is active. Returns true if it is, or false if it isn't.
breakpointName
(String) A breakpoint name.
skel.wasActive( breakpointName )
Determines if a breakpoint was active prior to the last state change. Returns true if it was, or false if it wasn't.
breakpointName
(String) A breakpoint name.
skel.canUse( breakpointName )
Determines if a given breakpoint applies to the current viewport. Returns true if it can, or false if it cannot.
breakpointName
(String) A breakpoint name.
skel.lock( viewportWidth )
Locks skelJS into always using the given viewport width instead of calculating one on the fly. When called, the value is stored in a cookie (to preserve
it between page loads; see the note below) and the page is automatically refreshed. Can be cleared with skel.unlock().
viewportWidth
(Integer) Viewport width to use (in pixels).
Since the viewport width determines active breakpoints, locking it to a specific value means the same ones will always be active regardless of the
actual viewport size. Used in conjunction with skel.unlock() and skel.canUse() this allows for some pretty interesting stu); for example, given the
breakpoints from our example (wide, narrow, mobile), we can create a simple "Switch to Desktop" toggle that lets mobile devices pull up the
desktop (wide) layout:
Note: A single client-side cookie is used to preserve the locked viewport width between page loads. However, be aware this won't work locally as
browsers usually don't store cookies for pages accessed via file://.
skel.unlock()
Clears a lock (if one's been set). See skel.lock() for more info.
Configuration Reference
Options
prefix
Type
String
Default
null (Disables stylesheet management)
Sets the stylesheet prefix. If set, skelJS will use this to figure out the names of your global and breakpoint stylesheets. For example, setting it to
"style" with the following breakpoints configured:
•
wide
•
narrow
•
narrow960
•
narrow720
•
narrow480
will result in skelJS looking for these stylesheets:
•
style.css – global stylesheet (always applies)
•
style-wide.css – applies when wide is active
•
style-narrow.css – applies when narrow is active
•
style-narrow960.css – applies when narrow960 is active
•
style-narrow720.css – applies when narrow720 is active
•
style-narrow480.css – applies when narrow480 is active
A prefix can also include a path name. For example, setting it to "/assets/css/style" with the same breakpoints as above results in:
•
/assets/css/style.css – global stylesheet (always applies)
•
/assets/css/style-wide.css – applies when wide is active
•
/assets/css/style-narrow.css – applies when narrow is active
•
/assets/css/style-narrow960.css – applies when narrow960 is active
•
/assets/css/style-narrow720.css – applies when narrow720 is active
•
/assets/css/style-narrow480.css – applies when narrow480 is active
Setting prefix to null (the default) disables stylesheet management entirely.
containers
Type
Integer
Default
960
Sets the global container width. Can be an integer (implies pixel units), any valid CSS measurement (eg. "40em"), or "fluid" (equivalent to "100%").
grid
Type
Grid Options
Default
{ gutters: 40, collapse: false }
Sets global grid options.
breakpoints
Type
Breakpoint Options
Default
{ "all": { range: "*", hasStyleSheet: false } }
Your breakpoints, listed in the following format:
You can also use the following shorthand format if you only need to specify a range for each breakpoint:
Note: Since breakpoint ranges are allowed to overlap, more than one can be active at any given time. When this happens, the options of each are
combined in order with those defined last taking precedence.
resetCSS
Type
Boolean
Default
false
If true, default browser styles will be reset using Erik Meyer's CSS resets (built in to skelJS).
normalizeCSS
Type
Boolean
Default
false
If true, default browser styles will be normalized using normalize.css (built in to skelJS).
boxModel
Type
String
Default
null
Sets the global CSS box model. Can be "border", "content", "margin", or "padding".
useOrientation
Type
Boolean
Default
false
For simplicity, skelJS ignores device orientation (where applicable) and always assumes it's being used in portrait mode. This results in the same
viewport width regardless of actual orientation and greatly simplifies breakpoint configuration. However, if you do want orientation to be a factor,
set this to true.
useRTL
Type
Boolean
Default
false
If you're using a right-to-le+ language (such as Arabic or Hebrew), set this to true to enable RTL compatibility.
preloadStyleSheets
Type
Boolean
Default
false
By default, skelJS will dynamically load breakpoint stylesheets only when it needs them. Setting this option to true will instead preload them all
ahead of time.
pollOnce
Type
Boolean
Default
false
If true, breakpoint checks will only be performed the first time the page is loaded, disabling breakpoint switching on resize.
pollOnLock
Type
Boolean
Default
false
If true, skelJS will immediately perform breakpoint checks a+er every skel.lock() or skel.unlock() call.
usePerpetualLock
Type
Boolean
Default
true
If true, the e)ects of a skel.lock() call will last until skel.unlock() has been called. If false, the e)ects will go away at the end of the user's session.
useDomainLock
Type
Boolean
Default
true
If true, the e)ects of a skel.lock() call will be applied to the domain (not just the current page or path). If false, the e)ects will only be applied to the
current page or path.
Breakpoint Options
range
Type
String
Default
"*" (any width)
Sets the breakpoint's active width range (in pixels). Can be any of the following:
"*"
Matches any viewport width.
"X"
Viewport width must be exactly X.
"X-Y"
Viewport width must be between X and Y (inclusive).
"-X"
Viewport width must be less than or equal to X.
"X-"
Viewport width must be greater than or equal to X.
Note: Ranges can overlap with that of other breakpoints.
lockViewport
Type
Boolean
Default
false
If true, skelJS will (where applicable) disable viewport zooming and resizing. Should only be enabled on breakpoints targeting small devices (such as
phones and smaller tablets).
viewportWidth
Type
Integer
Default
false
If set, determines the viewport width on mobile devices (equivalent to
<meta name="viewport" content="width=(value)" />
).
hasStyleSheet
Type
Boolean
Default
true
Determines if there's a stylesheet for the breakpoint. By default this is true, but there are times when setting this to false makes sense (for example,
when a breakpoint exists only to change the container size).
containers
Type
Integer
Default
960
Sets the breakpoint's container width. Can be an integer (implies pixel units), any valid CSS measurement (eg. "40em"), or "fluid" (equivalent to
"100%"). Overrides the global container width.
grid
Type
Grid Options
Default
null
Sets the breakpoint's grid options. Overrides global grid options.
Grid Options
gutters
Type
Integer
Default
40
Sets the gutter size. Can be an integer (implies pixel units) or any valid CSS measurement (eg. "2%").
collapse
Type
Boolean
Default
false
If true, all cells (except those in no-collapse rows) are forced to be 100% wide regardless of their actual unit size ("collapsing" the grid). Should only
be enabled on breakpoints targeting small devices (such as phones and smaller tablets).
FAQ
What browsers work with skelJS?
Pretty much all modern (and a few not-so-modern) browsers:
•
Chrome
•
Firefox
•
Safari
•
Opera
•
Internet Explorer 8+
•
Android Browser (2.x and up)
•
Safari/iOS (4.x and up)
MIT Licensed
GitHub
Product of n33.