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/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) 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/gulp/media/copy.js b/gulp/media/copy.js index 2669edec..3ee32463 100644 --- a/gulp/media/copy.js +++ b/gulp/media/copy.js @@ -20,6 +20,7 @@ var taskName = 'media:copy', dest: './build/', watch: [ 'source/assets/fonts/**/*', + 'source/assets/js/**/*.js', 'source/assets/media/**/*', 'source/tmp/media/**/*', 'source/preview/assets/media/**/*', @@ -30,6 +31,7 @@ var taskName = 'media:copy', gulp.task(taskName, function() { var changed = require('gulp-changed'), + livereload = require('gulp-livereload'), size = require('gulp-size'); return gulp.src(taskConfig.src, { @@ -39,7 +41,10 @@ gulp.task(taskName, function() { .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/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/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}} diff --git a/source/layouts/layout.hbs b/source/layouts/layout.hbs index 7f9d8467..68074ec6 100644 --- a/source/layouts/layout.hbs +++ b/source/layouts/layout.hbs @@ -3,39 +3,47 @@ - - - - {{#if title}}{{title}} – {{/if}}{{meta.project}} - - - - - {{#if env.dev}} - - {{/if}} - - - - {{#if env.dev}} - - {{/if}} - - - {{#block "header"}} - {{/block}} - -
    - {{#block "content"}} - {{/block}} -
    + + + + {{#if title}}{{title}} – {{/if}}{{meta.project}} + + + - + {{#if env.dev}} + + {{/if}} - {{#block "scripts"}} - {{#if meta.testScripts}} - {{> "preview/partials/qunit"}} + {{#if env.local}} + {{> "partials/local" }} {{/if}} - {{/block}} - + + {{#if env.acceptance}} + {{> "partials/acceptance" }} + {{/if}} + + + + {{#if env.dev}} + + {{/if}} + + + {{#block "header"}} + {{/block}} + +
    + {{#block "content"}} + {{/block}} +
    + + + + {{#block "scripts"}} + {{#if meta.testScripts}} + {{> "preview/partials/qunit"}} + {{/if}} + {{/block}} + 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}} 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}}