Prerequisites

Phovea is built on a range of standard technologies: Contributors to Phovea should be familiar with the tools we're already using.

• Understanding what's already in place may save you from reinventing the wheel, or adding an extra wheel.
• Understanding the idioms of the tool you're working with will make your code more clear to future developers.

Technologies and Tools used in Phovea

Programming Languages

Client

• TypeScript 2
• SASS

Server

• Python

Frameworks / Libraries

Phovea Generator

• yeoman

Client

• D3
• Font Awesome
• Bootstrap 3
• Jasmine for testing
• Now and then: LineUp.js, Papa Parse, jQuery select2, moment, lodash, ...

Server

• flask
• pytest for testing
• Now and then: numpy, pandas, Requests, Celery, LDAP, ...

Data Stores

• Redis
• MongoDB
• Hierarchical Data Format (HDF)
• SQLAlchemy -> PostgreSQL, SQlite, MySQL
• Neo4j

Build Tools

• Webpack 2
• Karma Test Runner
• pytest runner
• Python setuptools
• Travis CI

Version Control

All source code and documentation for Phovea is hosted on Github. Projects built with Phovea as part of the Caleydo project can be found in the distinct Caleydo organization on Github.

If you haven't used git itself before, please read through this tutorial, or try this interactive one.

To make contributions, please make sure you're up to date, and then branch from master. When you're done, make a pull request (PR) for your branch on Github. As the project develops we will used tagged releases, following semantic versioning conventions, but that is not necessary for every merge.

Documentation

Each Phoveo repo has a brief README, but documentation of the over-all project can be found here, as you've already discovered. The source code for the documentation is itself available on github.

READMEs, this documentation, and Github issue reports all use Markdown. Although HTML can be used within Markdown, it is usually not a good idea.

Packaging

We are using NPM's package.json to manage dependencies between components and external (web) libraries. Phovea plugins can be published to the NPM registry. Note, however, that we are not using the Node.js language.

New projects can be created with the Phovea Generator that is a Yeoman generators. See our cheatsheet for more details.

Server

Server-side plugins use the Python Flask framework. However, if these plugins register namespaces any WSGI compliant Python framework could be used.

Client

Client-side code is written in TypeScript and then compiled down to Javascript. TypeScript adds a typesystem to Javascript, and also lets you use features of the newest versions of the ECMAScript even on older browsers. As part of the build process, multiple libraries and assets are combined using Webpack.

The visualizations in Phovea are created (mostly) with D3.

JavaScript Promises are used throughout Phovea. The main idea of Promises is that asynchronous processes can be handled in code that can still be read lineary. At some points in Phovea a Promise is returned even is a value is immediately available, because we wanted to accomodate instances where a query to the server might actually be necessary.

Testing

When you push changes to Github, tests can automatically be run with Travis. If you have a new project, two things are necessary:

• Enable the tests by flipping the switch for your repo on https://travis-ci.org/profile/phovea, or the appropriate list for your organization. (Click the "resync" button if it is not on the list at first.)
• Add a travis.yml to indicate what tests should be run.

Any program or script that can return either a zero (success) or non-zero (failure) status can be part of your tests, but typically unit tests will be written with Jasmine and run with the Karma test runner.