cvut / fittable

Fittable is new timetable application developed at FIT CTU in Prague. It’s a client-side JavaScript application built on top of the Sirius API, created with an emphasis on modern approach to design and used technology.

Using JavaScript ES6+ code (converting to ES5 using babel) makes fittable ready for new technologies and development trends in JavaScript language.

Installation

Requirements

You will need Node.JS or io.js.

You need npm version 2.11 or newer for package scopes support. You can verify this by running:

npm --version

You can update npm by running:

npm install npm -g

Installing dependencies

To install dependencies, just run:

npm install

Building

We use npm scripts to execute common build tasks. Project uses Webpack under the hood for JS and CSS bundling.

Run the main build task with:

npm run build

This will build full and minified source code, transpiles JS files and copy HTML and image assets.

The resulting build is located in dist/ directory:

• fittable.js is bundle for usage in web browsers (it can be minified depending on build command used),
• js directory contains transpiled code to ES5 for use in other projects,
• index.html is an example project with mock-up data.

Alternatively you can use the following tasks individually:

• npm run build:dev – generates non-minified CSS and JS files
• npm run build:prod – generates production (minified) CSS and JS files
• npm run build:npm – transpiles ES6 source files to ES5 with Babel for consumption by other CommonJS packages,
• npm run build:assets – copies HTML and image files to dist/ directory

Development

Testing

We use tape for unit testing (blue-tape respectively).

Tests are located in src/test.

You can run tests using npm test for plain TAP output, or npm run test:spec for nicer output. There is also an experimental command npm run test:watch to run tests continuously when files change.

Development Server

Run npm start to launch webpack-dev-server with hot reloading.

You can access the running server on http://localhost:8080/

Access Credentials

To access local development instance you need an access token for authentication with backend service (Sirius). The easiest way to get the token is copying oauth_access_token cookie after authorisation with production instance.

Then add following to the .env file (or copy .env.sample in the repository):

OAUTH_ACCESS_TOKEN=<value of oauth_access_token cookie>
OAUTH_USERNAME=<your username>

These variables will be passed as respective cookies by the development server.

See also configuration below.

Configuration

Application behaviour can be controlled via the following environment variables. You can set these variables permanently via .env file, through export in shell or directly when running npm commands. For example:

FITTABLE_SOURCE=sirius npm start

starts a development server using Sirius as a data source.

Environment variables are inlined during build process using Webpack's DefinePlugin, e.g. in the example above, process.env.NODE_ENV gets replaced by "production" in the final bundle, resulting in conditions like "production" === "production" which can be further eliminated through minification.

Configuration Variables

NODE_ENV: When set to production, React debug messages are removed and Redux logging is disabled. Unset by default. Enabled for npm run build:prod (through webpack.production.config.js file).

FITTABLE_SOURCE: Controls which data backend is enabled. Set this to sirius to use actual data from Sirius (requires access credentials). By default, fake data source is used (called faux). Set to sirius for npm run build:prod (through webpack.production.config.js file).

SIRIUS_TARGET: Controls which instance of Sirius should be used for sirius data source By default, staging instance is used. Can be set to production to use production instance, or alternatively the resulting URL can be overriden by global variable (see below). Note that this is currently not set by npm run build:prod, i.e. staging instance is used by default.

SIRIUS_PROXY_PATH: Defines path to the OAuth proxy to access Sirius API, both in development server and production. Set to /api/sirius by default and it is further merged with <base href> in HTML. See below for overriding this in runtime.

OAUTH_ACCESS_TOKEN: Used by development server to set oauth_access_token cookie for Sirius authorisation. See Access Credentials.

OAUTH_USERNAME: Used by development server to set oauth_username cookie. It contains CTU username to load user's personal calendar from Sirius.

OAuth Proxy

Fittable doesn't handle OAuth authorization directly, we use ngx-oauth to handle authorization and token refreshing. It acts as a proxy for the remote API.

The proxy manages following cookies for the client:

• oauth_refresh_token – Long-lived token (in encrypted form) which is used by the proxy to refresh an access token after expiration. As long this token is set, we assume the user is authorized.
• oauth_access_token – Short-lived token to authorize requests to the remote API (passed through by the proxy).
• oauth_username – Username of the associated user, used to bootstrap initial requests.

Proxy needs to be located on SIRIUS_PROXY_PATH. You can override this variable in the generated bundle by setting global variable SIRIUS_PROXY_PATH before bundle initialisation, for example by adding the following to the index.html file (into <head>):

<script>
window.SIRIUS_PROXY_PATH = '/_proxy/api/v1'
</script>

Keep in mind the path is combined with <base href>.