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.
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
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
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
These build tools will get installed as you install the dependencies of the project with
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
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
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:
- The app, at http://localhost:3000
- The karma debug page, at http://localhost:9876/debug.html
- The page to connect a browser to karma, at http://localhost:9876
"Compiling" the JS files
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
if you want to build something else (eg. 'windows8').
You can also add plugins with the
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
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
(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
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
Additionally, while the Karma server is up, you can connect additional browsers (eg. Chrome, Firefox, IE)
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
lib/weaver-lib/testfolders. If you need to add new tests files for these libraries, add a new
MyClass.test.jsat 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
If you need to add tests for another part of the project (eg. a plugin), create a test folder with the same
weaver-lib. Add it to the list of files loaded by Karma in
karma.config.jsand you're set up for writing new tests.
Building the Windows 8 app
build script only "compiles" an HTML/JS/CSS application.
To finish building the Windows 8 app, you'll need to run another script named
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.