Skip to content

Commit caf413f

Browse files
formanforman
committed
docs update
1 parent bee9bdd commit caf413f

File tree

5 files changed

+234
-193
lines changed

5 files changed

+234
-193
lines changed

‎docs/guide/contributors.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Contributor guide
2+
3+
As an application contributor you enhance an existing web application
4+
by UI contributions developed in Python. You implement a Python module
5+
that is consumed by (one of) the application's backend servers that
6+
implements expected Chartlets REST API as outlined above.
7+
8+
Your module is supposed to export one or more instances of the
9+
`chartlets.Extension` class. An extension object is a container for your
10+
UI contributions. It groups contributions that logically belong together.
11+
12+
As an example, see [`my_extension` of the demo](https://github.com/bcdev/chartlets/tree/main/chartlets.py/my_extension).
13+
14+
To develop an extension, follow these steps:
15+
16+
1. Create the extension object
17+
2. Create the contribution object
18+
3. Implement the contribution layout
19+
4. Implement the contribution callbacks
20+
5. Register the contribution
21+
22+
In the following the above steps are detailed further.
23+
24+
## Create the extension object
25+
26+
Your contributions to the application are published using a
27+
`chartlets.Extension` object that is exported from your extension module.
28+
29+
```python
30+
from chartlets import Extension
31+
32+
ext = Extension("my_dashboard")
33+
```
34+
35+
## Create the contribution object
36+
37+
In a submodule you create a contribution object from an application specific
38+
contribution, e.g., a `Panel`. Application-specific contribution classes
39+
are always derived from `chartlets.Contribution`.
40+
41+
```python
42+
from chartlets.demo import Panel
43+
44+
panel = Panel(title="Click Statistics")
45+
```
46+
47+
## Implement the contribution layout
48+
49+
In the submodule
50+
51+
```python
52+
@panel.layout()
53+
def get_layout(ctx):
54+
return Button(id="button", text="Click me")
55+
```
56+
57+
## Implement the contribution callback
58+
59+
In the submodule
60+
61+
```python
62+
from chartlets import Import, Output
63+
64+
@panel.callback(
65+
Input("button", "n_clicks"),
66+
Output("button", "text")
67+
)
68+
def on_button_click(ctx, n_clicks):
69+
n = n_clicks + 1
70+
s = {1: "st", 2: "nd", 3: "rd"}.get(n, "th")
71+
return f"Click me a {n}{s} time"
72+
```
73+
74+
## Register the contribution
75+
76+
In the extension module
77+
78+
```python
79+
from chartlets import Extension
80+
from .stats_panel import panel as stats_panel
81+
82+
ext = Extension("my_dashboard")
83+
ext.add(stats_panel)
84+
```

‎docs/guide/providers.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Providers guide
2+
3+
As an application provider you allow for enhancing your web application by
4+
server-side UI-contributions provided by an application contributor.
5+
6+
## How Chartlets works
7+
8+
Users write the widgets in, e.g. Python, and a REST server implements three
9+
endpoints to publish the widgets:
10+
11+
- `GET /contributions`: Called once after application UI starts up.
12+
Returns an object whose keys are contribution points (e.g., "panels")
13+
and whose values are arrays of contribution objects.
14+
- `POST /layout/{contribPoint}/{contribIndex}`:
15+
Called once for every contribution when it becomes visible in the UI.
16+
Returns the contribution's initial component tree.
17+
- `POST /callback`:
18+
Called when users interact with the component tree or on application
19+
state changes. Returns an array of contribution changes where each
20+
contribution change contains an array of actions to be applied to the
21+
component tree.
22+
23+
The following sequence diagram depicts how the library is supposed to
24+
work. The top shows the JavaScript frontend that uses this library.
25+
The bottom shows the lifeline of the backend REST server.
26+
27+
![sequence.png](../images/sequence.png)
28+
29+
## Backend integration
30+
31+
The Chartlets backend implementation is provided by the module
32+
`chartlets.controllers` of the Python package `chartlets`.
33+
It makes it easy to integrate the Chartlet endpoints in your preferred
34+
webserver framework, such as Flask, FastAPI, or Tornado.
35+
36+
The following steps are required to enable your web server to support
37+
UI-contributions:
38+
39+
1. Update project dependencies
40+
2. Implement the possible contributions
41+
3. Define the contributions points
42+
4. Load the extensions
43+
5. Publish the extensions
44+
45+
In the following the above steps are detailed further.
46+
47+
### Update project dependencies
48+
49+
Add the Python package `chartlets` to your project dependencies.
50+
Currently, Chartlets is available from PyPI only.
51+
52+
### Implement the possible contributions
53+
54+
Implement the application-specific contributions that users
55+
can add to their extensions.
56+
57+
As an example, see [`panel.py` of the demo](https://github.com/bcdev/chartlets/tree/main/chartlets.py/chartlets/demo/contribs/panel.py):
58+
59+
```python
60+
from chartlets import Contribution
61+
62+
63+
class Panel(Contribution):
64+
"""Panel contribution"""
65+
66+
def __init__(self, name: str, title: str | None = None):
67+
super().__init__(name, title=title)
68+
```
69+
70+
### Define the contributions points
71+
72+
Define the possible contribution points in your application.
73+
74+
As an example, see [`server.py` of the demo](https://github.com/bcdev/chartlets/tree/main/chartlets.py/chartlets/demo/server.py):
75+
76+
```python
77+
from chartlets import Extension
78+
from chartlets.demo.contribs import Panel
79+
80+
Extension.add_contrib_point("panels", Panel)
81+
```
82+
83+
### Load the extensions
84+
85+
Load the extensions that augment your application.
86+
87+
As an example, see [`server.py` of the demo](https://github.com/bcdev/chartlets/tree/main/chartlets.py/chartlets/demo/server.py):
88+
89+
```python
90+
from chartlets import ExtensionContext
91+
92+
ext_ctx = ExtensionContext.load(app_ctx, extension_refs)
93+
```
94+
95+
### Publish the extensions
96+
97+
Implement the Chartlets API in your application-specific webserver using
98+
the controller implementations in `chartlets.controllers`.
99+
100+
As an example, see [`server.py` of the demo](https://github.com/bcdev/chartlets/tree/main/chartlets.py/chartlets/demo/server.py).
101+
102+
## Frontend integration
103+
104+
The JavaScript package `chartlets` provides the types, actions, and hooks
105+
to allow for supporting server-side UI contributions in your React
106+
application.
107+
108+
As an example, see [the demo application](https://github.com/bcdev/chartlets/tree/main/chartlets.js/src/demo).
109+
110+
As an application provider you will need to perform the
111+
following steps:
112+
113+
1. Update project dependencies
114+
2. Configure the framework
115+
3. Implement derived application state
116+
4. Render the contributions
117+
118+
### Update project dependencies
119+
120+
Add the `chartlets` package as a dependency to your `package.json`.
121+
The package provides also TypeScript type definitions.
122+
There is nothing more to be considered.
123+
124+
### Configure the framework
125+
126+
Before the framework can be used it must configured
127+
using the `initializeFramework` function.
128+
129+
```TypeScript
130+
import { initializeFramework } "charlets"
131+
```
132+
133+
### Implement derived application state
134+
135+
### Render the contributions
136+
137+
## Adding new components

‎docs/index.md‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,25 +16,13 @@ and a
1616
- Uses [Material UI](https://mui.com/material-ui/) components and
1717
[Vega-Lite](https://vega.github.io/vega-lite/) charts.
1818

19-
## How it works
20-
21-
Users write the widgets in, e.g. Python, and a REST server implements three
22-
endpoints to publish the widgets:
23-
24-
- `GET /contributions`: Called once after application UI starts up.
25-
Returns an object whose keys are contribution points (e.g., "panels")
26-
and whose values are arrays of contribution objects.
27-
- `POST /layout/{contribPoint}/{contribIndex}`:
28-
Called once for every contribution when it becomes visible in the UI.
29-
Returns the contribution's initial component tree.
30-
- `POST /callback`:
31-
Called when users interact with the component tree or on application
32-
state changes. Returns an array of contribution changes where each
33-
contribution change contains an array of actions to be applied to the
34-
component tree.
35-
36-
The following sequence diagram depicts how the library is supposed to
37-
work. The top shows the JavaScript frontend that uses this library.
38-
The bottom shows the lifeline of the backend REST server.
39-
40-
![images/sequence.png](images/sequence.png)
19+
## Users
20+
21+
The Chartlets framework has two types of target users:
22+
23+
**Application contributors** develop new contributions
24+
for a specific web application that is powered by Chartlets.
25+
26+
**Application providers** develop the web application
27+
and the service that allows for server-side UI contributions
28+
using Chartlets.

0 commit comments

Comments
 (0)