formstone/docs/json/mediaquery.json

Library of modular front end components.

{"main":["mediaquery.js"],"options":[{"name":"minWidth","type":" 0 ","description":"Array of min-widths"},{"name":"maxWidth","type":" Infinity ","description":"Array of max-widths"},{"name":"minHeight","type":" 0 ","description":"Array of min-heights"},{"name":"maxHeight","type":" Infinity ","description":"Array of max-heights"},{"name":"unit","type":"string","default":"'px'","description":"Unit to use when matching widths and heights"}],"events":[{"name":"mqchange.mediaquery","description":"Change to a media query match; Triggered on window"}],"methods":[{"name":"bind","description":"Binds callbacks to media query matching.","params":[{"name":"key","type":"string","description":"Instance key"},{"name":"media","type":"string","description":"Media query to match"},{"name":"data","type":"object","description":"Object containing 'enter' and 'leave' callbacks"}],"examples":["$.mediaquery(\"bind\", \"key\", \"(min-width: 500px)\", { ... });"]},{"name":"defaults","description":"Extends plugin default settings; effects instances created hereafter.","params":[{"name":"options","type":"object","default":"{}","description":"New plugin defaults"}],"examples":["$.mediaquery(\"defaults\", { ... });"]},{"name":"state","description":"Returns the current state.","return":{"type":"object","description":"Current state object"},"examples":["var state = $.mediaquery(\"state\");"]},{"name":"unbind","description":"Unbinds all callbacks from media query.","params":[{"name":"key","type":"string","description":"Instance key"},{"name":"media","type":"string","description":"Media query to unbind; defaults to all"}],"examples":["$.mediaquery(\"unbind\", \"key\");"]}],"name":"Media Query","type":"utility","description":"A jQuery plugin for responsive media query events.","dependencies":["jQuery","core.js"],"use":"### Basic\n\nMedia Query can track global changes to screen size based on an existing grid system. This is useful when many elements need to be resized at any change to the target screen size. Start by configuring the dimensions to be tracked by passing arrays at initialization. These arrays should contain the target width and/or heights to react to:\n\n```javascript\n$.mediaquery({\n  minWidth     : [ 320, 500, 740, 980, 1220 ],\n  maxWidth     : [ 1220, 980, 740, 500, 320 ],\n  minHeight    : [ 400, 800 ],\n  maxHeight    : [ 800, 400 ]\n});\n```\n\n### Events\n\nAfter initializing, simply listen for the `mqchange.mediaquery` event:\n\n```javascript\n$(window).on(\"mqchange.mediaquery\", function(e, state) {\n  console.log(state.minWidth, state.maxWidth, state.minHeight, state.maxHeight);\n});\n```\n\nNote: In the example above, the `mqchange.mediaquery` event will be fire twice for each breakpoint. This is because Mediaquery will respond to both the `min-width` and `max-width` changes.\n\n### Binding\n\nMedia Query can also bind events to specific media query changes for more fine grain control:\n\n```javascript\n$.mediaquery(\"bind\", \"mq-key\", \"(min-width: 740px)\", {\n  enter: function() {\n    ...\n  },\n  leave: function() {\n    ...\n  }\n});\n```\n\nTo unbind a Media Query:\n\n```javascript\n$.mediaquery(\"unbind\", \"mq-key\");\n```\n","demo":"<h4>Basic</h4>\r\n\r\n<!-- START: FIRSTDEMO -->\r\n\r\n<style>\r\n  .demo_output { margin: 20px 0; }\r\n  .demo_output span { display: inline-block; width: 90px; }\r\n  .demo_output p { margin: 0 0 20px; }\r\n  .demo_output p:first-child { font-weight: 600; }\r\n</style>\r\n\r\n<script>\r\n  Formstone.Ready(function() {\r\n    $(window).on(\"mqchange.mediaquery\", logChange);\r\n\r\n    if (!$.mediaquery(\"state\")) {\r\n      $.mediaquery({\r\n        minWidth     : [ 320, 500, 740, 980, 1220 ],\r\n        maxWidth     : [ 1220, 980, 740, 500, 320 ],\r\n        minHeight    : [ 400, 800 ],\r\n        maxHeight    : [ 800, 400 ]\r\n      });\r\n    } else {\r\n      logChange({}, $.mediaquery(\"state\"));\r\n    }\r\n\r\n    $.mediaquery(\"bind\", \"demo\", \"(min-width: 740px)\", {\r\n      enter: logBind,\r\n      leave: logBind\r\n    });\r\n\r\n  });\r\n\r\n  function logChange(e, state) {\r\n    var html = \"\";\r\n    html += \"<p><span>Change:</span><span>MinWidth:</span>\" + state.minWidth + \"<br>\";\r\n    html += \"<span></span><span>MaxWidth:</span>\"+ state.maxWidth + \"<br>\";\r\n    html += \"<span></span><span>MinHeight:</span>\"+ state.minHeight + \"<br>\";\r\n    html += \"<span></span><span>MaxHeight:</span>\"+ state.maxHeight + \"</p>\";\r\n\r\n    $(\".demo_basic\").prepend(html);\r\n  }\r\n\r\n  function logBind() {\r\n    var mql = this,\r\n      type = mql.matches ? \"Enter\" : \"Leave\"\r\n      html = \"<p><span>\" + type + \":</span>\" + mql.media + \"<br>\";\r\n\r\n    $(\".demo_binding\").prepend(html);\r\n  }\r\n</script>\r\n\r\n<div class=\"demo_output demo_basic form_textarea\"></div>\r\n\r\n<!-- END: FIRSTDEMO -->\r\n\r\n<h4>Binding</h2>\r\n<div class=\"demo_output demo_binding form_textarea\"></div>\n","document":"# Media Query\n\nA jQuery plugin for responsive media query events.\n\n<!-- HEADER END -->\n\n<!-- NAV START -->\n\n* [Use](#use)\n* [Options](#options)\n* [Events](#events)\n* [Methods](#methods)\n\n<!-- NAV END -->\n\n<!-- DEMO BUTTON -->\n\n<a name=\"use\"></a>\n\n## Using Media Query\n\n\n#### Main\n\n```markup\nmediaquery.js\n```\n\n\n#### Dependencies\n\n```markup\njQuery\ncore.js\n```\n\n### Basic\n\nMedia Query can track global changes to screen size based on an existing grid system. This is useful when many elements need to be resized at any change to the target screen size. Start by configuring the dimensions to be tracked by passing arrays at initialization. These arrays should contain the target width and/or heights to react to:\n\n```javascript\n$.mediaquery({\n  minWidth     : [ 320, 500, 740, 980, 1220 ],\n  maxWidth     : [ 1220, 980, 740, 500, 320 ],\n  minHeight    : [ 400, 800 ],\n  maxHeight    : [ 800, 400 ]\n});\n```\n\n### Events\n\nAfter initializing, simply listen for the `mqchange.mediaquery` event:\n\n```javascript\n$(window).on(\"mqchange.mediaquery\", function(e, state) {\n  console.log(state.minWidth, state.maxWidth, state.minHeight, state.maxHeight);\n});\n```\n\nNote: In the example above, the `mqchange.mediaquery` event will be fire twice for each breakpoint. This is because Mediaquery will respond to both the `min-width` and `max-width` changes.\n\n### Binding\n\nMedia Query can also bind events to specific media query changes for more fine grain control:\n\n```javascript\n$.mediaquery(\"bind\", \"mq-key\", \"(min-width: 740px)\", {\n  enter: function() {\n    ...\n  },\n  leave: function() {\n    ...\n  }\n});\n```\n\nTo unbind a Media Query:\n\n```javascript\n$.mediaquery(\"unbind\", \"mq-key\");\n```\n\n\n\n<a name=\"options\"></a>\n\n## Options\n\nSet instance options by passing a valid object at initialization, or to the public `defaults` method.\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `minWidth` | ` 0 ` | &nbsp; | Array of min-widths |\n| `maxWidth` | ` Infinity ` | &nbsp; | Array of max-widths |\n| `minHeight` | ` 0 ` | &nbsp; | Array of min-heights |\n| `maxHeight` | ` Infinity ` | &nbsp; | Array of max-heights |\n| `unit` | `string` | `'px'` | Unit to use when matching widths and heights |\n\n<hr>\n<a name=\"events\"></a>\n\n## Events\n\nEvents are triggered on the `window`, unless otherwise stated.\n\n| Event | Description |\n| --- | --- |\n| `mqchange.mediaquery` | Change to a media query match; Triggered on window |\n\n<hr>\n<a name=\"methods\"></a>\n\n## Methods\n\nMethods are publicly available, unless otherwise stated.\n\n### bind\n\nBinds callbacks to media query matching.\n\n```javascript\n$.mediaquery(\"bind\", \"key\", \"(min-width: 500px)\", { ... });\n```\n\n#### Parameters\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `key` | `string` | &nbsp; | Instance key |\n| `media` | `string` | &nbsp; | Media query to match |\n| `data` | `object` | &nbsp; | Object containing 'enter' and 'leave' callbacks |\n\n### defaults\n\nExtends plugin default settings; effects instances created hereafter.\n\n```javascript\n$.mediaquery(\"defaults\", { ... });\n```\n\n#### Parameters\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `options` | `object` | `{}` | New plugin defaults |\n\n### state\n\nReturns the current state.\n\n```javascript\nvar state = $.mediaquery(\"state\");\n```\n\n### unbind\n\nUnbinds all callbacks from media query.\n\n```javascript\n$.mediaquery(\"unbind\", \"key\");\n```\n\n#### Parameters\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| `key` | `string` | &nbsp; | Instance key |\n| `media` | `string` | &nbsp; | Media query to unbind; defaults to all |\n\n"}