unic · orioltf · Mar 16, 2017 · Mar 17, 2017 · May 8, 2017 · May 9, 2017
diff --git 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
@@ -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 _**`<head />`**_ 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
@@ -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
@@ -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
@@ -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
@@ -11,19 +11,19 @@ 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));
 		}
 	}
 
 	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
@@ -11,7 +11,7 @@
 								<li>
 									<a href="{{meta.previewUrl}}">{{meta.title}}</a>
 									{{#if meta.jira}}
-                                        (<a href="#{{meta.jira}}">
+										(<a href="#{{meta.jira}}">
 											{{meta.jira}}
 										</a>)
 									{{/if}}
@@ -35,7 +35,7 @@
 										{{meta.title}}
 									</a>
 									{{#if meta.jira}}
-                                       (<a href="#{{meta.jira}}">
+									   (<a href="#{{meta.jira}}">
 											{{meta.jira}}
 										</a>)
 									{{/if}}

diff --git a/source/layouts/layout.hbs b/source/layouts/layout.hbs
@@ -3,39 +3,47 @@
 <!--[if IE 8]>         <html lang="en" class="no-js ie8 lte-ie9 lte-ie8">         <![endif]-->
 <!--[if IE 9]>         <html lang="en" class="no-js ie9 lte-ie9">                 <![endif]-->
 <!--[if gt IE 9]><!--> <html lang="en" class="no-js">                         <!--<![endif]-->
-<head>
-	<meta charset="utf-8">
-	<meta http-equiv="X-UA-Compatible" content="IE=edge">
-	<title>{{#if title}}{{title}} – {{/if}}{{meta.project}}</title>
-	<meta name="viewport" content="width=device-width, initial-scale=1">
-
-	<link rel="stylesheet" href="/assets/css/main{{#unless env.dev}}.min{{/unless}}.css">
-
-	{{#if env.dev}}
-		<link rel="stylesheet" href="/assets/css/dev.css">
-	{{/if}}
-
-	<script src="/assets/js/head{{#unless env.dev}}.min{{/unless}}.js"></script>
-
-	{{#if env.dev}}
-		<script src="/assets/js/dev.js"></script>
-	{{/if}}
-</head>
-<body {{#if props.svgSprites}} data-svgsprites-options='{{props.svgSprites}}'{{/if}}>
-	{{#block "header"}}
-	{{/block}}
-
-	<div class="layout_wrapper" id="main">
-		{{#block "content"}}
-		{{/block}}
-	</div>
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<title>{{#if title}}{{title}} – {{/if}}{{meta.project}}</title>
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+
+		<link rel="stylesheet" href="/assets/css/main{{#unless env.dev}}.min{{/unless}}.css">
 
-	<script src="/assets/js/main{{#unless env.dev}}.min{{/unless}}.js"></script>
+		{{#if env.dev}}
+			<link rel="stylesheet" href="/assets/css/dev.css">
+		{{/if}}
 
-	{{#block "scripts"}}
-		{{#if meta.testScripts}}
-			{{> "preview/partials/qunit"}}
+		{{#if env.local}}
+			{{> "partials/local" }}
 		{{/if}}
-	{{/block}}
-</body>
+
+		{{#if env.acceptance}}
+			{{> "partials/acceptance" }}
+		{{/if}}
+
+		<script src="/assets/js/head{{#unless env.dev}}.min{{/unless}}.js"></script>
+
+		{{#if env.dev}}
+			<script src="/assets/js/dev.js"></script>
+		{{/if}}
+	</head>
+	<body {{#if props.svgSprites}} data-svgsprites-options='{{props.svgSprites}}'{{/if}}>
+		{{#block "header"}}
+		{{/block}}
+
+		<div class="layout_wrapper" id="main">
+			{{#block "content"}}
+			{{/block}}
+		</div>
+
+		<script src="/assets/js/main{{#unless env.dev}}.min{{/unless}}.js"></script>
+
+		{{#block "scripts"}}
+			{{#if meta.testScripts}}
+				{{> "preview/partials/qunit"}}
+			{{/if}}
+		{{/block}}
+	</body>
 </html>
diff --git a/source/partials/acceptance.hbs b/source/partials/acceptance.hbs
@@ -0,0 +1,11 @@
+<script type="text/javascript">
+	/**
+	 * Estatico configuration for acceptance instance
+	 * =============================================================================
+	 */
+
+	window.estatico = window.estatico || {};
+	window.estatico.options = {
+		fontLoaderUrl: '/whatever/folder/to/fonts.css?v2'
+	};
+</script>
diff --git a/source/partials/local.hbs b/source/partials/local.hbs
@@ -0,0 +1,11 @@
+<script type="text/javascript">
+	/**
+	 * Estatico configuration for local development
+	 * =============================================================================
+	 */
+
+	window.estatico = window.estatico || {};
+	window.estatico.options = {
+		fontLoaderUrl: '/assets/css/fonts.css?v2'
+	};
+</script>
diff --git a/source/preview/layouts/module.hbs b/source/preview/layouts/module.hbs
@@ -16,6 +16,14 @@
 		<link rel="stylesheet" href="/assets/css/dev.css">
 	{{/if}}
 
+	{{#if env.local}}
+		{{> "partials/local" }}
+	{{/if}}
+
+	{{#if env.acceptance}}
+		{{> "partials/acceptance" }}
+	{{/if}}
+
 	<script src="/assets/js/head{{#unless env.dev}}.min{{/unless}}.js"></script>
 
 	{{#if env.dev}}

diff --git 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"}}
 		<section class="sg_inner_wrapper sg_warning">
-			<strong>Warning:</strong> By default, the font loader assumes to find a <code>/assets/css/fonts.css</code> file. This can be configured as a parameter of the <code>FontLoader</code> instance in <code>head.js</code>. 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.
+			<strong>Warning:</strong> By default, the font loader assumes to find a <code>/assets/css/fonts.css</code> file. This can be configured as a parameter of the <code>FontLoader</code> instance in <code>head.js</code> 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.
 		</section>
 
 		{{#each fonts}}