From abce49a897d4e77fabd7fa14b1055b1667a60bb8 Mon Sep 17 00:00:00 2001 From: Vivek Munde Date: Thu, 20 Jul 2017 10:14:50 +0530 Subject: [PATCH] documentation --- README.md | 46 +++++++- tests/dummy/app/routes/application.js | 19 +++ tests/dummy/app/routes/index.js | 4 + .../app/templates/application-loading.hbs | 3 + tests/dummy/app/templates/application.hbs | 8 +- tests/dummy/app/templates/index.hbs | 111 ++++++++++++++++++ 6 files changed, 186 insertions(+), 5 deletions(-) create mode 100644 tests/dummy/app/routes/application.js create mode 100644 tests/dummy/app/routes/index.js create mode 100644 tests/dummy/app/templates/application-loading.hbs create mode 100644 tests/dummy/app/templates/index.hbs diff --git a/README.md b/README.md index 1c25d02..90488a1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,48 @@ # ember-m-css-loader -This README outlines the details of collaborating on this Ember addon. +This [Ember.js](https://emberjs.com/) addon helps load the css file(s) on demand, i.e. lazy loading, inside the `` tag in the `document` `` using the service `m-css-loader` . + +### Lazy Loading of CSS + +[CSS are render blocking resources.](https://developers.google.com/web/fundamentals/performance/critical-rendering-path/render-blocking-css) The ambitious SPAs need more than one CSS resources (external libraries) and some of these CSS resources can be more functionality centric and may not be required to get loaded on the Home screen or may be required only for few of screens. + +Suppose a web app uses Maps Library (like [leaflet](https://leafletjs.com)) for displaying maps, which comes with its own CSS. The maps are displayed only on couple of routes other than home screen. So the home screen is not needed to load the CSS for maps. The maps CSS should be loaded when the routes displaying maps are requested. In this scenario, its always preferable to load the CSS dynamically. + +## `.load(attr)` + +The method to load a CSS file on demand. + +`attr` is a JSON object which holds the attribute values for the `` tag to load CSS. It should at least have `href` property set to the source of the CSS. + + mCssLoader: Ember.inject.service('m-css-loader'), + beforeModel() { + this.get('mCssLoader').load({ + href: 'http://cdn-assets/maps.css', + integrity: 'sha384-shfssiufhnof7348f738f7bw8g+Pmsjshdinwe98', + crossorigin: 'anonymous' + }); + } + +#### Promise Based Load + +The service `m-css-loader` returns a promise. The service listens to the events `onload` and `onerror` on the `` tag in which the CSS is loaded. It resolves the promise inside `onload` event and rejects it if `onerror` event is raised. + +Use of this promise is completely optional and upto the requirement of the app. If a route needs to wait until the CSS gets loaded then the service can be used inside the `beforeModel` hook. + + mCssLoader: Ember.inject.service('m-css-loader'), + beforeModel() { + return this.get('mCssLoader').load({ + href: '/assets/maps.css' + }); + } + +#### Caching + +The service `m-css-loader` caches the `href`s loaded to avoid injecting the same CSS more than once. + +#### CORS + +The service inserts a `` tag which as good as having it hardcoded at the time of html load. So no [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) issue. ## Installation @@ -11,7 +53,7 @@ This README outlines the details of collaborating on this Ember addon. ## Running * `ember serve` -* Visit your app at [http://localhost:4200](http://localhost:4200). +* Visit your app at [http://localhost:4200](http://localhost:4200), which loads the [bootstrap](https://getbootstrap.com) CSS lazily. ## Running Tests diff --git a/tests/dummy/app/routes/application.js b/tests/dummy/app/routes/application.js new file mode 100644 index 0000000..40da1b9 --- /dev/null +++ b/tests/dummy/app/routes/application.js @@ -0,0 +1,19 @@ +import Ember from 'ember'; + +export default Ember.Route.extend({ + mCssLoader: Ember.inject.service('m-css-loader'), + beforeModel() { + return Ember.RSVP.hash({ + bootstrap: this.get('mCssLoader').load({ + href: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css', + integrity: 'sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u', + crossorigin: 'anonymous' + }), + bootstrapTheme: this.get('mCssLoader').load({ + href: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap-theme.min.css', + integrity: 'sha384-rHyoN1iRsVXV4nD0JutlnGaslCJuC7uwjduW9SVrLvRYooPp2bWYgmgJQIXwl/Sp', + crossorigin: 'anonymous' + }) + }); + } +}); diff --git a/tests/dummy/app/routes/index.js b/tests/dummy/app/routes/index.js new file mode 100644 index 0000000..26d9f31 --- /dev/null +++ b/tests/dummy/app/routes/index.js @@ -0,0 +1,4 @@ +import Ember from 'ember'; + +export default Ember.Route.extend({ +}); diff --git a/tests/dummy/app/templates/application-loading.hbs b/tests/dummy/app/templates/application-loading.hbs new file mode 100644 index 0000000..346f31e --- /dev/null +++ b/tests/dummy/app/templates/application-loading.hbs @@ -0,0 +1,3 @@ +
+ loading bootstrap css ... +
\ No newline at end of file diff --git a/tests/dummy/app/templates/application.hbs b/tests/dummy/app/templates/application.hbs index f8bc38e..96a3f8f 100644 --- a/tests/dummy/app/templates/application.hbs +++ b/tests/dummy/app/templates/application.hbs @@ -1,3 +1,5 @@ -

