View generation

[fbastian]

In GitLab by @fbastian on Jan 20, 2016, 11:34

It is necessary to improve the generation of the views in the webapp. From discussion with @pmoret and @vrechdelaval, we agreed:

• to use React for managing our HTML and Javascript.

• to not create a separate frontend webapp containing only HTML/Javascript (as, e.g., neXtProt): we have legacy code generated in Java, and we don't have the time to do a complete migration of this code, the Java webapp needs to remain; also, it is convenient to generate some HTML code from the Java webapp.

• to not move to the NPM/grunt/Webpack ecosystem; we will rather continue compiling/minifying/concatenating JS file with Maven. Because of the previous point, because we want to keep only one build process, and because none of us is familiar with these tools.

• that the Java webapp will still generate some HTML code, lightweight and convenient. Notably, to be able to include raw JS files in development, and minified/concatenated files in production; otherwise, we would need either to use different HTML files for development/production, or to move to the NPM/Grunt ecosystem.

• to use the JSX language. And to not externalize it in separate files (to externalize, cf. react-templates (looks a bit like Angular syntax...), or "manual externalization")

• that we'll start using React for new HTML code that we'll write.

TODO

• @pmoret: check how IntelliJ manages JSX/Javascript/HTML, and whether it is as convenient as in Eclipse to run a local webapp.
• @vrechdelaval: check with neXtProt their workflow; notably, do they have two separate webapps for the main website (one pure Java, one pure HTML/JS); what do they think of the ecosystem they use (NPM etc); ...
• @fbastian: create a complete workflow (use of React in a page, compilation of JSX code, minify/concatenate, etc)

Notes

• React allows server-side rendering, and to build an isomorphic webapp, see http://winterbe.com/posts/2015/02/16/isomorphic-react-webapps-on-the-jvm/
• Manage document title for server-side rendering: https://github.com/gaearon/react-document-title
• React starter kit: https://github.com/kriasoft/react-starter-kit/tree/master/docs
• NPM as a build tool? http://blog.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/
• Learn ES6: http://babeljs.io/docs/learn-es2015/
• A Maven plugin allows to install NPM and to use Webpack: https://github.com/eirslett/frontend-maven-plugin
• I guess we should use the client-side transform for development, and offline transform for production (using NPM and Webpack, see https://facebook.github.io/react/docs/getting-started.html).
• Eclipse doesn't manage JSX. A plugin of the Tern IDE, part of Eclipse, could solve the problem, see https://github.com/angelozerr/tern-react/issues/2
• To add support for React in Tern, some files need to be manually added :/ Requested an installation URL (https://github.com/angelozerr/tern-react/issues/3). In the mean time, I created a folder tern-react in /Applications/Eclipse.app/Contents/Eclipse/plugins/ternjs_1.1.0.201511082254/node_modules, and put in it package.json and react.js
• routing with React: https://github.com/rackt/react-router

[fbastian]

In GitLab by @fbastian on Jan 20, 2016, 15:40

I managed to activate JSX/ES6 support in Eclipse, see https://github.com/angelozerr/tern-react/issues/2#issuecomment-173222751

I'll update the Eclipse configuration files in a new react branch, and update the webapp documentation (you'll need to install the Tern Eclipse plugin).

[fbastian]

In GitLab by @fbastian on Jan 27, 2016, 17:20

Proposed plans

• we should entirely develop our frontend outside of maven/eclipse/tomcat, otherwise:

  • the workflow is too cumbersome (e.g., to include/concatenate/minify resources, to include them in different ways in dev mode or production mode, etc)
  • we don't benefit from the ecosystem existing around React.

• we should develop using NPM and webpack, because:

  • React advice to use NPM with webpack or browserify, but then provide all examples using webpack.
  • There is a Maven plugin allowing to install and run NPM and webpack, not browserify.
  • webpack seems to gain more attention than browserify lately.

• webpack configuration is complicated. hjs-webpack is a nice tool to make it easy:

  • hjs-webpack comes with a pre-built configuration, allowing automatic management of resources, and of development environment (hot reload, etc).
  • it is anyway always possible to take over hjs-webpack default configuration, and configure webpack as we wish.

• We will write code in JSX/webpack/ES6 syntax. This code will then be transpiled using Babel

  • the Babel preset we'll need are: babel-preset-es2015, babel-preset-react, babel-preset-react-hmre, see https://github.com/HenrikJoreteg/hjs-webpack#changing-babel-config

• When building our WAR file, we'll use the frontend-maven-plugin mentioned above to compile our webpack source files into CSS/JS files, and include them in the WAR directory. No need for two separate build processes.

• In development, the HTML calling our JS/CSS files (i.e., index.html) will be produced by webpack see https://github.com/HenrikJoreteg/hjs-webpack#html-optional-can-be-boolean-or-function.

• In production, the HTML will be sent by the server. This is to allow server-side rendering in the future if we wish.

Proposed code guides

• Our code will need to be module based, using CommonJS, AMD, or ES6 syntax. This is the standard for webpack development. See http://www.jbrantly.com/es6-modules-with-typescript-and-webpack/. From webpack-howto, "If you don't know what to use, use CommonJS".

• Don't use ES6 class declarations. Use Render.createClass. See react-router documentation update, and this tweet by react developer

• Use ES6 features, but only those supported by Babel, see http://babeljs.io/docs/learn-es2015/

• Don't write components in an App entry point, an entry point cannot be hot reloaded in dev. environment, see here and here

• Always use react-document-title, to potentially get access to document.title for server-side rendering.

• Avoid using global vars/global functions, data should be provided through states/props. But if you do, use React Context

Open questions

• Which routing library to use: react-router or react-router-component?

  • Both are similar, and both seem capable of server-side rendering. react-router seems more widely adopted.

• How to keep URL parameters in sync between server and client code? Potential solutions:

  • don't care, simply hardcode URLs everywhere in client code.
  • let the server provide URLs for webservice calls and client browser navigation. See for instance links management in JSON-API 1.0; transform our URLParameters objects from java to JSON, so that client code has access to parameter names, types, etc.

• Should we formally implement JSON-API in our responses? Currently we are based more on JSend. See the update of our JSON responses

• Should we make one App for all the website, with one Component per page (e.g., GeneComponent, AboutComponent), or one App per page?

Reading

NPM

• NPM is kind of similar to "Makefiles". See this tutorial explaining how to solely use NPM to build a frontend.

Webpack

• how-to

React-router

• Introduction

• basic demo

• Examples

• life cycles

• API reference

• management of query parameter with react-router: get URL parameters, Example

• Update URLs outside of components:

  • https://github.com/rackt/react-router/blob/master/docs/guides/advanced/NavigatingOutsideOfComponents.md
  • http://stackoverflow.com/questions/31079081/programmatically-navigate-using-react-router

Server-side rendering

• server-side rendering with tomcat: http://winterbe.com/posts/2015/02/16/isomorphic-react-webapps-on-the-jvm/
• server-side rendering with react-router:
  • stackoverflow answer
  • react-router server-side rendering documentation
  • universal server-side rendering with react-router