Skip to content

topanat dev

Jump to bottom
smoretti edited this page May 26, 2020 · 1 revision

This page describes how to work on the development of topAnat. Before reading this page, you should read Bgee apps installation and Bgee-webapp documentation. Table of content:

topAnat development

Layout

On the Java side (under BGEE_APPS_HOME/bgee-webapp/src/main/java/):

  • The Page Controller handling the requests related to topAnat is org.bgee.controller.CommandTopAnat. This class analyzes the requests to the server, to launch the appropriate actions on bgee-core, and to select the appropriate view to render the data.
  • The views responsible for rendering topAnat data for generating responses from the server are: org.bgee.view.html.HtmlTopAnatDisplay and org.bgee.view.json.JsonTopAnatDisplay (more could be added, for instance to render some data in TSV).

On the javascript side:

  • the javascript code for topAnat is in BGEE_APPS_HOME/bgee-webapp/src/main/webapp/js/topanat.js. In Eclipse, the js directory appears under Deployed Resources. (Maybe at some point of the development, it might be needed to modify other javascript files from the Bgee webapp, see the Javascript layout of Bgee)

On the css side:

  • the css code for topAnat is in BGEE_APPS_HOME/bgee-webapp/src/main/webapp/css/topanat.css. In Eclipse, the css directory appears under Deployed Resources. (Maybe at some point of the development, it might be needed to modify other CSS files from the Bgee webapp, see the CSS layout) of Bgee)

Access topAnat page on server

  • Some parameters of the Bgee webapp have been modified on the topAnat branch to deploy the webapp to the path topanat-dev (see commit 5a7ff3bd7b24d093515a6e53a17c4a2388f198f0). It means that the test webapp will be accessed through URLs looking like http://host/topanat-dev/ (e.g., http://localhost:8080/topanat-dev/, http://altbgee.unil.ch/topanat-dev/, see deploy the test webapp on localhost and deploy the test webapp on test server).

  • The search part of URLs to access the topAnat pages must include page=top_anat, e.g. http://host/topanat-dev/?page=top_anat.

Development strategy

The directory BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/ has been created to host static HTML, javascript, and css files, before their content is integrated into the Java webapp. See for instance BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/examples/basic_test.html for an example of a static HTML page using the actual javascript and css files of the webapp (and see examples section below). This directory could also store static JSON files used to mock the responses from server to AJAX requests.

The HTML code should be integrated back into the Java class org.bgee.view.html.HtmlTopAnatDisplay when ready. The JSON responses should be integrated into org.bgee.view.json.JsonTopAnatDisplay. The javascript code can be more easily directly integrated into BGEE_APPS_HOME/bgee-webapp/src/main/webapp/js/topanat.js, as well as the CSS code into BGEE_APPS_HOME/bgee-webapp/src/main/webapp/css/topanat.css.

Note: these static files were originally stored in BGEE_APPS_HOME/frontend-dev/, but they were moved into the webapp folder itself, so that they could be shipped directly into the webapp, and accessed through a webserver (useful for deploying and showing these pages on the test server, and also for performing real AJAX queries without browser limitations for AJAX queries through file system, see below).

Static file examples

Note that these static files use the actual topanat.js and topanat.css files of the Bgee webapp, so they will be broken as soon as these files will be edited. Maybe we could copy the first version in the examples directory then.

  • BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/examples/basic_test.html implements a basic AngularJS test, using topanat.js. The only modification is that this static HTML page also imports the JS file static_page_params.js, allowing to change the parameters used by the Bgee javascript functions (see Bgee Javascript layout).

Example to load static HTML pages: this page could be loaded from file system, or from your localhost at http://localhost:8080/topanat-dev/frontend-dev/examples/basic_test.html (see deploy the test webapp on localhost), or from the test server at http://altbgee.unil.ch/topanat-dev/frontend-dev/examples/basic_test.html (see deploy the test webapp on test server).

In static_page_params.js:

