Developer Bootstrap

UI Development

Set up the Maven Build

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

2. Clone the SynapseWebClient project down to your computer: git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git
3. Change into the proper directory with: cd SynapseWebClient
4. Set up upstream with: git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient
5. Fetch and merge changes from the Sage Bionetworks repo, which was named upstream: 
   git fetch upstream

Set up the Eclipse Build

1. Install Eclipse (Mars 4.5, Neon 4.6 GWT super dev mode does not start properly)
2. Install Google Web Toolkit, Google App Engine SDK, and Google plug-in for Eclipse using Eclipse new software from http://www.gwtproject.org/download.html.  Note: if you were using an older version of this plugin you will need to uninstall it and then re-install it to ensure it has  GWT 2.8 beta1 support. Another note: Installing the Google App Engine Maven Integration software made Eclipse error when building the SynapseWebClient. It would not work until I uninstalled it.
3. Install the Maven2Eclipse plugin: http://download.eclipse.org/technology/m2e/releases
4. Create a GitHub user account
   
   1. Contributors should fork the repository and submit GitHub Pull Requests for code inclusion.

5. Set up Git: https://help.github.com/articles/set-up-git

6. 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
   3. Next, Finish 
7. 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 src/main/resources and src/test/resources directories.
8. 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 Tookit" check box is selected.
   2. Also make sure you are using GWT 2.8 beta1
9. We need to tell the Google plugin where our web app directory can be found.  Right-click on the project in the package explorer and select Properties.
   
   1.  From the tree on the left of the dialog navigate to Google → Web Application
   2. Check the the check box: "This project has a WAR directory"
   3. With the "Browse" button, select "src/main/webapp"
   4. 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.
10. Now make sure GWT can compile your code
    
    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.
11. If the GWT Compile successfully compiled, then you're ready to run the application.
    
    1. Option 1: start from within Eclipse.
       1. Right-Click on the project in the package explorer
       2. Select: Run As → Web Application (GWT Super Dev Mode)
       3. Set the run configuration VM Arguments to the following: "-XX:MaxPermSize=512m -Xms512m -Xmx2048m -XstartOnFirstThread".  Also look at your eclipse.ini file (if launching SDM from Eclipse).
       4. Double-click on the link provided in the Development Mode window to view the portal in your browser.  If you get asked what page to start on choose Portal.html.
    2. Option 2: build and run from the command line.
       1. Run 'mvn clean install'
       2. Run 'mvn gwt:run'

Eclipse Workspace Settings

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.
• "Could not deserialize" or similar problems in Super Dev Mode are most often fixed by re-building through the command line (running 'mvn clean install')
• (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.  

1. Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
2. Go to the project root on your file system and delete .classpath, .project and the .settings/ folder
3. Go to Step 6 in "UI Development above"

If this still doesn't work, or your dev mode is broken for another reason, there are some further steps you can take.
(Check out this site for more information: http://www.eclipsezone.com/eclipse/forums/t61566.html)

1. 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.
2. 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 → General → Preferences. Make sure that 'Export All' is checked.)
      2. Switch to a new workspace. (Switch Workspace → Other, then name your new workspace.)
      3. Import your preferences into this new workspace (Import → General → Preferences, make sure 'Import All' is checked.)
      4. Import trunk as usual.

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
• 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 Servelets.
• 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
• Mockito testing framework - mock dependent classes/interfaces to isolate test.  Verify expected interactions (including async calls). 
• Bootstrap UI framework (including a number of extras widgets), wrapped for GWT.
• 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
• 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).

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

1. Follow the instructions on the Platform Bootstrap to set up 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:
      1. cd integration-test
      2. 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:

      {"version":"develop-SNAPSHOT"}

3. In the SWC project root pom.xml, change the synapse.version tag to develop-SNAPSHOT (so that the dependency is pointing to the code that's running on your local stack).
4. Set the repository endpoints in your maven settings.xml file by adding the following properties:

<org.sagebionetworks.authenticationservice.privateendpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/auth/v1</org.sagebionetworks.authenticationservice.privateendpoint>
<org.sagebionetworks.authenticationservice.publicendpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/auth/v1</org.sagebionetworks.authenticationservice.publicendpoint>
<org.sagebionetworks.repositoryservice.endpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
<org.sagebionetworks.fileservice.endpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/file/v1</org.sagebionetworks.fileservice.endpoint>
<org.sagebionetworks.searchservice.endpoint>http://localhost:8080/services-repository-develop-SNAPSHOT/</org.sagebionetworks.searchservice.endpoint>
<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html</org.sagebionetworks.portal.endpoint>

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 staging

Set the repository endpoints in your maven settings.xml file by adding the following properties:

<org.sagebionetworks.authenticationservice.privateendpoint>https://auth-staging.prod.sagebase.org/auth/v1</org.sagebionetworks.authenticationservice.privateendpoint>
<org.sagebionetworks.authenticationservice.publicendpoint>https://auth-staging.prod.sagebase.org/auth/v1</org.sagebionetworks.authenticationservice.publicendpoint>
<org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
<org.sagebionetworks.fileservice.endpoint>https://file-staging.prod.sagebase.org/file/v1</org.sagebionetworks.fileservice.endpoint>
<org.sagebionetworks.searchservice.endpoint>https://search-staging.prod.sagebase.org/</org.sagebionetworks.searchservice.endpoint>
<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html</org.sagebionetworks.portal.endpoint>

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

How to point to prod

Set the repository endpoints in your maven settings.xml file by adding the following properties:

<org.sagebionetworks.authenticationservice.privateendpoint>https://auth-prod.prod.sagebase.org/auth/v1</org.sagebionetworks.authenticationservice.privateendpoint>
<org.sagebionetworks.authenticationservice.publicendpoint>https://auth-prod.prod.sagebase.org/auth/v1</org.sagebionetworks.authenticationservice.publicendpoint>
<org.sagebionetworks.repositoryservice.endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
<org.sagebionetworks.fileservice.endpoint>https://file-prod.prod.sagebase.org/file/v1</org.sagebionetworks.fileservice.endpoint>
<org.sagebionetworks.searchservice.endpoint>https://search-prod.prod.sagebase.org/</org.sagebionetworks.searchservice.endpoint>
<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html?gwt.codesvr=127.0.0.1:9997</org.sagebionetworks.portal.endpoint>

Pointing to prod is especially useful at transitions between releases, so that there is a stack that you can point at. 

Restart the Portal app to load these properties 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 http://asciiflow.com/ to help in these situations.

Compile Report

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