cavis/deeplearning4j/deeplearning4j-ui-parent/deeplearning4j-ui-components/developerReadme.md

51 lines
3.6 KiB
Markdown

## Developer Readme
Some things to know regarding the deeplearning4j-ui-components module:
- This module is designed with the following goals in mind:
- Providing easy Java/JavaScript interoperability for reusable user interface components (charts, tables etc)
- Maintainability via the use of TypeScript and proper OO design
- Rapid application development, rather than providing the greatest amount of power/flexibility
The directory/package and file structure is mirrored (as much as possible) on both the java and typescript sides.
Some design principles here:
- Content and style are separate
- The goal is to have style information as an *optional* component on the Java side
- In principle styling can be done entirely in Java, entirely in JavaScript/CSS, or via a mixture of both (style options defined in Java will override those defined in CSS)
- In both the Java and TypeScript, there are Style objects; these define properties such as colors or line widths
- Java objects for UI components are created; these are converted to JSON using Jackson (typically to be posted to a web server)
- Jackson is configured to ignore null elements when encoding JSON (and the TypeScript code should handle missing values)
- JSON is converted back into JavaScript/TypeScript objects using the Component.getComponent(jsonStr: string) method, or using the TS object constructors directly (i.e., these parse the JSON)
- Consequently, any changes made to the Java UI component classes should be mirrored in both the Java and TS code
- After the JS/TS versions of the UI objects are created, they can be added to an existing component using the .render(addToObject: JQuery) method
- For charts, d3.js is used
- At present: behaviour (on click events, etc) cannot be defined in Java (this has to be done in TS/JS)
**Setup for developing TypeScript code**
- Install [node.js](https://nodejs.org/en/) and [TypeScript compiler](https://www.typescriptlang.org/#download-links)
- Then, in IntelliJ
- Ensure auto-compilation to TypeScript is disabled (untick "Enable TypeScript Compiler" in File -> Settings -> Languages & Frameworks -> TypeScript)
- Install the File Watchers plugin (File -> Settings -> Plugins). This will enable auto compilation to a *single* javascript library any time you make a change to the .ts files (next step)
- Set up a new file watcher for compilation
- File -> Settings -> Tools -> File Watchers; (+) -> TypeScript
- Program: point to typescript compiler (on Windows, for example: "C:\Users\ *UserName* \AppData\Roaming\npm\tsc.cmd")
- Arguments: empty (empty: use tsconfig.json)
After the above setup, all TypeScript files will be compiled to a single javascript file.
(Make sure your TypeScript compiler version is up to date; tsconfig.json is only suported by version 1.5 or above)
- Location: /deeplearning4j-ui-components/src/main/resources/assets/dl4j-ui.js
- A source map file (dl4j-ui.js.map) will also be produced; this aids with debugging (can see/debug original typescript code, even after it is converted to JavaScript)
- File name, location, and other options are defined in the tsconfig.json
**Note:** A rendering test is available in *test.java.org.deeplearning4j.ui.TestRendering.java* that generates a HTML file with some sample graphs.
It is recommended to open this via IntelliJ (right click -> Open In Browser)
**Note 2:** The *src/main/typescript/typedefs/* folder contains type definitions for some javascript libraries, from [https://github.com/DefinitelyTyped/DefinitelyTyped](DefinitelyTyped).
These allow us to use javascript libraries in typescript, whilst having type information.