From 0a11b7612012af851c04388e5c99afe6fbeac419 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Thu, 16 Mar 2017 17:39:16 +0100 Subject: [PATCH 1/6] Add un-webpacked JS configuration files --- docs/Setup_and_Usage.md | 6 +++ gulp/media/copy.js | 22 ++++++-- source/assets/js/configs/acceptance.js | 9 ++++ source/assets/js/configs/local.js | 9 ++++ source/assets/js/head.js | 13 +++-- source/assets/js/helpers/fontloader.js | 4 +- source/layouts/layout.hbs | 72 ++++++++++++++------------ 7 files changed, 92 insertions(+), 43 deletions(-) create mode 100644 source/assets/js/configs/acceptance.js create mode 100644 source/assets/js/configs/local.js diff --git a/docs/Setup_and_Usage.md b/docs/Setup_and_Usage.md index 6ae7278b..ec5d8827 100644 --- a/docs/Setup_and_Usage.md +++ b/docs/Setup_and_Usage.md @@ -57,6 +57,12 @@ npm start # dev flag makes sure the server and watcher don't crash on error ``` +Start server with an specific configuration, either `local` or `acceptance`: + +```shell +npm start -- --local +``` + Build: ```shell diff --git a/gulp/media/copy.js b/gulp/media/copy.js index a003a093..8b2894a2 100644 --- a/gulp/media/copy.js +++ b/gulp/media/copy.js @@ -5,7 +5,8 @@ * @desc Copy specific media files to build directory. */ -var gulp = require('gulp'); +var gulp = require('gulp'), + util = require('gulp-util'); var taskName = 'media:copy', taskConfig = { @@ -17,9 +18,14 @@ var taskName = 'media:copy', './source/modules/**/media/*', './source/demo/modules/**/media/*' ], + configsSrc: [ + './source/assets/js/configs/local.js', + './source/assets/js/configs/acceptance.js', + ], dest: './build/', watch: [ 'source/assets/fonts/**/*', + 'source/assets/js/**/*.js', 'source/assets/media/**/*', 'source/tmp/media/**/*', 'source/preview/assets/media/**/*', @@ -30,16 +36,24 @@ var taskName = 'media:copy', gulp.task(taskName, function() { var changed = require('gulp-changed'), - size = require('gulp-size'); + livereload = require('gulp-livereload'), + size = require('gulp-size'), + + src = util.env.local || util.env.acceptance ? + taskConfig.src.concat(taskConfig.configsSrc) : + taskConfig.src; - return gulp.src(taskConfig.src, { + return gulp.src(src, { base: './source/' }) .pipe(changed(taskConfig.dest)) .pipe(size({ title: taskName })) - .pipe(gulp.dest(taskConfig.dest)); + .pipe(gulp.dest(taskConfig.dest)) + .on('finish', function() { + livereload.reload(); + }); }); module.exports = { diff --git a/source/assets/js/configs/acceptance.js b/source/assets/js/configs/acceptance.js new file mode 100644 index 00000000..d40b6928 --- /dev/null +++ b/source/assets/js/configs/acceptance.js @@ -0,0 +1,9 @@ +/** + * Estatico configuration for acceptance instance + * ============================================================================= + */ + +window.estatico = window.estatico || {}; +window.estatico.options = { + fontLoaderUrl: '/whatever/folder/to/fonts.css?v1' +}; diff --git a/source/assets/js/configs/local.js b/source/assets/js/configs/local.js new file mode 100644 index 00000000..ab4b89c2 --- /dev/null +++ b/source/assets/js/configs/local.js @@ -0,0 +1,9 @@ +/** + * Estatico configuration for local development + * ============================================================================= + */ + +window.estatico = window.estatico || {}; +window.estatico.options = { + fontLoaderUrl: '/assets/css/fonts.css?v6' +}; diff --git a/source/assets/js/head.js b/source/assets/js/head.js index af533289..2ca216cd 100644 --- a/source/assets/js/head.js +++ b/source/assets/js/head.js @@ -3,9 +3,12 @@ import '../.tmp/modernizr'; import FontLoader from './helpers/fontloader'; import Helper from './helpers/helper'; -window.estatico = { +window.estatico = window.estatico || {}; +window.estatico.helpers = new Helper(); + +window.estatico = estatico.helpers.extend({ data: {}, // Content data - options: {}, // Module options - fontLoader: new FontLoader(), - helpers: new Helper() -}; + options: {} // Module options +}, window.estatico); + +window.estatico.fontLoader = new FontLoader(window.estatico.options.fontLoaderUrl); diff --git a/source/assets/js/helpers/fontloader.js b/source/assets/js/helpers/fontloader.js index d7c85cc4..ba0ebddb 100644 --- a/source/assets/js/helpers/fontloader.js +++ b/source/assets/js/helpers/fontloader.js @@ -11,10 +11,8 @@ class FontLoader extends Helper { this.cssHref = href; if (this._fileIsCached()) { - this.logger('just use the cached version'); this.injectFontsStylesheet(); } else { - this.logger('don\'t block the loading of the page; wait until it\'s done; then download fonts'); this.on(window, 'load', this.injectFontsStylesheet.bind(this)); } } @@ -22,8 +20,10 @@ class FontLoader extends Helper { injectFontsStylesheet() { if (this._supportsLocalStorageAndXHR()) { if (this._cacheIsValid(this.cssHref)) { + this.logger('just use the cached version'); this._injectRawStyle(localStorage.fontCssCache); } else { + this.logger('don\'t block the loading of the page; wait until it\'s done; then download fonts'); this._fetchAndStoreStylesheet(); } } else { diff --git a/source/layouts/layout.hbs b/source/layouts/layout.hbs index c69a87e7..8a4a9e6b 100644 --- a/source/layouts/layout.hbs +++ b/source/layouts/layout.hbs @@ -3,39 +3,47 @@ - - - - {{#if title}}{{title}} – {{/if}}{{project}} - - - - - {{#if env.dev}} - - {{/if}} - - - - {{#if env.dev}} - - {{/if}} - - - {{#block "header"}} - {{/block}} - -
- {{#block "content"}} - {{/block}} -
+ + + + {{#if title}}{{title}} – {{/if}}{{project}} + + + - + {{#if env.dev}} + + {{/if}} - {{#block "scripts"}} - {{#if meta.testScripts}} - {{> "preview/partials/qunit"}} + {{#if env.local}} + {{/if}} - {{/block}} - + + {{#if env.acceptance}} + + {{/if}} + + + + {{#if env.dev}} + + {{/if}} + + + {{#block "header"}} + {{/block}} + +
+ {{#block "content"}} + {{/block}} +
+ + + + {{#block "scripts"}} + {{#if meta.testScripts}} + {{> "preview/partials/qunit"}} + {{/if}} + {{/block}} + From de1047bb4363131042da75e41c8c6a9cc838747c Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 17 Mar 2017 13:34:40 +0100 Subject: [PATCH 2/6] Add documentation --- docs/frontend_architecture.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/frontend_architecture.md diff --git a/docs/frontend_architecture.md b/docs/frontend_architecture.md new file mode 100644 index 00000000..750cab29 --- /dev/null +++ b/docs/frontend_architecture.md @@ -0,0 +1,28 @@ +# Frontend architecture + +## Configure Estático JS + +Estático offers an unprocessed (by Webpack) JS file that sets the global _**`estatico`**_ object in the _**``**_ of the document. + +This option is dependant on a flag that has to be provided when executing gulp. Depending on the flag different configuration files can be loaded: + +- _**`–-local`**_: it will load _**`/assets/js/configs/local.js`**_ +- _**`--acceptance`**_: it will load _**`/assets/js/configs/local.js`**_ + +This split is useful when needing different configurations or data depending on the environment where the build will be hosted. For instance: + +- We may want to work with a database or an specific set of configurations when developing locally, so we add the needed configuration in _**`/assets/js/configs/local.js`**_ and run _**`npm start -- --local`**_ to develop +- We may want to build static assets for a simple preview server, for which no configuration would be needed, so we run _**`npm run build`**_ to generate the build without any extra configuration +- Finally we want to build static assets for an "acceptance" server that will require of a different database or a different set of configurations, so we run _**`npm run build -- --acceptance`**_ to generate the build that will include the _**`/assets/js/configs/acceptance.js`**_ file. + +To change or manage which file(s) can be loaded depending on a flag you can have a look at the [layout.hbs](http://latest.concorel.fe-preview.unic.com/layouts/layout.html) + +## Fonts loading + +Estático loads fonts using a deferred font loading logic: asynchronously and storing them in localStorage as caching mechanism to improve load times. The result is a single download of the needed fonts the first time the page is visited. Subsequent visits will use the cached fonts. + +To achieve this, we encode the fonts in base64 and save them all in _**`/assets/css/fonts.css`**_. Then, with JS it is checked if the file has been cached or not, and finally loaded only if needed. + +There is a validation mechanism in place to invalidate the cache: **the path and filename of the css**. We can add as many arguments the the filename as wanted to control this: so instead of requiring _**`/assets/css/fonts.css`**_ we can require _**`/assets/css/fonts.css?v=1`**_. Whenever we need to update fonts, we can update the _**`fonts.css`**_ file and update its call to _**`/assets/css/fonts.css?v=2`**_, which will invalidate the cache ind trigger a new download. + +To specify the load path you can use a [configuration file](#configure-estatico-js) From 7c497a50348f9c874ba491b19fa23cb6672ffd83 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Tue, 9 May 2017 11:16:32 +0200 Subject: [PATCH 3/6] Make JS configuration files HBS partials to avoid an extra HTTP call --- gulp/html/default.js | 2 ++ source/assets/js/configs/acceptance.js | 9 --------- source/assets/js/configs/local.js | 9 --------- source/layouts/layout.hbs | 4 ++-- source/partials/acceptance.hbs | 11 +++++++++++ source/partials/local.hbs | 11 +++++++++++ source/preview/layouts/module.hbs | 8 ++++++++ 7 files changed, 34 insertions(+), 20 deletions(-) delete mode 100644 source/assets/js/configs/acceptance.js delete mode 100644 source/assets/js/configs/local.js create mode 100644 source/partials/acceptance.hbs create mode 100644 source/partials/local.hbs diff --git a/gulp/html/default.js b/gulp/html/default.js index ebf0214c..35cd60f2 100644 --- a/gulp/html/default.js +++ b/gulp/html/default.js @@ -22,6 +22,7 @@ var taskName = 'html', srcModulePreview: './source/preview/layouts/module.hbs', partials: [ 'source/layouts/*.hbs', + 'source/partials/**/*.hbs', 'source/modules/**/*.hbs', 'source/demo/modules/**/*.hbs', 'source/preview/**/*.hbs' @@ -31,6 +32,7 @@ var taskName = 'html', watch: [ 'source/*.hbs', 'source/layouts/*.hbs', + 'source/partials/**/*.hbs', 'source/pages/**/*.hbs', 'source/demo/pages/**/*.hbs', 'source/modules/**/*.hbs', diff --git a/source/assets/js/configs/acceptance.js b/source/assets/js/configs/acceptance.js deleted file mode 100644 index d40b6928..00000000 --- a/source/assets/js/configs/acceptance.js +++ /dev/null @@ -1,9 +0,0 @@ -/** - * Estatico configuration for acceptance instance - * ============================================================================= - */ - -window.estatico = window.estatico || {}; -window.estatico.options = { - fontLoaderUrl: '/whatever/folder/to/fonts.css?v1' -}; diff --git a/source/assets/js/configs/local.js b/source/assets/js/configs/local.js deleted file mode 100644 index ab4b89c2..00000000 --- a/source/assets/js/configs/local.js +++ /dev/null @@ -1,9 +0,0 @@ -/** - * Estatico configuration for local development - * ============================================================================= - */ - -window.estatico = window.estatico || {}; -window.estatico.options = { - fontLoaderUrl: '/assets/css/fonts.css?v6' -}; diff --git a/source/layouts/layout.hbs b/source/layouts/layout.hbs index ca2e14b7..68074ec6 100644 --- a/source/layouts/layout.hbs +++ b/source/layouts/layout.hbs @@ -16,11 +16,11 @@ {{/if}} {{#if env.local}} - + {{> "partials/local" }} {{/if}} {{#if env.acceptance}} - + {{> "partials/acceptance" }} {{/if}} diff --git a/source/partials/acceptance.hbs b/source/partials/acceptance.hbs new file mode 100644 index 00000000..df3829de --- /dev/null +++ b/source/partials/acceptance.hbs @@ -0,0 +1,11 @@ + diff --git a/source/partials/local.hbs b/source/partials/local.hbs new file mode 100644 index 00000000..744817a8 --- /dev/null +++ b/source/partials/local.hbs @@ -0,0 +1,11 @@ + diff --git a/source/preview/layouts/module.hbs b/source/preview/layouts/module.hbs index 6bd88cce..ade0a081 100644 --- a/source/preview/layouts/module.hbs +++ b/source/preview/layouts/module.hbs @@ -16,6 +16,14 @@ {{/if}} + {{#if env.local}} + {{> "partials/local" }} + {{/if}} + + {{#if env.acceptance}} + {{> "partials/acceptance" }} + {{/if}} + {{#if env.dev}} From a42935384b96c30c8978474474c9c5e3dd4df3df Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Tue, 9 May 2017 11:20:38 +0200 Subject: [PATCH 4/6] Update reference in web fonts.hbs --- source/preview/styleguide/webfonts.hbs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/preview/styleguide/webfonts.hbs b/source/preview/styleguide/webfonts.hbs index 1b2c9997..8b96828a 100644 --- a/source/preview/styleguide/webfonts.hbs +++ b/source/preview/styleguide/webfonts.hbs @@ -8,7 +8,7 @@ In case of different sizes for each weight, they can be defined in separate obje {{#extend "preview/layouts/layout"}} {{#content "content"}}
- Warning: By default, the font loader assumes to find a /assets/css/fonts.css file. This can be configured as a parameter of the FontLoader instance in head.js. The result is that this currently fails on our GitHub pages, e.g., where the whole build is in a subdirectory. Subsequently, the request to the CSS file will result in a 404 and Roboto will not be loaded. + Warning: By default, the font loader assumes to find a /assets/css/fonts.css file. This can be configured as a parameter of the FontLoader instance in head.js or in the inline configuration script tag in the head of the page. The result is that this currently fails on our GitHub pages, e.g., where the whole build is in a subdirectory. Subsequently, the request to the CSS file will result in a 404 and Roboto will not be loaded.
{{#each fonts}} From 07300bafdd6ec4025a6b61294db4de63a233ad61 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Tue, 9 May 2017 11:30:16 +0200 Subject: [PATCH 5/6] Revert changes in copy task --- gulp/media/copy.js | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/gulp/media/copy.js b/gulp/media/copy.js index 61aa2c8e..3ee32463 100644 --- a/gulp/media/copy.js +++ b/gulp/media/copy.js @@ -5,8 +5,7 @@ * @desc Copy specific media files to build directory. */ -var gulp = require('gulp'), - util = require('gulp-util'); +var gulp = require('gulp'); var taskName = 'media:copy', taskConfig = { @@ -18,10 +17,6 @@ var taskName = 'media:copy', './source/modules/*/media/**/*', './source/demo/modules/*/media/**/*' ], - configsSrc: [ - './source/assets/js/configs/local.js', - './source/assets/js/configs/acceptance.js', - ], dest: './build/', watch: [ 'source/assets/fonts/**/*', @@ -37,13 +32,9 @@ var taskName = 'media:copy', gulp.task(taskName, function() { var changed = require('gulp-changed'), livereload = require('gulp-livereload'), - size = require('gulp-size'), - - src = util.env.local || util.env.acceptance ? - taskConfig.src.concat(taskConfig.configsSrc) : - taskConfig.src; + size = require('gulp-size'); - return gulp.src(src, { + return gulp.src(taskConfig.src, { base: './source/' }) .pipe(changed(taskConfig.dest)) From 8e634bef31f109a3d718872548757ef574a4ce59 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Tue, 9 May 2017 11:42:34 +0200 Subject: [PATCH 6/6] Fix indentation --- source/index.hbs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/index.hbs b/source/index.hbs index c7936c24..afa94a31 100644 --- a/source/index.hbs +++ b/source/index.hbs @@ -11,7 +11,7 @@
  • {{meta.title}} {{#if meta.jira}} - ( + ( {{meta.jira}} ) {{/if}} @@ -35,7 +35,7 @@ {{meta.title}} {{#if meta.jira}} - ( + ( {{meta.jira}} ) {{/if}}