README_DEV.md

Lets-Plot for Kotlin Developers Guide

Building the project

Copy file build_settings.template.yml located in the project root directory to the file named build_settings.yml in the same location.

run ./gradlew build

Running demos

Aside from of Jupyter demo notebooks the project also contains a set of simple demos showing how plots can be built in a JVM or Kotlin/JS environment.

Each JVM demo has main method and is launched like any other JVM application.

The Kotlin/JS demo app is launched using Gradle task: ./gradlew :js-frontend-app:browserDevelopmentRun

The simple demos can be found in the following folders:

lets-plot-kotlin/demo/browser
lets-plot-kotlin/demo/jvm-batik
lets-plot-kotlin/demo/jvm-javafx
lets-plot-kotlin/demo/geotools-batik
lets-plot-kotlin/demo/js-frontend-app

Lets-Plot in JVM and Kotlin/JS applications

Lets-Plot library enables embedding plots into a JVM or Kotlin/JS application.

When in JVM environment the Lets-Plot library offers a choice between JavaFX graphics and rendering powered by Apache Batik SVG Toolkit.

Artifacts

All artifacts are available at Maven Central.

Lets-Plot Kotlin API	lets-plot-kotlin-jvm lets-plot-kotlin-js lets-plot-kotlin-geotools		Published by this project.
Lets-Plot library	lets-plot-batik lets-plot-jfx lets-plot-common		Published by the Lets-Plot library project.

Project dependencies

The following is how you configure a Gradle (Groovy) project:

repositories {
  mavenCentral()
}

• JVM/Swing/Batik application:

dependencies {
    implementation "org.jetbrains.lets-plot:lets-plot-batik:$lets_plot_library_version>"
    implementation "org.jetbrains.lets-plot:lets-plot-kotlin-jvm:$lets_plot_kotlin_api_version"
}

• JVM/Swing/JavaFX application:

dependencies {
  implementation "org.jetbrains.lets-plot:lets-plot-jfx:$lets_plot_library_version"
  implementation "org.jetbrains.lets-plot:lets-plot-kotlin-jvm:$lets_plot_kotlin_api_version"
}

Note: Depending on which JRE you are using, you might need to add JavaFX dependencies as well.

• JVM/other:

If your JVM app doesn't use either frontend, you can provide just "lets-plot-common" dependency:

dependencies {
  implementation "org.jetbrains.lets-plot:lets-plot-common:$lets_plot_library_version"
  implementation "org.jetbrains.lets-plot:lets-plot-kotlin-jvm:$lets_plot_kotlin_api_version"
}

• Kotlin/JS application:

dependencies {
  implementation "org.jetbrains.lets-plot:lets-plot-kotlin-js:$lets_plot_kotlin_api_version"
}

Example applications

The lets-plot-mini-apps GitHub repository contains examples of using the Lets-Plot Kotlin API in JVM and Kotlin/JS projects.

You will also find similar "minimal" apps in this repository.

• JVM/Swing/Apache Batik: minimalDemo/Main.kt

• JVM/Swing/JavaFX Scene: minimalDemo/Main.kt

• Kotlin/JS: js-frontend-app

Frontend context

Frontend context is required for method show() in Figure interface to work properly. Both Plot and GGBunch classes in Lets-Plot Kotlin API implement Figure interface. Calling method show is typical for interactive notebook-like applications.

The following steps describe how to use Lets-Plot JVM "backend" in "browser" frontend context.

Add dependencies on maven artifacts

org.jetbrains.lets-plot:lets-plot-common:<lib version>
org.jetbrains.lets-plot-kotlin:lets-plot-kotlin-jvm:<api version>

Implement the jetbrains.letsPlot.FrontendContext interface:

import jetbrains.datalore.plot.PlotHtmlHelper
import jetbrains.letsPlot.FrontendContext

class MyNotebookContext: FrontendContext {
    override fun display(plotSpecRaw: MutableMap<String, Any>) {
        val html = PlotHtmlHelper.getDynamicDisplayHtmlForRawSpec(plotSpecRaw)
        // Append this `html` to your document ...
    }
}

Initialize lets-plot at runtime

Load Lets-Plot JS library to the user agent:

import jetbrains.datalore.plot.PlotHtmlHelper
import jetbrains.datalore.plot.PlotHtmlHelper.scriptUrl

val ver = .. // JS library version, for example: "1.2.3"
val html:String = PlotHtmlHelper.getDynamicConfigureHtml(scriptUrl(ver), false)
// include `configure html` in your document ...

Define Lets-Plot frontend context:

import jetbrains.letsPlot.LetsPlot
...
LetsPlot.frontendContext = MyNotebookContext()

License

Code and documentation released under the MIT license. Copyright © 2019-2021, JetBrains s.r.o.