Project Ariana

Project ariana - is a web-based image editing solution. We focus on a clean interface usable for both mouse and touchscreens. Our official website is ariana.pictures.

Project progress

User stories

Presentatie draaiboek

Index

• Project structure
• Getting started
  • Requirements
  • Node.js
  • Usage
• Development
  • git workflow
  • HTML styleguide
  • CSS/SASS styleguide
  • JS styleguide
  • Angular.js styleguide

Project structure

At a high level, the structure looks roughly like this:

ariana/
  |- src/
  | |- app/
  | | |- <app logic>
  | | |- renderengine/
  | | |- editengine/
  | | |- drawengine/
  | | |- content/
  | | |- header/
  | | |- layers/
  | | |- toolbox/
  | | |- app.js
  | | |- app.spec.js
  | | |- router.js
  | |- assets/
  | | |- <static files>
  | |- common/
  | | |- <reusable code>
  | |- sass/
  | | |- <style files>
  | | |- main.scss
  | | |- variables.scss
  | | |- other_sass.scss etc.
  | |- third-party
  | | |- <files used from third parties> 
  |- bower.json
  |- build.config.js
  |- Gruntfile.js
  |- package.json
  |- server.js
  |- setup.sh

A brief description of each entry

• src/ - ariana sources
  • app/ - is used for application specific code, e.g. templates and controllers
    • renderengine/ - the renderengine
    • editengine/ - the editengine draws overlays on the canvas for easy editing
    • drawengine/ - the drawengine
  • assets/ - images etc.
  • common/ - all code that is likely to be used by different modules
  • sass/ - all style files
    • main.scss main style file from which all others are included
    • variables.scss put ALL SASS variables here
    • other_sass.scss etc. all other sass files, one file should contain the styling for one "feature"
• bower.json - the list of bower dependencies
• build.config.js - settings for the grunt build system
• Gruntfile.js - grunt build script
• package.json - metadata about ariana, used by NPM
• server.js - a simple node.js server
• setup.sh - an installation script

Getting started

ariana runs on a Node.js server. Installing ariana takes about 3 minutes.

Requirements

• Node.js
• git
• ImageMagick

Node.js

First of all, install Node.js.

After installing Node.js enter the following in your terminal of choice:

$ git clone git@github.com:ArnoldSwaggernegger/ariana.git
$ cd ariana

Now that you have the repository cloned enter

$ sudo npm -g install grunt-cli karma bower
$ npm install
$ bower install
$ grunt watch

• npm install installs all node modules defined in package.json
• bower install installs all dependencies defined in bower.json to a path specified in .bowerrc
• grunt watch tells grunt (build system) to build ariana. The watch parameter lets grunt watch for changes to your files. Grunt will automatically rebuild and recompile when these changes are detected.
  • Grunt serves as a LiveReload server. You can install the LiveReload browser plugin to automatically refresh your browser when grunt rebuilds ariana (this is not necessary, only a comodity).
  • Grunt also minifies and combines javascript, css, etc.

You can also use our installations script, setup.sh, to execute these commands. The script will also check if all dependencies are installed.

Usage

To run ariana enter the following

$ node server.js

This will start a Node.js server on localhost:3000 and serves the build/ folder as main (the build folder is generated by grunt).

Development

ariana is based on Angular.js and WebGL. Please follow the following styleguides to ensure development of ariana goes smoothly.

git workflow

ariana uses git as version control system. When developing ariana refer to the issue tracker to find userstories. When using ariana and git:

• never push directly to master
• work on a new branch for every feature
  • when you are done with your feature send in a pull request to master
  • make sure the pull request can automatically merge
  • give a meaningful description for your pull request
• when fixing an issue refer to the #issue_number in your commit (example: fixes #23 - height of header is now correct).
• always provide a meaningful description with your commit (even when fixing issues).

HTML styleguide

• use double quotation marks <class="classname">, not <class='classname'>
• no spaces between types and attributes <class="classname">, not <class = "classname">
• keep tags lowercase <div>, not <DIV>
• use classes to style elements <class="classname">
• please refrain from using inline styles <style="don't do this">
• indentation is not necessary
• when you need to use indentation, use 4 spaces
• place every element on their own row (not necessary if row is very short)

<p>
text
</p>

• refrain from using a <div> when a <span> is also possible
• Please use opening and closing tags for all elements, <img></img> not <img />

CSS/SASS styleguide

• indentation is 4 spaces
• for connecting classnames use a dash -, not camelCase
• give meaningful names to classes
• please follow the following class and element layout

element { 
    property: value;
    property: value;
    
    .nested_class {
        property: value;
    }
    
    element, .class {
        property: value;
    }
}

• Note that SASS allows for nested class defenitions. However, don't overdo nesting
• stylesheets are split up into modules (widgets, headers, etc.). All variables will be combined into one file. A main file will import every other file.
• when adding a new style, always check if the same defenition already excists in another file.
• refer to the SASS documentation for detials on SASS

JS styleguide

• indentation is 4 spaces
• please use camelCase
• please write /* comment */ for single row comments
• please write

/* comments
 * are
 * great */

for multirow comments

• don't overdo comments, only write them if necessary to understand a section
• begin each file with a header

/*
 * Project Ariana
 * filename
 * 
 * small description of file
 * another line
 *
 */

• statements

if (condition) {
    statements;
}

• functions and modules

var moduleName = angular.module('moduleName', [
    'resource',
    'resource'
]);

angular.module('moduleName').run(['resource',
    function($resource) {
        statement
    }
]);

Angular.js styleguide

• Todo

Testing

For testing, we use Karma, which is based on Jasmine, a behaviour driven JavaScript testing suite. Position your test files next to the controller/directive to be tested and name them something.spec.js, so they will automatically be picked up by Grunt. The tests will be executed everytime the project is build, and you will be unable to finish building when the tests fail.