//points to the img directory of the Bgee webapp, 
//relative to the examples directory.
GLOBAL_PROPS.setImgPath('../../img/');
//the topAnat test webapp is deployed to the path 'topanat-dev'.
//This setting would not be needed if you were accessing this page from a server, 
//but it is needed to perform AJAX queries from pages loaded from file system.
GLOBAL_PROPS.setWebAppPath('/topanat-dev/');

Added in basic_test.html as compared to regular Bgee files:

<script type='text/javascript' src='static_page_params.js'></script>

(before the import of topanat.js but after the import of common.js)

  • BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/examples/localhost_ajax.html adds a test of an AJAX query made to a Bgee webapp deployed on your localhost (see deploy the test webapp on localhost). The only modification as compared to basic_test.html is to change the host used to perform AJAX queries (see Bgee Javascript layout).

Example to load static HTML pages: this page could be loaded from file system, or from your localhost at http://localhost:8080/topanat-dev/frontend-dev/examples/localhost_ajax.html (see deploy the test webapp on localhost). The AJAX query does not work on the test server, because of the host configuration to use localhost:8080 (see below).

Added in localhost_ajax.html as compared to basic_test.html:

<script>
//this setting would not be needed if the page was accessed 
//through a server on your localhost, but is is needed if you access it 
//from file system. Because of this setting, this page will not work 
//if accessed from a server that is not on your localhost (e.g., test server).
GLOBAL_PROPS.setBgeeHost('localhost:8080');
</script>

