Introduction
This post will help with installation of the OCW User Interface (UI).
It also acts as an initial go-to for primitive developers resources. Please see the table of contents for the layout.
Before you Begin
These instructions assume that all the required Python modules are installed on your local machine (PyNIO, PyNCL, Numpy, Requests, etc....).
If you would like to install these modules on your local machine, follow the steps defined in the Easy-RCMET documentation.
User Installation Guide
Installation on Mac OSX
Requirements
A few installations are needed before we get started.
Homebrew
If you don't already have Homebrew installed, you should!
Got to Homebrew's homepage for installation help. The process is very straightforward and shouldn't be too difficult to figure out.
NodeJS
Since you installed Homebrew this step is going to be a breeze!
brew install node
Assuming you installed everything to the default locations, you're also going to have to add the following to your path to make sure the Node Packaged Modules (npm) can be found. Stick the following in your ~/.bashrc file (assuming you run bash of course).
export PATH="/usr/local/share/npm/bin:$PATH"
You should now be able to run the following
node --version npm --version
and get the following output
v0.8.22
1.2.14
Karma
Next we'll install Karma so we can have a fun time running tests! All we need to do here is run this simple command!
npm install -g karma
Test to make sure that everything installed properly with
karma --version
which should give you the following output
Karma version: 0.8.5
Installation on Linux
Requirements
The following instructions assume a Debian-based Linux installation (e.g.: Ubuntu, LinuxMint, etc.).
Install Karma JavaScript Test Runner
Karma provides a comprehensive test framework for JavaScript. It depends on NodeJS, which we will install first:
(sudo) apt-get install node
Now that NodeJS is installed, we can use the Node Package Manager utility (npm) to install Karma:
(sudo) npm install -g karma
Getting Started
Bottle Services
This list of steps assumes that you already have bottle services running.
To start using or working on the UI, run the following snippets. It's assumed that $RCMET_UI_HOME points to the root UI directory that results from pulling the UI code.
cd $RCMET_UI_HOME ./scripts/web-server.js
This will boot up a web server, which will be running the application. Point your browser to http://localhost:8000/app/index.html to see the web application run.
Because we're good developers we will always write tests when we add new components. If we wanted to run all of our unit tests, we would run the following
cd $RCMET_UI_HOME/scripts ./tests.sh
This will boot up instances of whatever browser(s) we have set in the config and run all the tests. You can leave this running (assuming the config is properly set) and it will watch for changes to files and re-run tests whenever it detects a change.
We're currently using the Jasmine Testing Framework for writing our tests. The syntax is very understandable and descriptive. Check out their main page or look through our tests for some simple examples!
Overview
The user interface layout consists of the following directory structure. Each directory is described below.
$CLIMATE_HOME/ocw-ui/frontend
.
├── app
│ ├── ...
├── config
│ ├── ...
├── scripts
│ ├── ...
└── test
├── ...
Browse Github Code
You can also browse the source code here.
App
The app directory contains the actual application code. Nesting of code in this directory conforms to the typical web application layout format
Important Note
One thing that might be slightly confusing is the partials directory.
Snippets of HTML go here. For instance, the code that will be injected into a view when it is instantiated might exist in a partial.
This code can then be swapped with other partials when the browser is pointed to a specific address.
Resource Tip
For more information on view swapping, check out the AngularJS Phone Catalog Tutorial - Step 7.
Currently the development work is being done in index.html as opposed to index-async.html. We can convert over to the async load later if need be.
Config
The config directory contains configuration files (What!?! No way!!) for Karma. Karma is the testing framework that is provided with Angular-Seed which we'll be using for unit and end-to-end testing. The most useful and interesting setting in the config is the "files" label. You can use this to tell Karma which files to load and in what order they should be loaded. By default, the majority of the JS files that we'll be using aren't included. Whenever you add a JS file and you want to test a component, chances are you'll need to add it here!
Logs
Hay, there are logs here!
Scripts
This directory contains useful helper scripts that we'll use for development. The 3 that are of most interest to us are the *.sh scripts. "e2e-test.sh" and "test.sh" are used for running test code. "web-server.js" boots up a web server with Node for local testing.
Test
The two most useful sub-directories under Test are e2e and unit which divide up tests into obvious categories. Unit tests should be broken up based on the type of component that is being tested and placed into the proper JS file.
Developer Resources
The remainder of this document serves as a brief overview of the technologies being used to develop OCW.
Technologies
AngularJS
RCMET-UI is being developed with Angular.js in an attempt to simplify and streamline development. You can read more about Angular.js and discover why it's a great tool at Angular's main website.
While there are a number of useful examples on the main website, you might want to look through a more comprehensive example. The AngularJS Phone Catalog tutorial provides a great walk-through. Additionally, you can look at the Developer Guide which will also link you to the getting started guide and tutorial.
Our codebase for the project was bootstrapped with Angular-Seed which provides an application skeleton for typical AngularJS apps.