Content Comparison

Table of Contents

minLevel	3
maxLevel	6
outline	false
type	list
separator	brackets
printable	true

Child pages (Children Display)

UI Development

...

Internal Sage developers will be added as a developer on the project and will be able to push directly
External contributors should fork the repository and submit GitHub Pull Requests for code inclusion

...

e.x. READ-ONLY: git clone https://git@github.com/Sage-Bionetworks/SynapseWebClient.git

...

Prerequisite software to install
Java (Corretto JDK 11+ recommended)
Maven 3
Docker
Yarn v1

Set up your GitHub fork and a local repository

Create a GitHub user account if you don't already have one.
Set up your local git environment according to Sage’s GitHub Security guidance
Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo
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
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

Set up upstream with

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

Fetch and merge changes from the Sage Bionetworks repo, which was named upstream:
Code Block
git fetch upstream

Configure or update your Maven configuration settings.xml

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

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>
      <properties>
		<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html</org.sagebionetworks.portal.endpoint>
        <org.sagebionetworks.repositoryservice.endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
        <!-- insert properties described below here -->
        <!-- <org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
        <!-- Uncomment the property below to limit GWT permutations and speed up build time -->
        <!-- <gwt.module.suffix>Debug</gwt.module.suffix> -->
      </properties>
    </profile>
  </profiles>
  <activeProfiles/>
</settings>

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.

Code Block
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

Expand

title	Alternative ways to run SynapseWebClient in development mode

Instead of running yarn dev, you can alternatively directly use the GWT Maven plugin (e.g. mvn gwt:run) or an IDE integration. Please note that depending on your IDE/plugin configuration, your environment may be subtly different than the production system (e.g. many GWT plugins deploy a Jetty server, when we use Tomcat in production), which can result in subtle differences in behavior.

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.

In the synapse-react-client directory, run
Code Block
yarn link
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.
Make desired changes in the synapse-react-client project
Rebuild the JavaScript artifacts for synapse-react-client (pnpm nx run synapse-react-client:build)
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.

Expand

title	Setup with Eclipse

Install the latest Eclipse (for Java Development)
Install the Google Plug-in for Eclipse. Do not include GWT SDK in the install (GWT SDK will be installed by the maven install). Do not install the Google App Engine Maven Integration.
Import the project as a maven project
1. File → Import → Maven → Existing Maven Projects
2. Next, in Root Directory enter the local path to your repository clone

...

2. Next, Finish
You need to make sure the GWT xml files are on the classpath. All of these resources can be found in src/main/resources and src/test/resources

...

directories.
1. Right-click on portal (project name) → Build Path → Configure Build Path...

...

2. Remove the "Exclude" filter from the source tab on the

...

1. src/main/resources and src/test/resources directories.
We need to tell the GWT Eclipse-plugin that this is a GWT project. Do this by Right-Clicking on the project in the package explorer and select: Google

...

→ Web Toolkit Settings...
1. From the resulting dialog make sure the "Use Google Web

...

1. Toolkit" check box is selected.
2. Also make sure you are using

...

From the tree on the left of the dialog navigate to Google->Web Application
Check the the check box: "This project has a WAR directory"
With the "Browse" button, select "src/main/webapp"
UN-CHECK the "Launch and deploy from this directory" This is very important, if you keep this checked then Maven will not be able to generate a clean WAR file. If you see "GWT needs to recompile" when you deploy your WAR then you probably have this box checked.

...

1. the GWT SDK from your local maven repository (.m2/repository/com/google/gwt)
Verify GWT can compile your code
1. Right-Click on the project from the package explorer.
2. Select

...

1. Google→GWT Compile...
2. Under the "

...

1. Entry Point Modules" you should see "

...

1. PortalDebug - org.sagebionetworks.web", if not, then add it with the add button.

...

1. Remove the "Portal - org.sagebionetworks.web" entry.
2. 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"

...

Code Block

