eduardoboucas / include-media-export Goto Github PK

View Code? Open in Web Editor NEW

72.0 2.0 9.0 19 KB

📐 An include-media plugin for exporting breakpoints from Sass to JavaScript

Home Page: https://www.npmjs.com/package/include-media-export

License: MIT License

JavaScript 100.00%

include-media-export's Introduction

include-media — Export breakpoints plugin

Get include-media here.

Introduction

include-media is a good solution for storing a list of breakpoints and using them to alter the behavior of a website using media queries. However, that list of breakpoints is restricted to the scope of the CSS stylesheets. That is fine most of the times, but it's not uncommon for developers to need access to that data on the JavaScript side. The concept is described here.

This plugin grabs all the breakpoints from include-media and outputs their status as JSON format on the content property of a DOM object (<body> by default), allowing developers to make decisions based on the viewport width without having to re-declare their breakpoints, leading to maintainability problems.

More information about this plugin can be found here.

Installation

Sass

Download _include-media-export.scss and include it in your Sass project

@import 'include-media-export';

JavaScript

Import includeMedia.min.js onto your project. This file is just a simplistic approach to access the information sent across by include-media. Feel free to extend it to fit your needs.

Bower

You can also use install the plugin using Bower

bower install include-media-export

API

###im.greaterThan(breakpoint) Determines whether the current viewport width is greater than or equal to a set breakpoint

Accepts:
- breakpoint - Name of the breakpoint to test against
Returns: Boolean
Example:

if (im.greaterThan('desktop')) {
    console.log('This is a really big screen');
}

###im.lessThan(breakpoint) Determines whether the current viewport is less than a set breakpoint

Accepts:
- breakpoint - Name of the breakpoint to test against
Returns: Boolean
Example:

if (im.lessThan('tablet')) {
    console.log('This looks like a phone or a small tablet');
}

###im.getActive() Returns the name of the largest breakpoint active

Accepts: N/A
Returns: String
Example:

if (im.getActive() == 'phone') {
    console.log('This looks like a phone');
}

###im.getValue(breakpoint, asNumber) Returns a breakpoint's value

Accepts:
- breakpoint - Name of the breakpoint
- asNumber (optional) - Return the value as a String (with units) or as a number (unitless)
Returns: String or Float
Example:

console.log('For me, a desktop has a width of ' + im.getValue('desktop'));

###im.setElement(element) Defines the element where the JSON data is contained (default is body::after)

Accepts:
- element - DOM element
Returns: N/A
Example:

im.setElement(document.getElementById('my-element'));

###im.setUpdateMode(mode) Defines how the library polls the DOM element for updates. By default, it happens automatically when any query function is executed. The user can decide to take control of when the updates actually happen, by setting the update mode to 'manual' and calling im.update() to update.

Note that when this function is called for the first time it automatically runs an update.

Accepts:
- mode - Update mode. auto (default) or manual
Returns: N/A
Example:

im.setUpdateMode('manual');

###im.update() Updates the information about the state of the breakpoints by querying the DOM and parsing the JSON object. You don't need to use this function unless you set the update mode to manual (see above).

Accepts: N/A
Returns: N/A
Example:

window.addEventListener('resize', im.update);

include-media-export's People

Contributors

Stargazers

Watchers

Forkers

jameslutley herrkessler drazik davidvictor tszarzynski megatroncgn polarbirke va21eu david-carty

include-media-export's Issues

Hugo's improvements

(Originally suggested by @hugogiraudel here with my comments in parenthesis)

