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:
$ 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.