Skip to content

Commit

Permalink
feat: implement editable dataframe to manage dataframe editor component
Browse files Browse the repository at this point in the history
* feat: implement record_remove on EditableDataframe
* docs: write documentation section about dataframe
  • Loading branch information
FabienArcellier committed Jul 6, 2024
1 parent 5be456f commit 25e6af2
Show file tree
Hide file tree
Showing 3 changed files with 355 additions and 25 deletions.
102 changes: 102 additions & 0 deletions docs/framework/dataframe.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: "Dataframe"
---

**writer framework places the dataframe at the core of the application**. This is a great way for modeling a complex and massive data system.
it offers components as `dataframe` and `dataframe editor` to manipulate dataframes. These components allow you to visualize and interact with dataframes.

| compatibility | dataframe | dataframe editor |
|--------------------|---------------------------------------|------------------|
| `pandas.DataFrame` | x | x |
| `polar.DataFrame` | x | x |
| `list of records` | x (with `EditableDataframe`) | x |

### Use a dataframe

**a dataframe is simply added to the state**. A component like `dataframe` will be able to display it.

```python
import pandas
import writer as wf

wf.init_state({
'mydf': pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
})
```

### Prepare a dataframe for editing

**writer provides a helper to facilitate dataframe manipulatione**. This helper makes it easier to write event handlers such as adding a line,
deleting it or modifying a value, etc...

```python
import pandas
import writer as wf

df = pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})

wf.init_state({
'mydf': wf.EditableDataframe(df)
})
```

<Info>An `EditableDataframe` value can also be displayed in the `dataframe` component</Info>

#### Handle events from a dataframe editor

**The dataframe editor emits events when an action is performed**. You must subscribe to events to integrate changes to the state of the application.

```python
import pandas
import writer as wf

# Subscribe this event handler to the `wf-dfeditor-add` event
def on_record_add(state, payload):
payload['record']['sales'] = 0 # default value inside the dataframe
state['mydf'].record_add(payload)


# Subscribe this event handler to the `wf-dfeditor-update` event
def on_record_change(state, payload):
state['mydf'].record_update(payload)


# Subscribe this event handler to the `wf-dfeditor-action` event
def on_record_action(state, payload):
"""
This event corresponds to a quick action in the drop-down menu to the left of the dataframe.
"""
if payload.action == 'remove':
state['mydf'].record_remove(payload)
if payload.action == 'important':
state['mydf'].record(payload.id).update('flag', True) # update the column flag of the dataframe to true, trigger une mutation record_update
if payload.action == 'open':
state['record'] = state['df'].record(payload.id)

df = pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})

wf.init_state({
'mydf': wf.EditableDataframe(df)
})
```

#### Alternative to pandas.DataFrame

`EditableDataframe` can also be used with a polar dataframe and list of records.

```python
import pandas
import polars

import writer as wf

panda_df = pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
polars_df = polars.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
list_of_records = [{'a': 1, 'b': 4}, {'a': 2, 'b': 5}, {'a': 3, 'b': 6}]

wf.init_state({
'mypandas': wf.EditableDataframe(panda_df),
'mypolars': wf.EditableDataframe(polars_df),
'mylistofrecords': wf.EditableDataframe(list_of_records)
})
```
Loading

0 comments on commit 25e6af2

Please sign in to comment.