Structure

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

index.html

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.

/public/index.html

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.

/public/style/main.css

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

/public/style/icons/favicon.ico

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

/public/style/icons/apple-touch-icon-precomposed.png

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

/public/manifest.webapp

Webapp definition file that currently supported from Firefox, Firefox Mobile for Android, and Firefox OS https://developer.mozilla.org/en-US/docs/Apps/Manifest

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.

/public/js/app_installer.js

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.

helper/install.html

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

/public/manifest.json

Manifest definition file that currently supported from Chrome Desktop. http://developer.chrome.com/apps/manifest.html

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

/public/js/background.js

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 https://developer.mozilla.org/en-US/Apps/Developing/Porting_Chrome_apps_to_open_web_apps


3. Offline support

The structure:

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

/public/manifest.appcache

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.

/public/fallback.html

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

/public/js/fallback.js

Referenced in public/js/fallback.js.

/public/js/service-worker.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

/public/locale

contain locale translation files.

/public/locales/locales.{lang}.l20n

locale files

/public/manifest.webapp

define how to organize locale files in app manifest format https://github.com/l20n/l20n.js/blob/master/docs/html.md the manifest is referenced by index.html.

/public/vendor/l20n/l20n.min.js

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


5. Cordova support

The structure:

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

config.xml

The config.xml file is [http://cordova.apache.org/docs/en/5.0.0/config_ref_index.md.html#The%20config.xml%20File defined] for cordova app.

www/

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

/public/test

contain unit test and integration test cases.

/public/test/index.html

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

/public/test/unit

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

/public/test/integration

The place to put integration test cases.

/public/test/vendor

Include 3rd-party browser test utilities.

karma.conf.js

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

/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.

.csslintrc

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

.eslintrc

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

Mapping rules defined in Gaia project.

.eslintignore

.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

gulpfile.js

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.

helper/install.html

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

server.js

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.

browse

http://localhost:8000

will bring you to /index.html

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

config.js

The central place for server side configurations.

/views

Server side templates are defined here.

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

/views/index.html

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

/views/main.html

define basic syntax of dynamic page.

/routes

The handler of each url path.

package.json

Inherit the node package modules (npm) tool.

To fetch dependent packages, enter the webapplate folder and run

$ npm install

/public

Place to host static files.