Missing link in README (removed link altogether)
Remove camelCase from JS filename (and add version number)
Missing spaces after h3 in the README, API section
Missing space after : in SCSS file, line 17
Loosy equal in JS (fixed in #4)
Remove breakpoints[breakpoint].hasOwnProperty('active') from JS file (since I changed the JSON structure to always include the active property this no longer makes sense)
Remove dependency on parseFloat on im.getBreakpointValue(), allowing users to pass their own parsing function (won't we be adding unnecessary complexity?)

JSON.parse of readBreakpoints() errors with libsass

Due to "variable interpolation causes additional string escaping" as in sass/libsass#1115 the data object in readBreakpoints() returns an invalid string.

and check out the CSS:

One could fix the RegExp of the removeQuotes() function on line 80 to:

string = string.replace(/[']/g,'"').replace(/\\|^[\s\S]{0,1}|[\s\S]$/g, "");

This certainly not the best RegExp but works for me with libsass.

Clarifications on how to use `include-media-export` / Potentially adding docs

Hey @eduardoboucas,
I have been staring at the library for some time now, trying to implement it in one of my projects and try it, but there's no sufficient documentation/ information on how to do it. As I understand it:

Install it through npm: npm i include-media-export
Include it in your global scss file. In my case it's an index.scss with many reports. The problem may be here: I have tried to import it in 3 ways:
- @import 'include-media-export', like in your posted articles and NPM.
- @import '~/node_modules/include-media-export/dist/_include-media-export';, which is the one that makes sense in my case, I have the same import for include-media and it works.
- @import '~/node_modules/include-media-export'; to import the whole folder.
  If the way I do it is correct, then the problem might be elsewhere.
After this is done, I tried to make a custom function in one of my Vue components (So a JS file), but as soon as I type im., I don't get any suggestions, and it also complains that: SassError: Can't find stylesheet to import.╷ 109 │ @import '~/include-media-export' OR the rest of the import examples.
I also tried to import im like import {im} from 'many different folders' but ofc didnt work.

Do I understand the use of the library correctly?
If yes, can you elaborate on why I get these errors or how I can make it work?
I could also write some docs about it as I like the philosophy around it, as soon as I know how to use it :)

Best wishes!

Map with breakpoint values that are not in ascending order leads to false negatives in JavaScript

Working as expected:

Given a Sass map like include-media's default

$breakpoints: (
  'phone': 320px,
  'tablet': 768px,
  'desktop': 1024px
);

the correct active state of each CSS breakpoint will be correctly exposed for the current viewport via the content property of the configured element's (default: body) ::after-pseudo-element.

Not working as expected:

Given a more complex Sass map that has breakpoints without a strictly ascending order of values, the active state will not always be exposed correctly to JavaScript.

$breakpoints: (
  'phone': 320px,
  'tablet': 768px,
  'desktop': 1024px,
  'wide-screen': 1440px;
  'hero-switcharound': 1200px 
);

This export plugin generates CSS by looping through the map, so in this case the last generated media query will be @media (min-width: 1200px) { … }. Due to the way the CSS cascade works, the content of the pseudo-element is always set by the last matching media query.

So for viewports bigger than 1200px, content will always contain the JSON string generated for the hero-switcharound breakpoint and the exposed breakpoint active state will always be false for wide-screen – even for viewports bigger than 1440px.

Browser support

Hi Eduardo,

Just wanted to ask what kind of browser support your aiming for with this? I was trying to build a similar thing a while back and ran into issues with ie8 and some older version on android not being able to read the contents on the :after or :before pseudo elements. See this question I posted http://stackoverflow.com/questions/12959199/how-can-i-capture-after-content-in-ie8/13138505#13138505

In the end I found this project https://github.com/JoshBarr/on-media-query which started using the font-family property instead to get around these issues. I used it a few times but went back to declaring my breakpoints in both styles and javascript. By the looks of it that project has been abandoned a bit.

Things may be at a point where the browsers that cannot read the contents on the :after or :before pseudo elements no longer matter but I thought i'd give you a heads up incase you were not familiar with JoshBarr's project.

Carl.

Check for Element type?

Hi,

We log JS errors from our users, and very infrequently, this line in include-media.js causes some errors:

if (window.getComputedStyle && (window.getComputedStyle(element, '::after').content !== ''))

For instance, Googlebot encountered Failed to execute 'getComputedStyle' on 'Window': parameter 1 is not of type 'Element'. today

And 48 Firefox users (versions 47-50) encountered TypeError: window.getComputedStyle(...) is null over the past couple months

I can't pin down why this sometimes happens and have never been able to reproduce it myself, but I think it would help clear out some edge cases to check that window.getComputedStyle is a function and element is an Element before trying to use them?

Thanks!