Content Comparison

Table of Contents
minLevel 3

UI Development

Set up the Maven Build

...

1. Contributors should fork the repository and submit GitHub Pull Requests for code inclusion.

...

Set up Git: https://help.github.com/articles/set-up-git, and install git-secrets.

...

Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo

...

git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git

...

cd SynapseWebClient

...

git secrets --install
git secrets --register-aws

...

git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient

...

git fetch upstream

...

This should be the content of this file:

...

...

UI Development

Prerequisite software to install

• Java (Corretto JDK 11+ recommended)

• Maven 3

• Docker

• Yarn v1

Set up your GitHub fork and a local repository

1. Create a GitHub user account if you don't already have one.

2. Set up your local git environment according to Sage’s GitHub Security guidance

3. Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo

4. Clone your fork of SynapseWebClient project to your local machine and enter the project root directory

   Code Block
   language bash
   git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git cd SynapseWebClient

5. If you didn't set up the global pre-commit hook in step #2, set up a local pre-commit hook to detect secrets (do this for all repos that you clone in the future!):

   Code Block
   git secrets --install git secrets --register-aws

6. Set up upstream with

   Code Block
   git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient

7. Fetch and merge changes from the Sage Bionetworks repo, which was named upstream: 

   Code Block
   git fetch upstream

8. Configure or update your Maven configuration settings.xml

   1. The file needs to placed in $HOME/.m2/settings.xml (e.g. jane/.m2/settings.xml)

   2. This should be the content of this file:

      settings.xml

      Code Block
      language xml
      <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <localRepository/> <interactiveMode/> <usePluginRegistry/> <offline/> <pluginGroups/> <servers/> <mirrors/> <proxies/> <profiles> <profile> <id>dev-environment</id> <activation> <activeByDefault>true</activeByDefault> </activation>

...

1. 1. <properties> <org.sagebionetworks.portal.endpoint>http://

...

1. 1. 127.0.

...

1. 1. 0.

...

1. 1. 1:8888/Portal.html</org.sagebionetworks.portal.endpoint>

...

...

...

1. 1. <org.sagebionetworks.repositoryservice.endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> <!-- insert properties described below here -->

...

1. 1. <!-- <org.sagebionetworks.

...

1. 1. repositoryservice.

...

1. 1. endpoint>https://

...

1. 1. repo-staging.

...

1. 1. prod.

...

1. 1. sagebase.org/repo/v1</org.sagebionetworks.

...

1. 1. repositoryservice.endpoint> -->

...

1. 1. <!-- Uncomment the property below to limit GWT permutations and speed up build time --> <!-

...

Setup with Eclipse

...

1. File → Import → Maven → Existing Maven Projects
2. Next, in Root Directory enter the local path to your repository clone
3. Next, Finish 

...

1. Right-click on portal (project name) → Build Path → Configure Build Path...
2. Remove the "Exclude" filter from the source tab on the src/main/resources and src/test/resources directories.

...

1. From the resulting dialog make sure the "Use Google Web Toolkit" check box is selected.
2. Also make sure you are using the GWT SDK from your local maven repository (.m2/repository/com/google/gwt)

...

1. Right-Click on the project from the package explorer.
2. Select Google→GWT Compile...
3. Under the "Entry Point Modules" you should see "PortalDebug - org.sagebionetworks.web",  if not, then add it with the add button.
4. Remove the "Portal - org.sagebionetworks.web" entry.
5. The first time you run this you will be asked to select the output directory where GWT will compile the code. You want this to match the Maven WAR output directory, so use "target/portal-<VERSION>-SNAPSHOT"
6. If you get compilation errors from the JavaScript validator (i.e. NullPointerException), navigate to the project's properties → JavaScript → Include Path → Source, and exclude all files from the source. If an OutOfMemoryError was thrown while compiling, you can click the "Advanced" tab towards the bottom of the Google → GWT Compile window and add "-Xms512M -Xmx1524M" to the VM arguments to increase heap space.

...

Set the following arguments:

${workspace_loc:/portal/node/yarn/dist/bin/yarn.js}
sass
--no-source-map
--style=compressed
--unicode
--stop-on-error
--update 
--load-path=.
src/main/webapp/sass:target/portal-develop-SNAPSHOT