Note: many browsers disable the ability to perform AJAX queries through file system. If the AJAX queries fail for this reason, either you should launch your browser with different settings, or you should access the static pages through a deployed webapp (e.g., http://localhost:8080/topanat-dev/frontend-dev/examples/localhost_ajax.html, see deploy the test webapp on localhost)

Note: the topanat-dev webapp has been modified to allow cross-domain queries from any origin.

  • BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/examples/test_server_ajax.html adds a test of an AJAX query made to the Bgee topanat-dev webapp on test server (i.e., http://altbgee.unil.ch/topanat-dev/?page=top_anat see deploy the test webapp on test server). The only modification as compared to localhost_ajax.html is to change the host used to perform AJAX queries (see Bgee Javascript layout).

Example to load static HTML pages: this page could be loaded from file system, or from your localhost at http://localhost:8080/topanat-dev/frontend-dev/examples/test_server_ajax.html (see deploy the test webapp on localhost), or from the test server at http://altbgee.unil.ch/topanat-dev/frontend-dev/examples/test_server_ajax.html (see deploy the test webapp on test server).

Added in test_server_ajax.html as compared to localhost_ajax.html:

<script>
//this setting would not be needed if the page was accessed directly through 
//http://altbgee.unil.ch/topanat-dev/frontend-dev/examples/test_server_ajax.html, 
//but is is needed if you access it from file system, or from any other server, 
//such as your localhost. This can work only because cross-domain AJAX queries 
//from any origin has been enabled.
GLOBAL_PROPS.setBgeeHost('altbgee.unil.ch');
</script>

Note: many browsers disable the ability to perform AJAX queries through file system. If the AJAX queries fail for this reason, either you should launch your browser with different settings, or you should access the static pages through a deployed webapp (e.g., http://localhost:8080/topanat-dev/frontend-dev/examples/localhost_ajax.html, see deploy the test webapp on localhost)

Note: the topanat-dev webapp has been modified to allow cross-domain queries from any origin.

Deploy the test webapp on localhost

Follow the instructions to deploy webapp on server: the webapp can either be deployed through a real Tomcat server installed on your machine, or through Eclipse.

  • If you choose to use a real Tomcat server, the path to access the webapp will be the same as the name of the WAR file deployed in TOMCAT_HOME/webapps/. So, to access the webapp at the URL http://localhost:8080/topanat-dev/, the WAR file must be named topanat-dev.war (the Bgee webapp has been configured on the topAnat branch to generate a WAR file with such a name in BGEE_APPS_HOME/bgee-webapp/target/).

  • If you choose to deploy the webapp through Eclipse, you should have nothing more to do, and the webapp should be accessible at the URL http://localhost:8080/topanat-dev/ (configuration made in BGEE_APPS_HOME/bgee-webapp/.settings/org.eclipse.wst.common.component). Unless you had already imported the webapp in Eclipse before this configuration was made. In which case you need to delete the project from Eclipse and to re-import it (see Eclipse: import project).

Unless you made other modifications, the topAnat page should be accessible at http://localhost:8080/topanat-dev/?page=top_anat.

Test server

Access the test webapp on test server

Deploy the test webapp on test server

You can deploy the WAR file of the webapp on the test server through its Tomcat manager: http://altbioinfo.unil.ch/manager/html/ (login/password provided elsewhere).

  • In the Applications table, look for a webapp with the path /topanat-dev. If there is one, you need to unload it (Retirer button in French), otherwise your new deployment will fail. Warning: don't mess with the undeployment of a resource. This is our back-up server for Bgee ;)
  • Go to the 'upload WAR file' section (Fichier WAR à déployer in French). Select your WAR file, and upload it. Warning: your WAR file must be named exactly topanat-dev.war.
  • Check for the presence of any error message at the top of the page (it's written small). Otherwise, that's it.

Modifications on topAnat development completion

On the topAnat branch, the project has been modified so that: i) the resources built in BGEE_APPS_HOME/bgee-webapp/target/ (and notably, the WAR file to be deployed on the test server) are named with the prefix topanat-dev (instead of bgee-webapp-${project.version}); ii) Eclipse deploys the webapp to the context-root /topanat-dev (instead of an empty context-root); iii) a new directory allows to access static HTML files (BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/).

Important: after merging the topAnat branch, don't forget to restore the original settings. To see all modifications made: https://github.com/BgeeDB/bgee_apps/compare/68b9ec8d...d4092bda and 2d829f3da504740

  • in BGEE_APPS_HOME/bgee-webapp/.settings/org.eclipse.wst.common.component, modify
<property name="context-root" value="/topanat-dev"/>

into

<property name="context-root" value=""/>
  • in BGEE_APPS_HOME/pom.xml, remove the dependency to the artefact cors-filter (used to allow AJAX cross-domain queries from any origin):
<dependency>
    <groupId>com.thetransactioncompany</groupId>
    <artifactId>cors-filter</artifactId>
    <version>2.4</version>
    <scope>compile</scope>
</dependency>

  • in BGEE_APPS_HOME/bgee-webapp/pom.xml:

    • modify
<finalName>topanat-dev</finalName>

into

<finalName>bgee-webapp-${project.version}</finalName>
  • Remove the dependency to the artefact cors-filter (used to allow AJAX cross-domain queries from any origin)
<dependency>
    <groupId>com.thetransactioncompany</groupId>
    <artifactId>cors-filter</artifactId>
</dependency>
  • Re-enable CSS and JS file versioning by removing comments in properties css.version and js.version, see modification:
<!-- Note: disabling CSS and JS versioning for topAnat development 
     (will make deployment of test static HTML files easier) -->
<css.version><!-- ${project.version}c--></css.version>
<js.version><!-- ${project.version}c--></js.version>
  • in BGEE_APPS_HOME/bgee-webapp/src/main/resources/bgee-webapp.properties remove the bgeeRootDirectory setting:
org.bgee.webapp.bgeeRootDirectory=/topanat-dev/

  • in BGEE_APPS_HOME/bgee-webapp/src/main/webapp/WEB-INF/web.xml:

    • remove the servlet mapping for URLs /frontend-dev/* 
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>/frontend-dev/*</url-pattern>
</servlet-mapping>
  • remove the CORS filter (used to allow AJAX cross-domain queries from any origin):
<filter>
    <filter-name>CORS</filter-name>
    <filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>CORS</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
  • Delete the directory BGEE_APPS_HOME/bgee-webapp/src/main/webapp/frontend-dev/:
Clone this wiki locally