Welcome to the CORD UX/UI Contribution Guide! Thank you for your interest in contributing to the project. This guide is aimed at those who are interested in contributing to the CORD Project, to improve usability, design and make it look bright and shine.


Introduction

CORD is a complex system composed by a lot of moving parts. Most of them achieve backend functionalities and does not have a user interface.

The component that take of operating CORD and expose a UI is called XOS, and there is where you'll have opportunities to contribute. If you want to have more general information about XOS you can read the guide here.

 

Overview

XOS is Django Application that is able to load Service on demand, and thus to extend the classic Django Admin UI with:

  • New admin pages
  • Custom Javascript driven views

Before starting to contribute to on the UI you should consider reading the User Interface documentation

Why should I contribute to a Networking Project?

Most of the benefits listed in the  Collaboration Guidelines doesn't strictly apply to a Web Developer/Designer as we don't have direct interest in networking, but there are other aspect in that give values in contributing personally to an Open Source project, that are mainly:

  • Extend your knowledge
    • Collaborate with a team of experts on corporate scale project
    • Get used to work with a geographically distrubuted team
    • Work with cutting edge technologies
  • Gain visibility
    • Beeing part of a worldwide community of developers
    • Check in code in a successfull open source project

Setup a UI development environment

 

Requirements

In order to work on the XOS UI you need to have installed on your system:

Getting the code

You may follow this guide to learn more on how to setup Gerrit and submitting code. 

Once you're setup in Gerrit, the project you need to download to get started is service-profile.

Build the environment

Once cloned the service-profile repository you'll find a set of possible configuration for XOS, the one that is tailored to work on the user interface is, obviously, the "frontend" one. It contains all the required files to bootstrap the application with the appropriate settings plus a Vagrant file to setup up the development environment.

To launch XOS execute this commands:

vagrant frontend config
$ cd service-profile/frontend
# boot the Vagrant VM
$ vagrant up
# enter the Vagrant VM
$ vagrant ssh
# start xos
$ cd /opt/service-profile/frontend
$ make
# load CORD related mock data
$ make mock-cord-pod

At this point you should be able to access the UI at 192.168.46.100:9999 (and 9998, see User Interface documentation for the difference)

Note that the build process will create two sibling folder to service-profile. One is called "xos", that will contain all XOS related code, the other is "xos_services", and will contain all service related code. These three folders are shared with the Vagrant VM, and UI related folder inside "xos" are shared with the Docker container that is actually running XOS.

Development Process

Global Views

What we call global views are actually Django Admin templates, they can be found in 

$ cd xos/xos/templates

Custom Views

Custom Views are AngularJs driven single page application that can be loaded on demand in the Django Admin templates.

For more information about Custom Views you can read the Add View section in the XOS guide or look at this video tutorial.

Styles

XOS styling is base on Bootstrap 3 defined in SCSS. All the source files (and a development server) are located in:

$ cd xos/views/style
$ npm start

The "npm start" script will launch a node server on "http://localhost:3000" and should automatically open it in the browser. It will also take care of compiling SCSS files anytime they are saved along with reloading the browser.

External Components

Yeoman Generator

This Yeoman generator is defined to help developers to create and manage custom views. It will create a CORD tailored development environment and it take of publishing your view in XOS.

It will be released as a standalone NPM Module.

ngXosLib

This a UI component library. It is developed using AngularJs, and also if it implements some XOS related logic, it is designed to be as general purpose as possible. You can find the current documentation here and the source code inside the XOS repository.

The plan for the future is to release it as a Bower Component.