Adding Dependencies

When you create a plugin or application it is common to use additional Phovea modules or external libraries to avoid re-inventing the wheel again. There are slightly different ways how to add dependencies for the client-side and the server-side.

Adding client-side dependencies

A client-side dependency can be another Phovea module or a JavaScript library available on the npm registry.

Phovea modules and additional libraries

  1. Open the command line and navigate to the plugin directory
  2. Run yo phovea:add-dependency
  3. Select the additional (Phovea) modules that should be included
  4. Confirm your selection with Enter and move the next step
  5. Select additional libraries (e.g., jQuery, D3) that are known by the Phovea framwork
  6. Confirm your selection with Enter
  7. Override files if you will be asked to
  8. (Optional, but recommended: Commit the changes)
  9. Update your setup

Add other external libraries

Follow theses steps only, if you cannot find the library in the known libraries by the Phovea framework (using the Phovea generator in the step above).

  1. Research if the library and the @types (TypeScript typings) are available on npmjs
  2. If yes, continue. If not, ask the library author to publish the library on npmjs.
  3. Open the package.json of the application/plugin repository
  4. Add the library and typings in the corresponding versions to the dependencies section. For example:
"dependencies": {
  "@types/d3": "3.5.36",
  "d3": "3.5.17"
},
  1. (Optional, but recommended: Commit the changes)
  2. Update your setup

Version conflicts with D3 (v3 vs. v4)

Most of the Phovea repositories (e.g., phovea_vis and phovea_clue) use D3 v3. If you want to use code that uses D3 v4 add the specific D3 module (e.g., d3-selection) and the @type dependency (as described above) to the package.json.

"dependencies": {
   "@types/d3-scale": "^1.0.4",
   "d3-scale": "^1.0.3"
},

Note, that you must import the specific D3 v4 modules to your TypeScript file as follows to avoid conflicts with the D3 v3 library:

import {scaleLinear} from 'd3-scale';

Importing a jQuery UI widget

Import a jQuery UI widget, here Sortable, as follows:

  1. Run npm install -save jquery-ui in the plugin directory
  2. Update your setup
  3. Import the widget in TypeScript, as follows:
import * as $ from 'jquery';
import 'jquery-ui/ui/widgets/sortable'; // specify the widget here
import 'style-loader!css-loader!jquery-ui/themes/base/all.css'; // use Webpack CSS loader to import base style for all widgets

Important: Make sure you specified the particular widget and use the style loader in the import statements.


Adding server-side dependencies

A server-side dependency can be another Phovea module or pip package available on PyPI Python Package Index.

Phovea server modules and additional libraries

  1. Open the command line and navigate to the directory of the server library
  2. Run yo phovea:add-dependency
  3. Select the additional (Phovea) modules that should be included
  4. Confirm your selection with Enter and move the next step
  5. Select additional libraries (e.g., MongoDB, Redis) that are known by the Phovea framwork
  6. Confirm your selection with Enter
  7. Override files if you will be asked to
  8. (Optional, but recommended: Commit the changes)
  9. Update your setup

pip dependencies

Follow theses steps only, if you cannot find a suitable Phovea plugin (using the Phovea generator in the step above).

  1. Navigate to the server library directory
  2. Open the requirements.txt
  3. Add the pip dependencies and version (one per line) as follows:
ujson==1.33
enum==0.4.6
  1. (Optional, but recommended: Commit the changes)
  2. Update your setup

NOTE: A bug (addressed here) in the Phovea generator is overriding changes made to the requirements.txt when running yo phovea:update. You have to restore the modifications manually until the bug is fixed.


Update setup / apply changes

Workspace setup

  1. Navigate to the workspace directory
  2. Run yo phovea:workspace to merge the dependencies of all cloned repos in the workspace directory
  3. Override files if you will be asked to
  4. Run docker-compose build for server-side changes
  5. Run npm install for client-side changes

Stand-alone setup

  1. Run npm install to install new npm dependencies