Skip to content

Commit c02ec15

Browse files
lukasvinclavlukasvinclav
authored
docs: cohort tracker components (#895)
1 parent 93ca3dd commit c02ec15

File tree

5 files changed

+292
-97
lines changed

5 files changed

+292
-97
lines changed

‎docs/components/cohort.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Component - Cohort
3+
order: 2
4+
description: Cohort component in Unfold theme
5+
---
6+
7+
# Cohort component
8+
9+
The cohort component allows you to display cohort analysis data in a table format. It's useful for analyzing user behavior and retention over time. Unfold provides a default implementation of the cohort component. The only important parameter is the `data` parameter, which is a dictionary that contains a more complex data structure.
10+
11+
12+
## Default cohort component implementation in template
13+
14+
In template you can use the default implementation of the cohort component by using the following code below. The `component_class` parameter is the name of the component class that you will create in the next section and it will prepare the data for the cohort component.
15+
16+
```html
17+
{% load unfold %}
18+
19+
{% component "unfold/components/cohort.html" with component_class="MyCohortComponent" %}
20+
{% endcomponent %}
21+
```
22+
23+
If you don't want to use `component_class` parameter, you can prepare `data` in the dashboard callback function and use it like this:
24+
25+
```html
26+
{% load unfold %}
27+
28+
{% component "unfold/components/cohort.html" with data=my_data_variable data=my_data %}
29+
{% endcomponent %}
30+
```
31+
32+
## Custom cohort data preparation in component class
33+
34+
Below you can see an example of a component class that prepares the data for the cohort component. The component in template will receive the `data` parameter that is passed to the `get_context_data` method.
35+
36+
```python
37+
# admin.py
38+
39+
from unfold.components import BaseComponent
40+
41+
class MyCohortComponent(BaseComponent):
42+
def get_context_data(self, **kwargs):
43+
context = super().get_context_data(**kwargs)
44+
context.update({
45+
"data": DATA
46+
})
47+
return context
48+
```
49+
50+
## Data structure example
51+
52+
```python
53+
DATA = {
54+
"headers": [
55+
# Col 1 header
56+
{
57+
"title": "Title",
58+
"subtitle": "something", # Optional
59+
},
60+
],
61+
"rows": [
62+
# First row
63+
{
64+
# Row heading
65+
"header": {
66+
"title": "Title",
67+
"subtitle": "something", # Optional
68+
},
69+
"cols": [
70+
# Col 1 cell value
71+
{
72+
"value": "1",
73+
"subtitle": "something", # Optional
74+
}
75+
]
76+
},
77+
# Second row
78+
{
79+
"header": {
80+
# Row heading
81+
"title": "Title",
82+
"subtitle": "something", # Optional
83+
},
84+
# Col 1 cell value
85+
"cols": [
86+
{
87+
"value": "1",
88+
}
89+
]
90+
},
91+
]
92+
}
93+
```

‎docs/components/component_class.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Component class
3+
order: 1
4+
description: Component class for custom component preprocessing
5+
---
6+
7+
# Component class
8+
9+
Each component in Unfold theme has a component class that is responsible for preparing the data for the component. The component class is optional and if you don't want to use it, you can pass the data directly to the component in the template.
10+
11+
```python
12+
# admin.py
13+
14+
from unfold.components import BaseComponent
15+
16+
class MyComponent(BaseComponent):
17+
def get_context_data(self, **kwargs):
18+
context = super().get_context_data(**kwargs)
19+
context.update({
20+
"data": DATA
21+
})
22+
return context
23+
```
24+
25+
You can then use the component class in your template like this:
26+
27+
```html
28+
{% load unfold %}
29+
30+
{% component "unfold/components/my_component.html" with component_class="MyComponent" %}{% endcomponent %}
31+
```

‎docs/components/index.md‎

Lines changed: 0 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -3,100 +3,3 @@ title: Components
33
order: 8
44
description: Pre-build components to compose custom dashboard area in admin.
55
---
6-
7-
# Components
8-
9-
Unfold provides a set of already predefined templates to speed up overall dashboard development. These templates contain predefined design which matches global design style so there is no need to spend any time adjusting styles.
10-
11-
The biggest benefit of Unfold components is the possibility to nest them inside one template file provides an unlimited amount of possible combinations. Then each component includes `children` variable which contains a value specified in the parent component. Except for `children` variable, components can have multiple variables coming from the parent template as component variables. These parameters can be specified in the same as parameters when using `{% include with param1=value1 param2=value2 %}` template tag.
12-
13-
```html
14-
{% load unfold %}
15-
16-
{% component "unfold/components/flex.html" with col=1 %}
17-
{% component "unfold/components/card.html" %}
18-
{% component "unfold/components/title.html" %}
19-
Card Title
20-
{% endcomponent %}
21-
{% endcomponent %}
22-
{% endcomponent %}
23-
```
24-
25-
Below you can find a more complex example which is using multiple components and processing them based on the passed variables from the `DASHBOARD_CALLBACK`.
26-
27-
```html
28-
{% load i18n unfold %}
29-
30-
{% block content %}
31-
{% component "unfold/components/container.html" %}
32-
{% component "unfold/components/flex.html" with class="gap-4"%}
33-
{% component "unfold/components/navigation.html" with items=navigation %}
34-
{% endcomponent %}
35-
36-
{% component "unfold/components/navigation.html" with class="ml-auto" items=filters %}
37-
{% endcomponent %}
38-
{% endcomponent %}
39-
40-
{% component "unfold/components/flex.html" with class="gap-8 mb-8 flex-col lg:flex-row" %}
41-
{% for card in cards %}
42-
{% trans "Last 7 days" as label %}
43-
{% component "unfold/components/card.html" with class="lg:w-1/3" %}
44-
{% component "unfold/components/text.html" %}
45-
{{ card.title }}
46-
{% endcomponent %}
47-
48-
{% component "unfold/components/title.html" %}
49-
{{ card.metric }}
50-
{% endcomponent %}
51-
{% endcomponent %}
52-
{% endfor %}
53-
{% endcomponent %}
54-
{% endcomponent %}
55-
{% endblock %}
56-
```
57-
58-
## List of available components
59-
60-
| Component | Description | Arguments |
61-
| --------------------------------- | ------------------------------ | ------------------------------------ |
62-
| unfold/components/button.html | Basic button element | submit |
63-
| unfold/components/card.html | Card component | class, title, footer, label, icon |
64-
| unfold/components/chart/bar.html | Bar chart implementation | class, data, height, width |
65-
| unfold/components/chart/line.html | Line chart implementation | class, data, height, width |
66-
| unfold/components/container.html | Wrapper for settings max width | class |
67-
| unfold/components/flex.html | Flex items | class, col |
68-
| unfold/components/icon.html | Icon element | class |
69-
| unfold/components/navigation.html | List of navigation links | class, items |
70-
| unfold/components/progress.html | Percentual progress bar | class, value, title, description |
71-
| unfold/components/separator.html | Separator, horizontal rule | class |
72-
| unfold/components/table.html | Table | table, card_included, striped |
73-
| unfold/components/text.html | Paragraph of text | class |
74-
| unfold/components/title.html | Basic heading element | class |
75-
76-
77-
## Table component example
78-
79-
```python
80-
from typing import Dict
81-
from django.http import HttpRequest
82-
83-
84-
def dashboard_callback(request: HttpRequest) -> Dict:
85-
return {
86-
"table_data": {
87-
"headers": ["col 1", "col 2"],
88-
"rows": [
89-
["a", "b"],
90-
["c", "d"],
91-
]
92-
}
93-
}
94-
```
95-
96-
```html
97-
{% load unfold %}
98-
99-
{% component "unfold/components/card.html" with title="Card title" %}
100-
{% component "unfold/components/table.html" with table=table_data card_included=1 striped=1 %}{% endcomponent %}
101-
{% endcomponent %}
102-
```

‎docs/components/introduction.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Introduction to components
3+
order: 0
4+
description: Components overview for in Unfold theme
5+
---
6+
7+
# Introduction to components
8+
9+
Unfold provides a set of already predefined templates to speed up overall dashboard development. These templates contain predefined design which matches global design style so there is no need to spend any time adjusting styles.
10+
11+
The biggest benefit of Unfold components is the possibility to nest them inside one template file provides an unlimited amount of possible combinations. Then each component includes `children` variable which contains a value specified in the parent component. Except for `children` variable, components can have multiple variables coming from the parent template as component variables. These parameters can be specified in the same as parameters when using `{% include with param1=value1 param2=value2 %}` template tag.
12+
13+
```html
14+
{% load unfold %}
15+
16+
<div class="flex flex-col">
17+
{% component "unfold/components/card.html" %}
18+
{% component "unfold/components/title.html" %}
19+
Card Title
20+
{% endcomponent %}
21+
{% endcomponent %}
22+
</div>
23+
```
24+
25+
Below you can find a more complex example which is using multiple components and processing them based on the passed variables from the `DASHBOARD_CALLBACK`.
26+
27+
```html
28+
{% load i18n unfold %}
29+
30+
{% block content %}
31+
{% component "unfold/components/container.html" %}
32+
<div class="flex flex-col gap-4">
33+
{% component "unfold/components/navigation.html" with items=navigation %}
34+
{% endcomponent %}
35+
36+
{% component "unfold/components/navigation.html" with class="ml-auto" items=filters %}
37+
{% endcomponent %}
38+
</div>
39+
40+
<div class="grid grid-cols-3">
41+
{% for card in cards %}
42+
{% trans "Last 7 days" as label %}
43+
{% component "unfold/components/card.html" with class="lg:w-1/3" %}
44+
{% component "unfold/components/text.html" %}
45+
{{ card.title }}
46+
{% endcomponent %}
47+
48+
{% component "unfold/components/title.html" %}
49+
{{ card.metric }}
50+
{% endcomponent %}
51+
{% endcomponent %}
52+
{% endfor %}
53+
</div>
54+
{% endcomponent %}
55+
{% endblock %}
56+
```
57+
58+
## List of available components
59+
60+
| Component | Description | Arguments |
61+
| --------------------------------- | ------------------------------ | ------------------------------------ |
62+
| unfold/components/button.html | Basic button element | submit |
63+
| unfold/components/card.html | Card component | class, title, footer, label, icon |
64+
| unfold/components/chart/bar.html | Bar chart implementation | class, data, height, width |
65+
| unfold/components/chart/line.html | Line chart implementation | class, data, height, width |
66+
| unfold/components/container.html | Wrapper for settings max width | class |
67+
| unfold/components/flex.html | Flex items | class, col |
68+
| unfold/components/icon.html | Icon element | class |
69+
| unfold/components/navigation.html | List of navigation links | class, items |
70+
| unfold/components/progress.html | Percentual progress bar | class, value, title, description |
71+
| unfold/components/separator.html | Separator, horizontal rule | class |
72+
| unfold/components/table.html | Table | table, card_included, striped |
73+
| unfold/components/text.html | Paragraph of text | class |
74+
| unfold/components/title.html | Basic heading element | class |
75+
| unfold/components/tracker.html | Tracker component | data |
76+
| unfold/components/cohort.html | Cohort component | data |
77+
78+
79+
## Table component example
80+
81+
```python
82+
from typing import Dict
83+
from django.http import HttpRequest
84+
85+
86+
def dashboard_callback(request: HttpRequest) -> Dict:
87+
return {
88+
"table_data": {
89+
"headers": ["col 1", "col 2"],
90+
"rows": [
91+
["a", "b"],
92+
["c", "d"],
93+
]
94+
}
95+
}
96+
```
97+
98+
```html
99+
{% load unfold %}
100+
101+
{% component "unfold/components/card.html" with title="Card title" %}
102+
{% component "unfold/components/table.html" with table=table_data card_included=1 striped=1 %}{% endcomponent %}
103+
{% endcomponent %}
104+
```

‎docs/components/tracker.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Component - Tracker
3+
order: 3
4+
description: Tracker component in Unfold theme
5+
---
6+
7+
# Tracker component
8+
9+
The tracker component is a visual representation of data points. It's useful for displaying activity or progress over time. Each cell in the tracker can be colored differently and can include a tooltip for additional information.
10+
11+
## Default tracker component implementation in template
12+
13+
You can use the default implementation of the tracker component in your template with the following code. Like the cohort component, you can either use a component class to prepare the data or pass the data directly.
14+
15+
Using component class:
16+
17+
```html
18+
{% load unfold %}
19+
20+
{% component "unfold/components/tracker.html" with component_class="MyTrackerComponent" %}
21+
{% endcomponent %}
22+
```
23+
24+
Using data directly:
25+
26+
```html
27+
{% load unfold %}
28+
29+
{% component "unfold/components/tracker.html" with data=my_data_variable %}
30+
{% endcomponent %}
31+
```
32+
33+
## Custom tracker data preparation in component class
34+
35+
Below you can see an example of a component class that prepares the data for the tracker component. The component in template will receive the `data` parameter that is passed to the `get_context_data` method.
36+
37+
```python
38+
# admin.py
39+
40+
from unfold.components import BaseComponent
41+
42+
class MyTrackerComponent(BaseComponent):
43+
def get_context_data(self, **kwargs):
44+
context = super().get_context_data(**kwargs)
45+
context.update({
46+
"data": DATA
47+
})
48+
return context
49+
```
50+
51+
## Data structure example
52+
53+
```python
54+
DATA = [
55+
{
56+
"color": "bg-primary-400 dark:bg-primary-700",
57+
"tooltip": "Custom value 1",
58+
},
59+
{
60+
"color": "bg-primary-400 dark:bg-primary-700",
61+
"tooltip": "Custom value 2",
62+
}
63+
]
64+
```

0 commit comments

Comments
 (0)