...

1. Right-Click on the project in the package explorer
2. Select: Run As → GWT Development Mode with Jetty, and select Portal.html
3. Double-click on the link provided in the Development Mode window to view the portal in your browser. 

...

1. Right-Click on the project from the package explorer.
2. Select: Run As → JUnit Test

Setup with Intellij

1. Download IntelliJ community edition, it comes pre-built with GWT and Maven support. 
2. Install GWT SDK (install the actual SDK, not the eclipse plugin version)
   1. If downloading Java for the first time then download Java 8 as well.
3. If you want to run Maven manually then install it from here (this will require you to add the mvn installation directory to your PATH as well), otherwise see notes here on configuring IntelliJ to run maven build.
4. Import the SWC into IntelliJ by File → New Project From Existing Sources... <Select Path to SWC Location>
5. If running Maven manually run like so (see note below on saving build time by running in debug mode):
   1. Run 'mvn clean install'
   2. Run 'mvn gwt:run'

...

1. 1. - <gwt.module.suffix>Debug</gwt.module.suffix> --> </properties> </profile> </profiles> <activeProfiles/> </settings>

2. Verify you can build the project and run the unit tests:

   Code Block
   mvn clean install

Development

You may use an IDE of your choice. Instructions for setting up IntelliJ IDEA and Eclipse can be found below.

To run the app in development mode, run yarn install then yarn dev. This will launch three processes:

• The GWT Codeserver, which watches for source changes

• A file watcher that monitors changes to static assets, and copies them to the deployed web application directory when they change

• An Apache Tomcat Docker container that will host the web application

As you make changes to the source code and static assets, changes will be picked up in the app when you refresh the page.

Running the accounts site to enable sign-in

SynapseWebClient delegates authentication and account management to a separate web application. In order to sign in to a local instance of SynapseWebClient, you must also start a local instance of the account management application. Set up the synapse-web-monorepo project and run the following command.

pnpm nx run SageAccountWeb:preview --port=3000 --host

If your portal instance is configured to use to a different backend stack, you will need to configure SageAccountWeb to also use the same stack.

We have an open ticket to improve this process: SWC-7230

JavaScript dependency development

If you have made changes to a JavaScript dependency (e.g. synapse-react-client), you can see those changes in your local development environment by “linking” the projects. As an example, we will link the synapse-react-client project.

1. In the synapse-react-client directory, run

   Code Block
   yarn link

2. In the SynapseWebClient directory, run

   Code Block
   yarn link synapse-react-client

   This will create a symlink on your machine so the node_modules/synapse-react-client directory points to your local synapse-react-client directory.

3. Make desired changes in the synapse-react-client project

4. Rebuild the JavaScript artifacts for synapse-react-client (pnpm nx run synapse-react-client:build)

5. If you’re running yarn dev, the changed JavaScript file should automatically be picked up. Refresh your browser window to see the changes (you will likely need to open your browser dev tools → Network → Disable Cache, and leave the browser devtools open)

When you want to unlink synapse-react-client, in the SynapseWebClient directory you can run yarn unlink synapse-react-client and then yarn install --force.

Known issues:

• Running yarn install in SynapseWebClient after linking synapse-react-client breaks the pnpm installation in the synapse-web-monorepo project. To fix this, run pnpm install --force in the synapse-web-monorepo project.

IDE Setup Instructions

This section contains instructions for setting up various IDEs to develop SynapseWebClient.

...

...

...

...

Technologies used

There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:

...

• Guice - is the base IoC technology but it is only fully functional in Server-side.
• Gin - provides basic IoC for GWT client-side code.
• Guice Servlet - This is a sub-project of Guice that allows dependency inject into Servelets.

...

Technologies used

There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:

• Java!

• Google Web Toolkit

• React and the Synapse React Client

  • Further reading: How to create and render a React component in SynapseWebClient

• For dependency injection, an example of Inversion of Control (IoC), we are using a combination of GIN and Guice.

  • Guice - is the base IoC technology but it is only fully functional in Server-side.

  • Gin - provides basic IoC for GWT client-side code.

  • Guice Servlet - This is a sub-project of Guice that allows dependency inject into servlets.

