gasolin edited this page Jun 7, 2015 · 55 revisions

The structure

Webapplate denotes webapp template. Provide 'holographic' templates that suit for both offline and server hosting webapp development. Webapplate also contains some help tools that save your time.

1. Static webapp (Client-side) support

The structure:

webapplate /
 ├── index.html
 └── public
     ├── index.html
     ├── manifest.appcache
     ├── fallback.html
     ├── js 
     │   ├── main.js
     │   └── fallback.js
     ├── style
     │   ├── main.css
     │   ├── images
     │   └── icons
     │       ├── favicon.ico
     │       ├── icon128.png
     │       └── apple-touch-icon-precomposed.png
     ├── locale
     │   ├── manifest.json
     │   └── locale.{lang}.l20n
     └──  vendor


Is used for offline or non-dynamic webapp. The default setting will redirect page to /public/index.html. Comment the meta tag can stop the redirection.

Basic App structure (/public)

The structure follows Firefox OS gaia webapp file structure.


The main entrypoint of webapplate based on Mobile Boilerplate. It contains many best practices and support webapp-installer script. Here is the detail Template Syntax Explanation.


Referenced in public/index.html. Some best practice for styles.


Referenced in public/index.html. check Syntax for detail.


Referenced in public/index.html. check Syntax for detail.

  1. WebApp support

Currently support Firefox WebApp and Chrome App

2.1 Firefox WebApp support

The structure:

webapplate /
 ├── helper
 │   └── install.html
 └── public
     ├── manifest.webapp 
     ├── js 
     │   └── app_installer.js
     └── style
         └── icons
             └── icon128.png


Webapp definition file that currently supported from Firefox, Firefox Mobile for Android, and Firefox OS

We can use manifest validator to check if the syntax is valid.

(deprecated) We could use command grunt f2c to convert from manifest.webapp to Chrome compatible manifest.json file.


Referenced in public/index.html. The file is a script to detect if is this webapp is installed. And will pop a dialog if the webapp is not installed yet.


If you are designing packaged app but want to test it on real device without USB connection. You could use gulp pack command to package the webapp, then open a web server to host download page in dist/ folder.

2.2 Chrome Apps support

The structure:

webapplate /
 └── public
     ├── manifest.json 
     ├── js 
     │   └── background.js
     └── style
         └── icons
             └── icon128.png


Manifest definition file that currently supported from Chrome Desktop.

(deprecated) We could use command grunt c2f to convert from manifest.json to Firefox compatible manifest.webapp file.


The file is a script to specify the initial window size of Chrome Apps.

The difference and common part between chrome app and Firefox webapp could be referred to

3. Offline support

The structure:

webapplate /
 └── public
     ├── index.html
     ├── manifest.appcache
     ├── fallback.html
     └── js 
         ├── service-worker.js
         └── fallback.js


Referenced in public/index.html. (deprecated) The file is used for offline cache, can be auto generated by grunt command grunt manifest. We recommend try service worker instead.


Referenced in public/manifest.appcache. Show when network not available.


Referenced in public/js/fallback.js.


New service worker could manage offline cache and push notifications.

4. Multiple Language Support Framework

The structure:

webapplate /
 └── public
     ├── index.html
     ├── manifest.webapp
     ├── locales
     │   └── locales.xx.l10n
     └── vendor
         └── l20n/l20n.min.js


contain locale translation files.


locale files


define how to organize locale files in app manifest format the manifest is referenced by index.html.


l20n.js library. Need run bower install first to fetch the library.

5. Cordova support

The structure:

webapplate /
 ├── config.xml
 └── www (generated)


The config.xml file is [ defined] for cordova app.


the cordova required www/ folder could be generated by gulp cordova command.

5. Test Framework

The structure:

webapplate /
 ├── karma.conf.js
 └── public
     └── test
         ├── index.html
         ├── integration
         ├── unit
         └── vendor


contain unit test and integration test cases.


The mainpage to run the client-side test. We have to manually include files in /public/test/unit folder to this file for test.


The place to put unit test cases. Use the name convention public/test/unit/<name>_test.js correspondent to public/js/<name>.js


The place to put integration test cases.


Include 3rd-party browser test utilities.


karma configurations. You could change browsers property to test your webapp on target browser.

Here is the general test guide with webapplate.

6. Quality and Style check (Lint)

The structure:

webapplate /
 ├── .csslintrc
 ├── .eslintrc
 ├── .eslintignore
 └── docs
     ├── index.html
     └── report


/docs folder is generated by gulp docs command, which include

  • jsdoc (in index.html)

The command also runs eslint, csslint and sloc for code style check and line of code report.


Mapping rules defined in Gaia project. check rules in CSS wiki


.eslintrc is used to set default eshint Code quality checker rules.

Mapping rules defined in Gaia project.


.eslintignore pre-defined some external file folders that should not be checked.

7. Help tools

You can ignore help tools. But they are useful and save your time.

The structure:

webapplate /
 ├── gulpfile.js
 ├── .bowerrc
 ├── bower.json
 └── helper
    └── install.html


Currently gulpfile handles all webapplate build process.

The test result will be reported on console.

To export static website, run

$ gulp static

The static webpage will generated to dist/ folder. And test/ folder will not be included in the export website.

To export packaged webapp, run

$ gulp pack

You could learn Packaged App in MDN for detail.

You should remove the appcache_path in manifest.webapp to get manifest validator pass.


The helper/install.html will be copied to dist/ for local install packaged webapp.

bower.json / .bowerrc (optional)

bower use bower.json to manage Javascript libraries.

To manage libraries, config component.json and run

$ bower install

bower will fetch proper libraries to public/vendor folder.

Currently webapplte will default fetch following projects:

8. Dynamic webapp (Server-side) support

The structure:

webapplate /
 ├── server.js
 ├── config.js
 ├── routes
 │   ├── index.js
 │   └── api.js
 ├── views
 │   ├── index.html
 │   └── main.html
 ├── package.json
 └── public


The server script written by node.js and express, which provide grade 'A' speed web server configuration in yslow measurement.

Use command :

node server.js

to start the server with default port 8000.



will bring you to /index.html

server.js also define the controller of server side web pages.


The central place for server side configurations.


Server side templates are defined here.

Default templates use the Django-like template swig syntax. You can change the template support in server.js.


It inherit template from main.html. The default setting will redirect page to /public/index.html. Comment the 'meta' tag can stop the redirection.


define basic syntax of dynamic page.


The handler of each url path.


Inherit the node package modules (npm) tool.

To fetch dependent packages, enter the webapplate folder and run

$ npm install


Place to host static files.