Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
Gruntfile.js
apps
browser-sync.config.js
docs
lib
plugins
themes
vendor
webpack.config.js
.gitignore
.jshintrc
README.md
karma.config.js
kss-config.json
package.json
pom.xml
yuidoc.json

README.md

Loom - Front-end

The first section gives some brief instructions for building and running the web-based Weaver up quickly.

The subsequent sections explain this project in much greater detail and are required reading for development of Weavers.

Quickstart

This project is dependent upon node v0.12.

Open a command prompt within the front-end folder and execute the following:

$ npm install
$ npm run build

Now all the files that need to be served by a web server are in front-end/apps/web/dist. You can transfer these files to a remote web server or server from this location.

If you already have Apache HTTPD installed the see the Fronting with Apache HTTPD section in the README.md in the top-level folder.

Alternatively, you can start a simple server including Browsersync from the front-end directory thus:

$ npm start

Project structure

This folder holds the sources for Weaver, the generic UI for Loom. Weaver can be packaged as two separate applications: a web app or a Windows 8 one. Both have a lot of code in common. This led to the following structure:

  • apps: Stores the parts that are specific to each app, mainly a couple of JS files to tune how they start.
  • lib: The common code of the apps is split into two layers, each one provided by a specific library. weft provides a low level API for interacting with Loom (models and common interactions). weaver provides the UI layer that is used to create the apps
  • plugins: Additional functionalities can be added to the apps via a system of plugin.
  • themes: The apps can be styled via themes
  • vendor: Though dependencies are managed via NPM, some 3rd party scripts couldn't be loaded that way. They reside in the vendor folder.

The rest of the folders are configuration for the different build tools used to generate the apps.

What you'll need on your machine to build the project

The bulk of the build is done by Javascript build tools, so you'll need NodeJS and NPM on your machine. Some tasks also use GruntJS to be executed, so you'll need that installed too.

If you plan to build the Windows 8 app, you'll obviously need to be on a Windows machine. You'll also need Visual Studio 2013 or 2015 (having MSBuild.exe installed might be enough, though).

Last, if you intend to deploy the apps on Nexus or make a release, you'll need Maven, just like for the back-end parts. It is just used for coordinating calls to the Javasript tools with the Maven lifecycle, as well as packaging the apps in a suitable format for Maven repositories.

A word about proxies:

NPM doesn't seem to use the HTTP_PROXY (or its lowercase counterpart) environment variables. To configure NPM's proxy, use npm set proxy <your_proxy> for the plain HTTP one and npm set https-proxy <your_https_proxy> for HTTPS.

NPM clones Git repositories when installing some of the dependencies. If your proxy doesn't accept the git:// protocol, you can configure Git to use HTTP(S) instead. For Github repositories (which is essentially where the Git based dependencies are stored), you 'd use: git config --global url.https://github.com.insteadOf git://github.com

Javascript build tools overview

These build tools will get installed as you install the dependencies of the project with npm install.

webpack is the main build tool. It resolves dependencies between JS modules, LESS scripts and other resources. It then compiles them into a unique JS and CSS file (plus an additional one for the theme). karma runs the tests. It takes care of setting up a server to host the test files, starting a PhantomJS instance and actually running the tests. To make sure things work the same way as in the apps, it delegates the "compilation" to webpack browser-sync provides a server to be used when developing. It watches the files generated by webpack and will automatically reload the page when they changes grunt is used to launch the build of the Windows 8 app, as it had a handy plugin for it. It is also used for updating the Windows 8 app version when doing a Maven release.

Only building the apps

If you only need to build the apps, you can use Maven to build both apps in one go. From this folder, you'll first need to install the NPM dependencies with npm install. It didn't seem to play well with Maven, which is why this step has been left out of the Maven lifecycle.

Once the dependencies have been installed, you can build the app with mvn clean install. This will generate the apps artifacts in the target repositories of each app, provided you're on Windows. If you're on another OS, it will only build the Web app.

Developing the apps

If you're developing on the project, it is more efficient to run the Javascript build tools as they provide features for watching your files as they change and running again. They can be run via different NPM scripts.

Unless you're working on something specific to the Windows 8 app, it is faster to develop features or fix bugs in the web app. This saves you the rebuild and reinstallation of the Windows app. Once things look OK on the web side, you can make a final check that the feature/fix works the same in the Windows 8 app.

When working with the web app, you can quickly start all the necessary build tools with:

$ npm run dev

This will launch the browser-sync server to host the files, start webpack so it builds the apps and watches files for changes, and have karma kick off its server so you can debug tests. You'll be able to access:

"Compiling" the JS files

The build script will run webpack under the hood, to "compile" the application. By default, it'll build the 'web' app. You'll need provide it which app you want to build with the --app parameter if you want to build something else (eg. 'windows8'). You can also add plugins with the --with-plugins parameter, using a coma separated list of the plugins you want in your app. Last you'll probably want to add Webpack's --watch flag to make it monitor your files (you can also add any CLI arguments supported by Webpack).

For example, to build the windows8 app with the table and treemap plugin and watch the files:

$ npm run build -- --app windows8 --with-plugins treemap,table --watch

Running a development server

When developing the web app, you'll need a server to host the built project so you can access it in your browser. You can launch a browser-sync server using the start script: npm run start (or just npm start). Once started, your project will be accessible on port 3000.

The server will also watch the files build by Webpack and reload the page whenever they change.

The script can also open a browser for you, using the --open flag (don't forget the -- to separate the script's arguments from NPM's arguments).

As a default, the server will proxy request landing on /loom to the local loom server (http://localhost:9099/loom). The target URL can be changed by setting the LOOM_SERVER environment variable before running the script.

Launching automated tests

Weft and Weaver libraries are tested using a framework called mocha (with some help of chai for the assertions and SinonJS for mocking).

The execution of the tests is managed by the test script (npm run test). Under the hood, it uses Karma to set up a server hosting the tests and run them in a browser (PhantomJS).

By default, the script only runs the tests once, printing the results in the console. Not the most handy for debugging. The --no-single-run flag will have Karma keep the server up (same as before, don't forget the -- to let NPM pass the flag to the script). You can then debug the tests in a browser by accessing http://localhost:9876/debug.html.

Additionally, while the Karma server is up, you can connect additional browsers (eg. Chrome, Firefox, IE) by opening http://localhost:9876. This will allow you to run the tests simultaneously in different environments. Karma will also watch the files used to run the test and re-execute the test once they change. You'll have to reload the debug.html page manually, though.

Adding new tests

Karma will add any file suffixed in .test.js from the lib/weft/test and lib/weaver-lib/test folders. If you need to add new tests files for these libraries, add a new MyClass.test.js at the path corresponding to the class you're testing. For example, if your class is at lib/weft/js/weft/models/MyModel.js, your test should be at lib/weft/test/weft/models/MyModel.js.

If you need to add tests for another part of the project (eg. a plugin), create a test folder with the same karma.test.js file as weft or weaver-lib. Add it to the list of files loaded by Karma in karma.config.js and you're set up for writing new tests.

Building the Windows 8 app

The build script only "compiles" an HTML/JS/CSS application. To finish building the Windows 8 app, you'll need to run another script named msbuild. It will package the app created by the build script into a Windows8 app (make sure you're on a Windows machine, though).

Another option is to open the project in Visual Studio and build/run it from there.