The examples below are all for client-side only applications. While I don't anticipate the server side components add too much complexity, keep that in mind when venturing outside of the scope of these examples.
There are two ways of getting a Phovea Application up and running:
We will start with cloning an existing application as this will help you understand where all the pieces go and where/how you should write you code when writing your own application.
Examples below use the genealogyVIS application but can be use for any existing Phovea application
There are two ways to set up an existing Phovea App
The first approach (creating a workspace) is particularly useful when developing multiple plugins, as all the projects within the workspace will share a common npm installation and Docker setup.
This approach creates a ''workspace'' which uses Docker and Docker Compose. The workspace setup also creates a PyCharm project.
mkdir workspace
cd workspace
git clone https://github.com/Caleydo/genealogyVIS.git
(and/or) clone any other repos that you will need).yo phovea:workspace
npm install
npm run start:genealogyVIS
http://localhost:8080/
Your directory structure (for one or more projects) will look like this:
workspace --> has the helper/docker files but is not attached to any repo
\- repo1 --> cloned from github
\- repo2 --> cloned from github
If you have several repos in your workspace, you can run:
to update all the repos in your workspace.
$ git clone https://github.com/Caleydo/genealogyVIS.git
$ cd genealogy_vis
$ npm install
$ npm run build
The build process is optional because it is not required in order to run the application (e.g. during testing/development).
The build process itself includes:
npm run start
Unlike npm run build
, npm run start
will just build the application in memory without any tests or code quality checks
Phovea ignores *.js files on commit. since TypeScript is a superset of javascript it's safe to rename *.js to *.ts files. The only thing you have to take care about is the import and export, since each file is a separate module/file.
The need for import and export is because with TypeScript (and ES6 in general) you cannot use the global scope and every file has his own scope. You need to declare what variables and functions should be exported/imported. Follow the links to learn more about export and import.
Now that you have successfully (hopefully) cloned and examined an existing application, you are ready to build your own application!
sudo npm install -g yo github:phovea/generator-phovea
mkdir name_of_new_app
cd name_of_new_app
yo phovea
and follow the prompts.npm install
npm run build
The build step is optional since it is not required for testing/development.
The build process itself includes:
npm start
Here we assume that you want to create a client side app, called myapp
, that speaks to a server side app myapp_server
. Note that plugins must always be lowercase.
sudo npm install -g yo github:phovea/generator-phovea
mkdir myapp_workspace
cd myapp_workspace
Here myapp_workspace
is a name of your choosing. This folder will hold the workspace, and nested within the different plugins.
Create the client side as follows:
mkdir myapp
cd myapp
yo phovea:init-app
and follow the prompts. This initializes a new client app.cd ..
If you have an existing phovea client side app, you can just clone that repository into this directory.
Create the server side as follows:
mkdir myapp_server
cd myapp_server
yo phovea:init-slib
and follow the prompts. The promt asks you for your application's name, put in myapp
. This initializes a new server app.cd ..
Clone and resolve the phovea_server
as follows:
yo phovea:clone phovea_server
and follow the prompts.yo phovea:workspace
If you are developing against the develop
branch (which is very likely), you must also switch the repository to the develop
branch.
yo will resolve all dependencies for you. If you, however, want to also edit things like phovea_core
at the same time, you can just check it out and switch it to the right branch:
yo phovea:clone phovea_core
cd phovea_core
git checkout develop
If you want to change any phovea plugins, you should first create a new feature branch. Don't commit directly to develop or master.
Keep Docker running.
npm install
docker-compose build
Keep Docker running.
docker-compose up -d
npm run start:myapp
Now in the browser check adress http://localhost:8080/
for accessing the app or http://localhost:8080/api/hello_world/
for accessing the API.