Skip to content

Commit 2ed3a9d

Browse files
koperagenkoperagen
committed
Documentation for rendering
1 parent ba9182c commit 2ed3a9d

File tree

6 files changed

+127
-14
lines changed

6 files changed

+127
-14
lines changed

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,11 @@ public fun <T> DataFrame<T>.toHTML(
211211
return tableHtml + DataFrameHtmlData("", bodyFooter, "")
212212
}
213213

214-
public data class DataFrameHtmlData(val style: String, val body: String, val script: String) {
214+
/**
215+
* Container for HTML page data in form of String
216+
* Can be used to compose rendered dataframe tables with additional HTML elements
217+
*/
218+
public data class DataFrameHtmlData(val style: String = "", val body: String = "", val script: String = "") {
215219
@Language("html")
216220
override fun toString(): String = """
217221
<html>
@@ -268,6 +272,10 @@ public data class DataFrameHtmlData(val style: String, val body: String, val scr
268272
}
269273
}
270274

275+
/**
276+
* @param rowsLimit null to disable rows limit
277+
* @param cellContentLimit -1 to disable content trimming
278+
*/
271279
public data class DisplayConfiguration(
272280
var rowsLimit: Int? = 20,
273281
var nestedRowsLimit: Int? = 5,

‎core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
package org.jetbrains.kotlinx.dataframe.samples.api
2+
3+
import java.io.File
4+
import org.jetbrains.kotlinx.dataframe.api.reorderColumnsByName
5+
import org.jetbrains.kotlinx.dataframe.api.sortBy
6+
import org.jetbrains.kotlinx.dataframe.api.sortByDesc
7+
import org.jetbrains.kotlinx.dataframe.io.DataFrameHtmlData
8+
import org.jetbrains.kotlinx.dataframe.io.DisplayConfiguration
9+
import org.jetbrains.kotlinx.dataframe.io.toHTML
10+
import org.jetbrains.kotlinx.dataframe.io.toStandaloneHTML
11+
import org.junit.Ignore
12+
import org.junit.Test
13+
14+
class Render : TestBase() {
15+
@Test
16+
@Ignore
17+
fun useRenderingResult() {
18+
// SampleStart
19+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).openInBrowser()
20+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).writeHTML(File("/path/to/file"))
21+
// SampleEnd
22+
}
23+
24+
@Test
25+
fun composeTables() {
26+
// SampleStart
27+
val df1 = df.reorderColumnsByName()
28+
val df2 = df.sortBy { age }
29+
val df3 = df.sortByDesc { age }
30+
31+
listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df -> acc + df.toHTML() }
32+
// SampleEnd
33+
}
34+
35+
@Test
36+
fun configureCellOutput() {
37+
// SampleStart
38+
df.toHTML(DisplayConfiguration(cellContentLimit = -1))
39+
// SampleEnd
40+
}
41+
}

‎docs/StardustDocs/d.tree

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,9 @@
169169
<toc-element topic="toMap.md"/>
170170
</toc-element>
171171
<toc-element topic="rendering.md">
172+
<toc-element topic="toHTML.md"/>
172173
<toc-element topic="format.md"/>
174+
<toc-element topic="jupyterRendering.md"/>
173175
</toc-element>
174176
</toc-element>
175177
<toc-element topic="gradleReference.md"/>

‎docs/StardustDocs/topics/jupyterRendering.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[//]: # (title: Jupyter Notebooks)
2+
3+
Rendering in Jupyter Notebooks can be configured using `dataFrameConfig.display` value.
4+
Have a look at [toHTML](toHTML.md#configuring-display-for-individual-output) function to configure output for single cell
5+
6+
### Content limit length
7+
8+
Content in each cell gets truncated to 40 characters by default.
9+
This can be changed by setting `cellContentLimit` to a different value on the display configuration.
10+
11+
```kotlin
12+
dataFrameConfig.display.cellContentLimit = 100
13+
```

‎docs/StardustDocs/topics/rendering.md

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,6 @@
11
[//]: # (title: Rendering)
22

3-
// TODO
3+
This section describes APIs that you can use to render DataFrame types and configure display.
44

5-
## Jupyter Notebooks
6-
7-
Rendering in Jupyter Notebooks can be configured using `dataFrameConfig.display` value.
8-
9-
### Content limit length
10-
11-
Content in each cell gets truncated to 40 characters by default.
12-
This can be changed by setting `cellContentLimit` to a different value on the display configuration.
13-
14-
```kotlin
15-
dataFrameConfig.display.cellContentLimit = 100
16-
```
5+
* [`toHTML`](toHTML.md) — operation for rendering DataFrame object to an HTML table
6+
* [`Jupyter Notebooks`](jupyterRendering.md) — configuration specific to notebook environments

‎docs/StardustDocs/topics/toHTML.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
[//]: # (title: toHTML)
2+
3+
<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Render-->
4+
5+
DataFrame can be rendered to HTML.
6+
Rendering of hierarchical tables in HTML is supported by JS and CSS definitions
7+
that can be found in project resources.
8+
9+
Depending on your environment there can be different ways to use result of `toHTML` functions
10+
11+
## IntelliJ IDEA
12+
13+
### Working with result
14+
15+
Following function produces HTML that includes JS and CSS definitions. It can be displayed in the browser and has parameters for customization.
16+
17+
<!---FUN useRenderingResult-->
18+
19+
```kotlin
20+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).openInBrowser()
21+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).writeHTML(File("/path/to/file"))
22+
```
23+
24+
<!---END-->
25+
26+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).openInBrowser()
27+
df.toStandaloneHTML(DisplayConfiguration(rowsLimit = null)).writeHTML(File("/path/to/file"))
28+
29+
### Composing multiple tables
30+
31+
`toHTML` and `toStandaloneHTML` return composable `DataFrameHtmlData`. You can use it to include additional scripts, elements, styles on final page or just merge together multiple tables
32+
33+
<!---FUN composeTables-->
34+
35+
```kotlin
36+
val df1 = df.reorderColumnsByName()
37+
val df2 = df.sortBy { age }
38+
val df3 = df.sortByDesc { age }
39+
40+
listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df -> acc + df.toHTML() }
41+
```
42+
43+
<!---END-->
44+
45+
## Jupyter Notebooks
46+
47+
### Configuring display for individual output
48+
49+
`toHTML` is useful if you want to configure display for single cell, not whole notebook as described in section for [Jupyter Notebooks](jupyterRendering.md)
50+
51+
<!---FUN configureCellOutput-->
52+
53+
```kotlin
54+
df.toHTML(DisplayConfiguration(cellContentLimit = -1))
55+
```
56+
57+
<!---END-->
58+
59+

0 commit comments

Comments
 (0)