Welcome to Ember

- -{{outlet}} +

{{#link-to "index"}}ember-m-css-loader{{/link-to}}

+
+
+ {{outlet}} +
\ No newline at end of file diff --git a/tests/dummy/app/templates/index.hbs b/tests/dummy/app/templates/index.hbs new file mode 100644 index 0000000..3989c29 --- /dev/null +++ b/tests/dummy/app/templates/index.hbs @@ -0,0 +1,111 @@ +

Read Me

+
+
+

This Ember.js addon helps load the css file(s) on demand, i.e. lazy loading, inside + the <link> tag in the document <head> using the service m-css-loader .

+

+ Lazy Loading of CSS

+

CSS are render blocking resources. The ambitious SPAs need more than one CSS resources (external libraries) and some of these CSS resources can be more + functionality centric and may not be required to get loaded on the Home screen or may be required only for few of + screens.

+

Suppose a web app uses Maps Library (like leaflet) for displaying maps, which comes + with its own CSS. The maps are displayed only on couple of routes other than home screen. So the home screen is not + needed to load the CSS for maps. The maps CSS should be loaded when the routes displaying maps are requested. In + this scenario, its always preferable to load the CSS dynamically.

+

+ .load(attr)

+

The method to load a CSS file on demand.

+

attr is a JSON object which holds the attribute values for the <link> tag to load CSS. + It should at least have href property set to the source of the CSS.

+ 
mCssLoader: Ember.inject.service('m-css-loader'), 
+beforeModel() {
+    this.get('mCssLoader').load({
+            href: 'http://cdn-assets/maps.css',
+            integrity: 'sha384-shfssiufhnof7348f738f7bw8g+Pmsjshdinwe98',
+            crossorigin: 'anonymous'
+        });
+}
+
+

+ Promise Based Load

+

The service m-css-loader returns a promise. The service listens to the events onload and onerror on the <link> tag in which the CSS is loaded. It resolves the promise inside onload event and rejects it if onerror event is raised.

+

Use of this promise is completely optional and upto the requirement of the app. If a route needs to wait until the CSS + gets loaded then the service can be used inside the beforeModel hook.

+ 
mCssLoader: Ember.inject.service('m-css-loader'), 
+beforeModel() {
+	return this.get('mCssLoader').load({
+		href: '/assets/maps.css'
+	});
+}
+
+

+ Caching

+

The service m-css-loader caches the hrefs loaded to avoid injecting the same CSS more than + once.

+

+ CORS

+

The service inserts a <link> tag which as good as having it hardcoded at the time of html load. So + no CORS issue.

+

+ Installation

+ +

+ Running

+ +

+ Running Tests

+ +

+ Building

+ +

For more information on using ember-cli, visit https://ember-cli.com/.

+
\ No newline at end of file