From afddcc28290af7d4f559ca7be7a0cd60b34d30d7 Mon Sep 17 00:00:00 2001 From: Thomas Parisot Date: Fri, 9 Jan 2015 19:55:16 +0000 Subject: [PATCH] Documentation cleanup. --- .ruby-version | 1 - README.md | 220 ++------------------------------------------- docs/html-api.md | 69 ++++++++++++++ docs/js-api.md | 36 +++++++- docs/js-options.md | 126 ++++++++++++++++++++++++++ karma.conf.js | 85 ------------------ package.json | 1 - 7 files changed, 237 insertions(+), 301 deletions(-) delete mode 100644 .ruby-version create mode 100644 docs/html-api.md create mode 100644 docs/js-options.md diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index 227cea2..0000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -2.0.0 diff --git a/README.md b/README.md index 00e0561..eff6eb1 100644 --- a/README.md +++ b/README.md @@ -175,220 +175,13 @@ This will result in the following HTML output: ``` ---- - # Documentation -## HTML Attributes - -The *HTML API* helps you control how Imager works from the *content point of view*. - -### `data-src` - -Available placeholders are: - -- `{width}`: best available image width (numeric value) -- `{pixel_ratio}`: device pixel ratio (either *blank* or `-1.3x`, `-2x`, `-3x` etc.) - - -So the following HTML... - -```html -
-``` - -...is converted to... - -```html - -``` - -### `data-width` - -`data-width` is the enforced size of the image placeholder; where the actual image will eventually be loaded. - -This can be especially useful if you don't want to depend on the image container width. - -So the following HTML... - -```html -
-
-
-``` - -...is converted to... - -```html -
- alternative text -
-``` - -### `data-alt` and `data-class` - -These two `data-*` attributes are copied from the responsive placeholder to the response `img` element.nnot process images or who have image loading disabled. It is converted to the `alt` attribute of the `img element. - -So the following HTML... - -```html -
-
-``` - -...is converted to... - -```html -alternative text - -``` - -## JavaScript Configuration - -You can create one or several concurrent configurations of Imager within the same page. Its configuration options are -described below. - -[Advanced JavaScript API documentation lies in the `docs/` folder](docs/js-api.md). - -### `availableWidths` - -This option is intended to reflect the available widths of each responsive image. These values will be used as replacements -for the `{width}` variable in `data-src` placeholders. - -The following examples demonstrate the results of passing through different object types for the `availableWidths` option... - -`Array`: the widths are represented as numeric values - -```js -new Imager({ - availableWidths: [240, 320, 640] -}); -``` - -`Object`: the widths associate a string value for their numeric counterpart - -```js -new Imager({ - availableWidths: { - 240: 'small', - 320: 'medium', - 640: 'large' - } -}); -``` - -`Function`: must return a value for the provided width argument - -```js -// will return a double sized image width as a numeric value -new Imager({ - availableWidths: function (image) { - return image.clientWidth * 2; - } -}); -``` - -### `availablePixelRatios` - -An Array which indicates what are the available pixel ratios available for your responsive images. - -These values will be used as replacements for the `{pixel_ratio}` variable in `data-src` placeholders. - -```js -new Imager({ availablePixelRatios: [1, 2] }); -``` - -**Default value**: `[1, 2]` - -### `className` - -A String which indicates what the `className` value will be added on the newly created responsive image. - -```js -new Imager({ className: 'image-replace' }); -``` - -**Default value**: `image-replace` - -### `scrollDelay` - -An Integer value (in milliseconds) to indicate when Imager will check if a scroll has ended. If a scroll has stopped after this delay and the `lazyload` option is `true`, Imager will update the `src` attribute of the relevant images. - -**Default value**: `250` - -```js -new Imager({ scrollDelay: 250 }); -``` - -**Notice**: set the `scrollDelay` value to `0` at your own risk; unless you know what you're doing, setting the value to zero will make the user experience totally janky! (and that would be an odd thing to do as you have chosen to use Imager to improve the user experience) - -### `onResize` - -A Boolean value. If set to `true`, Imager will update the `src` attribute of the relevant images. - -**Default value**: `true` - -```js -new Imager({ onResize: true }); -``` +Browse Imager public APIs and options – versioned alongside the source code of the project: -### `lazyload` - -An *experimental* Boolean value. If set to `true`, Imager will update the `src` attribute only of visible (and nearly visible) images. - -**Default value**: `false` - -```js -new Imager({ lazyload: true }); -``` - -### `lazyloadOffset` - -A `Number` of extra pixels below the fold taken in account by the lazyloading mechanism. - -**Default value**: `0` - -```js -new Imager({ lazyload: true, lazyloadOffset: 300 }); -``` - -### `onImagesReplaced` - -A callback `Function`. Runs after Imager updates the `src` attribute of all relevant images. - -Its first and unique argument is an `Array` of `HTMLImageElement`, the ones processed by Imager. - -```js -new Imager({ - onImagesReplaced: function(images) { - console.log('the src of all relevant images has been updated'); - } -}); -``` - -## JavaScript API - -### `.ready(fn)` - -Executes a function when Imager is ready to work. - -```js -new Imager({ ... }).ready(function(){ - console.log('Placeholders divs have been replaced'); -}); -``` - -### `.add(elements | selector)` - -Add new elements to the existing pool of responsive images. - -```js -var imgr = new Imager('.delayed-image-load'); - -imgr.add('.new-delayed-image-load-selector'); -imgr.add(newElements); -imgr.add(); // reuses the constructor selector ('.delayed-image-load') -``` +- [HTML options](docs/html-api.md) +- [JavaScript options](docs/js-options.md) +- [JavaScript API](docs/js-api.md) # Demos @@ -398,8 +191,10 @@ Additional and fully working examples lie in the [`demos` folder](demos/). # They are using it - [BBC News](http://m.bbc.co.uk/news) +- [BBC Sport](http://m.bbc.co.uk/sport) - [The Guardian](http://www.theguardian.com/) - [`x-imager` Web Component](https://github.com/addyosmani/x-imager) +- [Imager.jsx React Component](https://www.npmjs.com/package/imager.jsx) # Background @@ -415,6 +210,7 @@ Much of this work can be repurposed to work with a more standards-based approach For the purposes of maintaining a distinguishment between the ImageEnhancer concept built by BBC News and this project, we're calling it **Imager.js** +**[Read more on BBC Responsive News blog](http://responsivenews.co.uk/post/58244240772/imager-js)**. # Credits @@ -426,7 +222,7 @@ For the purposes of maintaining a distinguishment between the ImageEnhancer conc # Licence -> Copyright 2014 British Broadcasting Corporation +> Copyright 2015 British Broadcasting Corporation > > Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at > diff --git a/docs/html-api.md b/docs/html-api.md new file mode 100644 index 0000000..46cf2dc --- /dev/null +++ b/docs/html-api.md @@ -0,0 +1,69 @@ +# Imager.js documentation + +- [HTML options](html-api.md) +- [JavaScript options](js-options.md) +- [JavaScript API](js-api.md) + +## HTML Attributes + +The *HTML API* helps you control how Imager works from the *content point of view*. + +### `data-src` + +Available placeholders are: + +- `{width}`: best available image width (numeric value) +- `{pixel_ratio}`: device pixel ratio (either *blank* or `-1.3x`, `-2x`, `-3x` etc.) + + +So the following HTML... + +```html +
+``` + +...is converted to... + +```html + +``` + +### `data-width` + +`data-width` is the enforced size of the image placeholder; where the actual image will eventually be loaded. + +This can be especially useful if you don't want to depend on the image container width. + +So the following HTML... + +```html +
+
+
+``` + +...is converted to... + +```html +
+ alternative text +
+``` + +### `data-alt` and `data-class` + +These two `data-*` attributes are copied from the responsive placeholder to the response `img` element.nnot process images or who have image loading disabled. It is converted to the `alt` attribute of the `img element. + +So the following HTML... + +```html +
+
+``` + +...is converted to... + +```html +alternative text + +``` diff --git a/docs/js-api.md b/docs/js-api.md index 3be44e5..2cc8834 100644 --- a/docs/js-api.md +++ b/docs/js-api.md @@ -1,3 +1,9 @@ +# Imager.js documentation + +- [HTML options](html-api.md) +- [JavaScript options](js-options.md) +- [JavaScript API](js-api.md) + ## JavaScript API The *JavaScript API* helps you instantiate and control how Imager works from a *business logic point of view*. @@ -6,7 +12,7 @@ The *JavaScript API* helps you instantiate and control how Imager works from a * Calling the constructor will initialise responsive images for the provided `elements` or the HTML elements concerned by the `selector`. -The `options` bit is an object documented below, in the [JavaScript Options section](#javascript-options). +The `options` bit is an object documented in the [JavaScript Options section](js-options.md). ```js new Imager('.responsive-image-placeholder'); @@ -28,6 +34,30 @@ new Imager(); ``` +### `.ready(fn)` + +Executes a function when Imager is ready to work. + +```js +new Imager({ ... }).ready(function(){ + console.log('Placeholders divs have been replaced'); +}); +``` + + +### `.add(elements | selector)` + +Add new elements to the existing pool of responsive images. + +```js +var imgr = new Imager('.delayed-image-load'); + +imgr.add('.new-delayed-image-load-selector'); +imgr.add(newElements); +imgr.add(); // reuses the constructor selector ('.delayed-image-load') +``` + + ### `Imager.checkImagesNeedReplacing()` Updates the `img[src]` attribute if the container width has changed, and if it matches a different `availableWidths` value. @@ -41,6 +71,7 @@ var imgr = new Imager(); $(document).on('customEvent', $.proxy(imgr.checkImagesNeedReplacing, imgr)); ``` + ### `Imager.registerResizeEvent()` Registers a `window.onresize` handler which will update the relevant `img[src]` (using `Imager.checkImagesNeedReplacing`) @@ -55,6 +86,7 @@ var imgr = new Imager(); $(document).on('load', $.proxy(imgr.registerResizeEvent, imgr)); ``` + ### `Imager.registerScrollEvent()` Registers a `window.onscroll` handler which will update the relevant `img[src]` (using `Imager.checkImagesNeedReplacing`) @@ -68,4 +100,4 @@ var imgr = new Imager(); // Using jQuery to set-up the event handling and help keep the correct scope when executing the callback $(document).on('load', $.proxy(imgr.registerScrollEvent, imgr)); -``` \ No newline at end of file +``` diff --git a/docs/js-options.md b/docs/js-options.md new file mode 100644 index 0000000..30cede1 --- /dev/null +++ b/docs/js-options.md @@ -0,0 +1,126 @@ +# Imager.js documentation + +- [HTML options](html-api.md) +- [JavaScript options](js-options.md) +- [JavaScript API](js-api.md) + +## JavaScript Configuration + +You can create one or several concurrent configurations of Imager within the same page. Its configuration options are +described below. + +### `availableWidths` + +This option is intended to reflect the available widths of each responsive image. These values will be used as replacements +for the `{width}` variable in `data-src` placeholders. + +The following examples demonstrate the results of passing through different object types for the `availableWidths` option... + +`Array`: the widths are represented as numeric values + +```js +new Imager({ + availableWidths: [240, 320, 640] +}); +``` + +`Object`: the widths associate a string value for their numeric counterpart + +```js +new Imager({ + availableWidths: { + 240: 'small', + 320: 'medium', + 640: 'large' + } +}); +``` + +`Function`: must return a value for the provided width argument + +```js +// will return a double sized image width as a numeric value +new Imager({ + availableWidths: function (image) { + return image.clientWidth * 2; + } +}); +``` + +### `availablePixelRatios` + +An Array which indicates what are the available pixel ratios available for your responsive images. + +These values will be used as replacements for the `{pixel_ratio}` variable in `data-src` placeholders. + +```js +new Imager({ availablePixelRatios: [1, 2] }); +``` + +**Default value**: `[1, 2]` + +### `className` + +A String which indicates what the `className` value will be added on the newly created responsive image. + +```js +new Imager({ className: 'image-replace' }); +``` + +**Default value**: `image-replace` + +### `scrollDelay` + +An Integer value (in milliseconds) to indicate when Imager will check if a scroll has ended. If a scroll has stopped after this delay and the `lazyload` option is `true`, Imager will update the `src` attribute of the relevant images. + +**Default value**: `250` + +```js +new Imager({ scrollDelay: 250 }); +``` + +**Notice**: set the `scrollDelay` value to `0` at your own risk; unless you know what you're doing, setting the value to zero will make the user experience totally janky! (and that would be an odd thing to do as you have chosen to use Imager to improve the user experience) + +### `onResize` + +A Boolean value. If set to `true`, Imager will update the `src` attribute of the relevant images. + +**Default value**: `true` + +```js +new Imager({ onResize: true }); +``` + +### `lazyload` + +An *experimental* Boolean value. If set to `true`, Imager will update the `src` attribute only of visible (and nearly visible) images. + +**Default value**: `false` + +```js +new Imager({ lazyload: true }); +``` + +### `lazyloadOffset` + +A `Number` of extra pixels below the fold taken in account by the lazyloading mechanism. + +**Default value**: `0` + +```js +new Imager({ lazyload: true, lazyloadOffset: 300 }); +``` + +### `onImagesReplaced` + +A callback `Function`. Runs after Imager updates the `src` attribute of all relevant images. + +Its first and unique argument is an `Array` of `HTMLImageElement`, the ones processed by Imager. + +```js +new Imager({ + onImagesReplaced: function(images) { + console.log('the src of all relevant images has been updated'); + } +}); +``` diff --git a/karma.conf.js b/karma.conf.js index acecdce..c882f90 100644 --- a/karma.conf.js +++ b/karma.conf.js @@ -68,13 +68,6 @@ module.exports = function (config) { // enable / disable watching file and executing tests whenever any file changes autoWatch: false, - sauceLabs: { - tunnelIdentifier: process.env.TRAVIS_JOB_NUMBER || null, - accessKey: process.env.SAUCE_ACCESS_KEY, - testName: 'BBC-News/Imager.js', - startConnect: false - }, - browserStack: { project: 'BBC-News/Imager.js', build: process.env.CONTINUOUS_INTEGRATION ? null : ('Local testing - ' + Date.now()) @@ -198,84 +191,6 @@ module.exports = function (config) { browser_version: '7.0', os: 'OS X', os_version: 'Mavericks' - }, - // Saucelabs - SauceIE6: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows XP', - version: '6' - }, - SauceIE7: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows XP', - version: '7' - }, - SauceIE8: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows 7', - version: '8' - }, - SauceIE9: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows 7', - version: '9' - }, - SauceIE10: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows 8', - version: '10' - }, - SauceIE11: { - base: 'SauceLabs', - browserName: 'internet explorer', - platform: 'Windows 8.1', - version: '11' - }, - SauceFirefox: { - base: 'SauceLabs', - browserName: 'firefox', - platform: 'Windows 7', - version: '21' - }, - SauceAndroid: { - base: 'SauceLabs', - browserName: 'android', - platform: 'Linux', - version: '4.0' - }, - SauceiOS7: { - base: 'SauceLabs', - browserName: 'iphone', - platform: 'OS X 10.9', - version: '7.1' - }, - SauceiOS6: { - base: 'SauceLabs', - browserName: 'iphone', - platform: 'OS X 10.8', - version: '6.1' - }, - SauceiOS5: { - base: 'SauceLabs', - browserName: 'iphone', - platform: 'OS X 10.8', - version: '5.1' - }, - SauceiOS4: { - base: 'SauceLabs', - browserName: 'iphone', - platform: 'OS X 10.6', - version: '4.3' - }, - SauceSafari5: { - base: 'SauceLabs', - browserName: 'safari', - platform: 'OS X 10.6' } }, diff --git a/package.json b/package.json index 4f535b8..c544db2 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,6 @@ "karma-ievms": "^0.0.4", "karma-mocha": "^0.1.9", "karma-phantomjs-launcher": "^0.1.4", - "karma-sauce-launcher": "^0.2.10", "karma-sinon": "^1.0.3", "mocha": "^1.17.1", "sinon": "^1.8.1",