• HTTP REST calls are currently made using Spring's RestTemplate. http://blog.

  msbbc.co.uk/2008/11/java-using-jersey-and-grizzly-to-create.html

  springsource.com/2009/03/27/rest-in-spring-3-resttemplate/

• Mockito testing framework - mock dependent classes/interfaces to isolate test.  Verify expected interactions (including async calls). 

• Bootstrap 3 UI framework (including a number of extras widgets), wrapped for GWT (deprecated).

• Markdown-it - for markdown processing .  Extended the library by adding a number of plugins, available on npm.  The Node.js plugin that's used to orchestrate the processing is called markdown-it-synapse. The source code for many of these plugins is in the synapse-web-monorepo project.

• AWS js sdk - direct browser upload/download from s3-like storage.

• jquery, moment js, font-awesome, mathjax, plot.ly, twitter, nodeca/pica (browser image resize), SparkMD5 (browser side md5 calculation), nchart and jsplumb (Dave's charting libraries for provenance), Google (analytics, search, closure-library, single sign on).

• frontend-maven-plugin to install

  node

  Node and

  yarn

  Yarn at build-time

  .

Cross-browser testing

We have a shared account to use BrowserStack to test the website for cross browser compatibility issues.
Alternatively, for testing IE on Mac I use VirtualBox with an image provided by Microsoft from modern.IE.  For this to work, in your Windows VM, you will need to map an ip to outer in order to access your local machine (note, Windows UAC requires you to do this as an admin).

How to limit GWT build permutations

To speed up build time, add the following property to your local maven settings.xml file:

<gwt.module.suffix>Debug</gwt.module.suffix>

How to point to the local stack

...

Build and launch a local backend stack.  From an up-to-date clone of Synapse-Repository-Services on your local box:

...

Build the local stack by running 'mvn clean install -Dorg.sagebionetworks.database.drop.schema=true'.

...

1. cd integration-test
2. mvn cargo:run

...

• , which provides numerous JavaScript dependencies via NPM.

End-to-end testing

Instructions on running end-to-end tests are included in this README.

How to point to a local instance of the Synapse backend

1. Follow the instructions on the Platform Bootstrap to set up a local backend stack. 

2. Build and launch a local backend stack.  From an up-to-date clone of Synapse-Repository-Services on your local box:

   1. Build the local stack by running mvn clean install -Dorg.sagebionetworks.database.drop.schema=true.

   2. Now launch it:

      Code Block
      cd integration-test mvn cargo:run

   3. Verify the services are running correctly by visiting http://localhost:8080/services-repository-develop-SNAPSHOT/repo/v1/version. You should see something like this:

      Code Block
      {"version":"develop-SNAPSHOT"}

3. In the SWC project root pom.xml, change the synapse.version tag to develop-SNAPSHOT, so that Maven utilizes artifacts that were built by running on your local stack.

4. Update the repository endpoint property in your maven settings.xml file:

   Code Block
   <org.sagebionetworks.repositoryservice.endpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/repo/

...

{"version":"develop-SNAPSHOT"}

...

1. v1</org.sagebionetworks.repositoryservice.endpoint>

2. Restart the Portal app to load these properties from settings.xml.

How to point to a remote stack

Set the repository endpoint parameters in your maven settings.xml file

...

. 

To point to the development stack set:

<org.sagebionetworks.repositoryservice.

...

Note that emails will not be sent when pointing to a local repo, the SynapseEmailService will instead write files to the devdata.sagebase.org s3 bucket in format <to_email_address>.json

Restart the Portal app to load these properties from settings.xml.

How to point to a remote stack

...

endpoint>https://repo-dev.dev.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>

To point to staging set:

...

<org.sagebionetworks.repositoryservice.

...

endpoint>https://repo-staging.prod.sagebase.org/repo/

...

v1</org.sagebionetworks.repositoryservice.

...

endpoint>

To point to production set:

<org.sagebionetworks.repositoryservice.

...

endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.

...

endpoint>

Restart the Portal app to load this property from settings.xml.

...

To get the big picture of widget relationships, sometimes it is helpful to have a picture.  We are testing the use of tools like httphttps://asciiflowmermaid.js.comorg/ to help in these situations.

...