OpenESDH Angular Material

This is an implementation of OpenESDH using Angular.js and Angular Material as a foundation.

Branches

The repository contains both ES5 and ES6 branches that are inherited from the forked Angular Material project. I don't even know what ES5 and ES6 means. We'll probably replace them with branches for testing, etc.

Getting Started

Prerequisites

You will need git to clone the repository. You can get git from http://git-scm.com/.

We also use a number of node.js tools to initialize and test material-start. You must have node.js and its package manager (npm) installed. You can get them from http://nodejs.org/.

Clone material-start

To get you started you can simply clone master branch from the OpenESDH-UI repository and install the dependencies:

NOTE: The master branch contains the traditional, ES5 implementation familiar to Angular developers.

Clone the material-start repository using git:

git clone https://github.com/OpenESDH/OpenESDH-UI.git
cd OpenEDSH-UI

If you just want to start a new project without the material-start commit history then you can do:

git clone --depth=1 https://github.com/OpenESDH/OpenESDH-UI.git <your-project-name>

The depth=1 tells git to only pull down one commit worth of historical data.

Install Dependencies

We have two kinds of dependencies in this project: tools and AngularJS framework code. The tools help us manage and test the application. You need to have both npm and bower installed.

• We get the tools we depend upon via npm, the [node package manager][npm].
• We get the AngularJS code via bower, a [client-side code package manager][bower].

We have preconfigured npm to automatically run bower so we can simply do:

npm install

Behind the scenes this will also call bower install. You should find that you have two new folders in your project.

• node_modules - contains the npm packages for the tools we need
• app/bower_components - contains the AngularJS framework files

Note that the bower_components folder would normally be installed in the root folder but material-start changes this location through the .bowerrc file. Putting it in the app folder makes it easier to serve the files by a web server.

Run End-to-End Tests

To run your e2e tests your should install and configure Protractor and the Selenium WebServer. These are already specified as npm dependencies within package.json. Simply run these terminal commands:

npm update
webdriver-manager update

Your can read more details about Protractor and e2e here: http://angular.github.io/protractor/#/ for more details on Protractor.

1. Start your local HTTP Webserver: live-server or http-server.

cd ./app; live-server;

Note: since live-server is working on port 8080, we configure the protractor.conf.js to use baseUrl: 'http://localhost:8080'

2. In another tab, start a Webdriver instance:

webdriver-manager start

This will start up a Selenium Server and will output a bunch of info logs. Your Protractor test will send requests to this server to control a local browser. You can see information about the status of the server at http://localhost:4444/wd/hub. If you see errors, verify path in e2e-tests/protractor.conf.js for chromeDriver and seleniumServerJar to your local file system.

3. Run your e2e tests using the test script defined in package.json:

npm test

This uses the local Protractor installed at ./node_modules/protractor

Directory Layout

app/                    --> all of the source files for the application
  assets/app.css        --> default stylesheet
  src/           --> all app specific modules
     cases/              --> package for cases features
     ..
  index.html            --> app layout file (the main html template file of the app)
karma.conf.js         --> config file for running unit tests with Karma
e2e-tests/            --> end-to-end tests
  protractor-conf.js    --> Protractor config file
  scenarios.js          --> end-to-end scenarios to be run by Protractor

Updating Angular

Previously we recommended that you merge in changes to angular-seed into your own fork of the project. Now that the AngularJS framework library code and tools are acquired through package managers (npm and bower) you can use these tools instead to update the dependencies.

You can update the tool dependencies by running:

npm update

This will find the latest versions that match the version ranges specified in the package.json file.

You can update the Angular dependencies by running:

bower update

This will find the latest versions that match the version ranges specified in the bower.json file.

Serving the Application Files

While AngularJS is client-side-only technology and it's possible to create AngularJS webapps that don't require a backend server at all, we recommend serving the project files using a local web server during development to avoid issues with security restrictions (sandbox) in browsers. The sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr, etc to function properly when an html page is opened via file:// scheme instead of http://.

Running the App during Development

The app's services depend on a running OpenESDH server being proxied to the path /alfresco.

To that end, Gulp tasks have been added to make this very easy to do.

To install Gulp, run:

$ sudo npm install -g gulp

To run and connect to OpenESDH server on the test.openesdh.dk server, run:

$ gulp

This server always runs the latest builds of the OpenESDH repository develop branch.

To run and connect to a locally running OpenESDH server on localhost:8080, run:

$ gulp local

To run and connect to OpenESDH server on the demo.openesdh.dk server, run:

$ gulp demo

To only build the scripts and css files, for example, if you are deploying to Apache, run:

$ gulp build

Running on Apache

Here is a sample virtual host configuration for Apache 2.4 (on Ubuntu):

<VirtualHost *:80>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/OpenESDH-UI

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

        ProxyPass /alfresco ajp://localhost:8009/alfresco
        ProxyPassReverse /alfresco ajp://localhost:8009/alfresco

        <Location />
                Header merge Cache-Control no-cache

                # Make sure that if it is an XHR request,
                # we don't send back basic authentication header.
                # This is to prevent the browser from displaying a basic auth login dialog.
                # The UI will handle redirecting to a login page.
                Header unset WWW-Authenticate "expr=req('X-Requested-With') == 'XMLHttpRequest' && resp('WWW-Authenticate') =~ /^Basic/"
        </Location>
</VirtualHost>