language	xml

<!-- Comment the below security constraint out if you are working in GWT development mode -->
<!-- 	<security-constraint>
		<web-resource-collection>
			<web-resource-name>Protected Context</web-resource-name>
			<url-pattern>/*</url-pattern>
		</web-resource-collection>
		<user-data-constraint>
			<transport-guarantee>CONFIDENTIAL</transport-guarantee>
		</user-data-constraint>
	</security-constraint>
 -->

...

1. 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.
If the GWT Compile successfully compiled, then you're ready to run the application.
1. Right-Click on the project in the package explorer
2. Select: Run As

...

1. → GWT Development Mode with Jetty, and select Portal.html
2. Double-click on the link provided in the Development Mode window to view the portal in your browser.

...

Getting Eclipse's GWT Dev mode working again after version changes

When the root pom.xml's version changes (upon each sprint's release), your dev mode will be broken (giving either a 404 or a 503 error when you try to view the page at http://127.0.0.1:8888/Portal.html?gwt.codesvr=127.0.0.1:9997. To fix this you can do one of two things:

...

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

Eclipse Workspace Settings verification:

Set file encoding to UTF-8 and the line-endings (for new files) to Unix, so that text files are saved in a format that is not specific to the Windows or Mac OS and most easily shared across heterogeneous developer desktops:

Open Preferences
Navigate to the Workspace preferences: General → Workspace
Change the Text File Encoding to UTF-8
Change the New Text File Line Delimiter to Other and select Unix from the drop-down

Troubleshooting

Check your exclusion filters through configure build path in Eclipse to assure nothing is excluded, then refresh and clean the SWC project.
(git) Pull the latest changes from the upstream repository.
Try to rebuild your Eclipse's Portal project and keep your files in place

...

.
Perform a Maven update.

Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
Go to

...

the project root on your file system and delete .classpath, .project and the .settings/ folder
Go to

...

"Set up with Eclipse"

Verify the web app directory is correct. Right-click on the project in the package explorer and select Properties:

From the tree on the left of the dialog navigate to Google → Web Application
Check the the check box: "This project has a WAR directory"
With the "Browse" button, select "src/main/webapp"
UN-CHECK the "Launch and deploy from this directory" This is very important, if you keep this checked then Maven will not be able to generate a clean WAR file. If you see "GWT needs to recompile" when you deploy your WAR then you probably have this box checked

If this still doesn't work, or your dev mode is broken for another reason

...

, there are some further steps you can take.

...

Use the '-clean' argument.
1. One way to do this is to add -clean on its own line as the first line on the eclipse.ini file, and restart Eclipse.
Use a new workspace.
1. I followed the instructions in the site linked above. The gist of it is:
  1. Export your preferences to somewhere outside your Eclipse environment environment (Export

...

1. 1. → General

...

1. 1. → Preferences. Make sure that 'Export All' is checked.)
  2. Switch to a new workspace. (Switch Workspace

...

1. 1. → Other, then name your new workspace.)
  2. Import your preferences into this new workspace (Import

...

1. 1. → General

...

1. 1. → Preferences, make sure 'Import All' is checked.)
  2. Import trunk as usual.

Expand

title	Setup with Intellij IDEA

Download IntelliJ IDEA
1. The community edition is free
2. The Ultimate edition requires purchasing a license. It includes enhanced support for GWT, but it’s not necessary for development.
Import the SynapseWebClient project into IntelliJ by File → New Project From Existing Sources... <Select Path to SWC Location>
Set up IntelliJ to directly call yarn dev
1. Run → Edit Configurations…
2. Click “Add New Configuration” → npm
3. Set the following options
  - Command: run
  - Script: dev
  - Package manager: yarn

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
  . http://code.google
  .
  com/docreader/#p=google-guice&s=google-guice&t=Motivation
- Gin - provides basic IoC for GWT client-side
  code. http://
  code
  .google
  .
  com/p/google-gin/wiki/GinTutorial
- Guice Servlet - This is a sub-project of Guice that allows dependency inject into
  Servelets. http://code.google.com/p/google-guice/wiki/ServletModule
Http
- servlets.
HTTP REST calls are currently made using Spring's RestTemplate. http://blog.springsource.com/2009/03/27/rest-in-spring-3-resttemplate/
To create API REST stub-services we are using a combination of two technologies:
- Jersey - provides a quick and easy method for transforming simple POJO's into RESTful web services using annotations. http://jersey.java.net/nonav/documentation/latest/user-guide.html
- Grizzly - The GrizzlyWebContainerFactory makes it simple to start a local web container. http://blog.msbbc.co.uk/2008/11/java-using-jersey-and-grizzly-to-create.html

How to override configuration (obsolete, needs updating)

If you want to point it to a locally running instance of the repository service:

Run As->Run Configurations
click on the "Arguments" Tab
add to the VM Arguments -Dorg.sagebionetworks.rest.api.endpoint=http://localhost:8080/
Image Removed

Creating a new Maven + GWTproject

This section outlines what is needed to create a new Java project that is configured correctly for both Maven and GWT. To setup a project correctly, we will be depending on the gwt-maven-plugin: http://mojo.codehaus.org/gwt-maven-plugin/.

...

From command line run the following command, and fill in all of the variables:

Code Block
mvn archetype:generate \ -DarchetypeRepository=repo1.maven.org -DarchetypeGroupId=org.codehaus.mojo \ -DarchetypeArtifactId=gwt-maven-plugin \ -DarchetypeVersion=2.1.0-1

...

./settings/org.eclipse.jdt.core.prefs
./settings/org.eclipse.wst.common.component
./settings/org.eclipse.wst.common.project.facet.core.xml
pom.xml

...

Right-click the project root in the package explorer and select properties.
1. Under the Java Build Path tab, select Libraries.
2. Remove the 1.5 JRE library.
3. Select Add Library...
4. Select JRE System Library then Next, and choose a 1.6 library.

...

In the gwt-maven-plugin, comment-out the generateAsync goal as it conflicts with the GWT eclipse plugin:

...

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 and Yarn at build-time, 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

Follow the instructions on the Platform Bootstrap to set up a local backend stack.
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"}
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.

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/v1</org.sagebionetworks.repositoryservice.endpoint>

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

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

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:

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

To point to staging set:

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

To point to production set:

Code Block
<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.

Documenting complicated UI in the code

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

Compile Report

To generate a compile report, set enableClosureCompiler to false in the root pom.xml

Version	Old Version 7	New Version Current
Changes made by	David Burdick (Unlicensed)	Nick Grosenbacher
Saved on	May 23, 2012	Jan 27, 2025

Versions Compared

Key

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

Development

Running the accounts site to enable sign-in

JavaScript dependency development

IDE Setup Instructions

Getting Eclipse's GWT Dev mode working again after version changes

Technologies used

How to override configuration (obsolete, needs updating)

Creating a new Maven + GWTproject

End-to-end testing

How to point to a local instance of the Synapse backend

How to point to a remote stack

Documenting complicated UI in the code

Compile Report

Content Comparison

Versions Compared

Key

UI Development

Prerequisite software to installJava (Corretto JDK 11+ recommended)Maven 3DockerYarn v1

Set up your GitHub fork and a local repository

Development

Running the accounts site to enable sign-in

JavaScript dependency development

IDE Setup Instructions

Getting Eclipse's GWT Dev mode working again after version changes

Technologies used

How to override configuration (obsolete, needs updating)

Creating a new Maven + GWTproject

End-to-end testing

How to point to a local instance of the Synapse backend

How to point to a remote stack

Documenting complicated UI in the code

Compile Report

Prerequisite software to install
Java (Corretto JDK 11+ recommended)
Maven 3
Docker
Yarn v1