Skip to end of banner
Go to start of banner

Developer Bootstrap

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 61 Next »

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. Follow the instructions on the Platform Bootstrap.
  4. Change the synapse.version tag to develop-SNAPSHOT.
    1. The synapse.version tag in root pom.xml has the form 2012-08-06-3e90a85-44, it has the date (2012-08-06) and the first 7 chars of the commit hash, 3e90a85.
  5. Now, from an up-to-date clone of Synapse-Repository-Services on your local box:
    1. mvn clean install -Dorg.sagebionetworks.database.drop.schema=true
    2. cd integration-test
    3. mvn cargo:run

    4. 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"}
  6. Now, in your up-to-date clone of SynapseWebClient:
    1. mvn gwt:run
    2. A GWT Development Mode log window should pop-up.
  7. Now try to open the web-app from the Dev Mode window.  You should be prompted to install the GWT Dev Mode plugin (assuming your browser is supported).

Set up the Eclipse Build

  1. Install Eclipse
  2. Install Google Web Toolkit, Google App Engine SDK, and Google plug-in for Eclipse using Eclipse new software from Google's update site - http://dl.google.com/eclipse/plugin/4.2.  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.4.0 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. (Optional) Install the EGit eclipse plugin: http://www.eclipse.org/egit/download/
  5. Create a GitHub user account
    1. Internal Sage developers will be added as a developer on the project and will be able to push directly
    2. External contributors should fork the repository and submit GitHub Pull Requests for code inclusion

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

  7. 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 
  8. (Optional) Enable Git Team tracking
    1. Now right click on portal (project name) -> Team -> Share Project
    2. Next, Select repository type Git
    3. Next, Check the box "Use or create repository in parent folder of project
    4. Next, Finish 
  9. 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.
  10. 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.4.0 (or 2.5.1). Later versions also seem to work.
  11. 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.
  12. Now that the Portal.gwt.xml file is on the classpath, make sure GWT knows it is the entry point.
    1. Right-Click on the project from the package explorer.
    2. Select Google->Web Toolkit Settings...
    3. Under the "entry point modules" you should see "Portal - org.sagebionetworks.web",  if not, then add it with the add button.
  13. Now make sure GWT can compile your code
    1. Right-Click on the project in the package explorer
    2. Google->GWT Compile
    3. 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"
    4. 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. You may need to increase the max heap space even more to prevent running out of memory, so experiment with increasing -Xmx, the max heap space, to -Xmx3g (3 gigabytes rather than 1.5 gigabytes).
  14. You are finally ready to run the application in development mode.
    1. Right-Click on the project in the package explorer
    2. Select: Run As->Web Application
    3. 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
    4. If you get a 404 error, you may need to navigate to the project root directory and "mvn clean install".

Setup GWT SuperDevMode

As of Chrome version 39, the old GWT Development Mode is no longer available.
Using Super Dev Mode (SDM) means running two servers, one for the web application and one for the Code Server that compiles classes for SDM when the compile button is pushed on the web page or in the bookmark.

First thing to do is to make sure that your Google Plugin for Eclipse is up to date (version >=  3.8.0.v201410302155-rel-r42).
NOTE: After we update to GWT v2.6 or greater, this section needs to be rewritten (can be a single launch configuration if using GWT 2.6).

  • In your existing web application Portal launch configuration (created in the previous section above), add the following to the VM Arguments: "-Xmx512m -XX:MaxPermSize=512m -Dgwt.codeserver.port=9876"

Now it's time to create a new Run Configuration for the Code Server:

  • From the Run Configurations window, add a new Java Application, named "Portal GWT Super Dev Mode Code Server" (for example).
  • Set the Project to the Portal project.
  • Set the Main Class to com.google.gwt.dev.codeserver.CodeServer
  • Set the Program Arguments to "-src <SynapseWebClient_root_directory>/src/main/java -port 9876 org.sagebionetworks.web.Portal"

You should now be ready to launch the Code Server.  Here are a couple of common problems...

  • Missing jars in your WEB-INF/lib directory (the maven dependencies)?  "mvn clean install" from command line, then change your Run Configuration->Arguments->Working Directory to Other, pointing to ${workspace_loc:portal/target/portal-develop-SNAPSHOT}
  • Serialization problems? Due to this known issue that applies to GWT v2.5.1, you should always run the Code Server first, then start the Portal web application once the code server is available. We now copy over gwt.rpc files on servlet init as a workaround until we upgrade to GWT v2.6.

Almost done!

  1. Launch the Code Server, and go to the code server webpage (http://localhost:9876/) when it is ready. Now drag the bookmarklets to your browser's bookmark bar. 
  2. Launch the Portal Web Application run configuration, and go to http://127.0.0.1:8888/Portal.html .  In this window, click the Dev Mode On bookmarklet that you created from the previous step.  This will cause the code server to compile code for your user agent.
  3. The Portal should now be visible.  To debug client-side code, bring up the Developer Tools in the browser.  In Chrome, select the Sources tab, and expand the code server url (localhost:9876) until you find the java file that you would like to debug.  You can set breakpoints in this view.  To debug servlet-side code, in Eclipse start the Portal Web Application in debug mode, and set breakpoints within Eclipse.

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

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 try the following things:

  • Remove all of your PLFM projects, check out a fresh copy of the PLFM project and start from the beginning of this document.
  • Performing a Maven update.
  • Alternatively, you can just rebuild your Eclipse's Portal project and keep your files in place:
  1. Git pull update to the newest version
  2. Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
  3. Go to the project root on your file system and delete .classpath, .project and the .settings/ folder
  4. Go to Step 7 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:

Virtualization

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).

 

  • No labels