Skip to content

Commit bf863e2

Browse files
LuboZLuboZ
authored
Merge pull request #9 from SmartBase-SK/develop
triv: #no-task wip: documentation
2 parents 806ca95 + 480878b commit bf863e2

File tree

13 files changed

+209
-78
lines changed

13 files changed

+209
-78
lines changed

‎docs/dashboard.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ class PurchaseChartWidget(SBAdminDashboardLineChartWidgetByDate):
6060
</Tabs>
6161

6262

63-
## 💡 Example #2: List Widget
63+
## 💡Example #2: List Widget
6464
This widget shows a paginated table of the latest purchases.
6565

6666
<Tabs groupId="2">

‎docs/detail/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Detail view",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Integration examples"
7+
}
8+
}

‎docs/detail/classes.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Fieldset Layout Classes
3+
sidebar_position: 3
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
### Fieldset Layout Classes
9+
SmartBase Admin supports additional customization of fieldset layout in detail views using the classes option.
10+
11+
Django SmatBase Admin currently supports one class: `DETAIL_STRUCTURE_RIGHT_CLASS`.
12+
13+
This class aligns the given fieldset to the right panel in the detail view layout (which typically has two columns: left and right).
14+
It is useful for grouping meta fields, status fields, or supplementary info away from the main form content.
15+
16+
## 💡Example: Defining class for `Base setting` fieldset
17+
<Tabs groupId="2">
18+
<TabItem value="code" label="Code">
19+
20+
```python title="catalog/sb_admin.py"
21+
@admin.register(Product, site=sb_admin_site)
22+
class ProductSBAdmin(SBAdmin):
23+
fieldsets = [
24+
(
25+
"Base settings",
26+
{
27+
"classes": [DETAIL_STRUCTURE_RIGHT_CLASS], # Fieldset Layout class
28+
"fields": [
29+
"is_active",
30+
"slug",
31+
"sku",
32+
"categories",
33+
"manufacturer",
34+
],
35+
},
36+
),
37+
]
38+
39+
#... other fields
40+
```
41+
42+
</TabItem>
43+
<TabItem value="screenshot" label="Result">
44+
45+
![Category sbadmin](/img/screenshots/right_class.png)
46+
47+
</TabItem>
48+
49+
</Tabs>
50+

‎docs/inlines.mdx‎ renamed to ‎docs/detail/fake_inlines.mdx‎

Lines changed: 8 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,23 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 2
3+
title: Fake Inlines
34
---
45
import Tabs from '@theme/Tabs';
56
import TabItem from '@theme/TabItem';
67

7-
# Inlines
8+
# Fake Inlines (SBAdminFakeInlineMixin)
89

9-
SmartBase Admin supports inlines in a powerful and flexible way using a set of custom classes extending Django’s built-in inline functionality.
10-
11-
Inlines allow related objects to be edited on the same page as the parent object. `django-smartbase-admin` enhances this with a polished UI,
12-
sortable support and tabular/stacked rendering options out of the box.
13-
14-
## Available Inline Classes
15-
16-
The following inline classes are available and can be used depending on your needs:
17-
18-
### SBAdminTableInline
19-
<Tabs groupId="1">
20-
<TabItem value="code" label="Code">
21-
```python title="catalog/sb_admin.py"
22-
class ProductImageInline(SBAdminTableInline):
23-
model = ProductImage
24-
fields = ("image", "alt_text")
25-
extra = 1
26-
```
27-
</TabItem>
28-
<TabItem value="screenshot" label="Result">
29-
30-
![Category sbadmin](/img/screenshots/sbadmin_table_inline.png)
31-
32-
</TabItem>
33-
</Tabs>
34-
35-
### SBAdminStackedInline
36-
<Tabs groupId="2">
37-
<TabItem value="code" label="Code">
38-
```python title="catalog/sb_admin.py"
39-
class ProductImageInline(SBAdminStackedInline):
40-
model = ProductImage
41-
fields = ("image", "alt_text")
42-
extra = 1
43-
```
44-
</TabItem>
45-
<TabItem value="screenshot" label="Result">
46-
47-
![Category sbadmin](/img/screenshots/SBAdminStackedInline.png)
48-
49-
</TabItem>
50-
</Tabs>
51-
52-
### Manage related objects that use GenericForeignKey
53-
`SBAdminGenericTableInline` and `SBAdminGenericStackedInline` are same as SBAdminTableInline and SBAdminStackedInline, but Generic inlines allow you to manage related objects that use GenericForeignKey.
54-
55-
## Fake inlines
56-
57-
### SBAdmin Fake Inlines (SBAdminFakeInlineMixin)
5810
SBAdminFakeInlineMixin is used to create inlines that are dynamically filtered — without needing a real ForeignKey relationship in the database. This is useful when you want to show related data based on some logic (e.g. "products from the same manufacturer") but don’t want to (or can't) define a hard model relation.
5911

6012
These inlines are rendered like standard inlines but do not impact database schema.
61-
#### 🛠 How it works
13+
## 🛠 How it works
6214
- Define inline which extending `SBAdminFakeInlineMixin`
6315
- For inline, define `filter_fake_inline_identifier_by_parent_instance(self, inline_queryset, parent_instance)`. This controls what queryset will be shown in the inline, based on the parent instance.
64-
#### 💡 Example
16+
17+
## 💡 Example: Products from the same manufacturer
18+
6519
This example showcases a fake inline for a Product admin page that lists other products from the same manufacturer.
20+
6621
```python title="catalog/sb_admin.py"
6722
class ProductSameManufacturerInline(SBAdminFakeInlineMixin, SBAdminTableInline):
6823
model = Product

‎docs/detail/inlines.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
7+
# Inlines
8+
9+
SmartBase Admin supports inlines in a powerful and flexible way using a set of custom classes extending Django’s built-in inline functionality.
10+
11+
Inlines allow related objects to be edited on the same page as the parent object. `django-smartbase-admin` enhances this with a polished UI,
12+
sortable support and tabular/stacked rendering options out of the box.
13+
14+
## Available Inline Classes
15+
16+
The following inline classes are available and can be used depending on your needs:
17+
18+
### SBAdminTableInline
19+
<Tabs groupId="1">
20+
<TabItem value="code" label="Code">
21+
```python title="catalog/sb_admin.py"
22+
class ProductImageInline(SBAdminTableInline):
23+
model = ProductImage
24+
fields = ("image", "alt_text")
25+
extra = 1
26+
```
27+
</TabItem>
28+
<TabItem value="screenshot" label="Result">
29+
30+
![Category sbadmin](/img/screenshots/sbadmin_table_inline.png)
31+
32+
</TabItem>
33+
</Tabs>
34+
35+
### SBAdminStackedInline
36+
<Tabs groupId="2">
37+
<TabItem value="code" label="Code">
38+
```python title="catalog/sb_admin.py"
39+
class ProductImageInline(SBAdminStackedInline):
40+
model = ProductImage
41+
fields = ("image", "alt_text")
42+
extra = 1
43+
```
44+
</TabItem>
45+
<TabItem value="screenshot" label="Result">
46+
47+
![Category sbadmin](/img/screenshots/SBAdminStackedInline.png)
48+
49+
</TabItem>
50+
</Tabs>
51+
52+
### Manage related objects that use GenericForeignKey
53+
`SBAdminGenericTableInline` and `SBAdminGenericStackedInline` are same as SBAdminTableInline and SBAdminStackedInline, but Generic inlines allow you to manage related objects that use GenericForeignKey.

‎docs/detail/tabs.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Detail View Tabs
3+
sidebar_position: 4
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
### Detail View Tabs
9+
10+
SmartBase Admin allows you to organize fieldsets and inlines into tabs using the sbadmin_tabs configuration
11+
12+
The sbadmin_tabs attribute is a dictionary where:
13+
- Keys are tab titles (strings),
14+
- Values are lists of Fieldset titles (strings, must match the first element of a fieldset tuple), or Inline classes (e.g., ProductImageInline).
15+
16+
## 💡Example: Creating 2 tabs view
17+
<Tabs groupId="2">
18+
<TabItem value="code" label="Code">
19+
20+
```python title="catalog/sb_admin.py"
21+
@admin.register(Product, site=sb_admin_site)
22+
class ProductSBAdmin(SBAdmin):
23+
model = Product
24+
inlines = [ProductImageInline]
25+
fieldsets = [
26+
(
27+
"Appearance",
28+
{
29+
"fields": ["name", "description", "price"]
30+
},
31+
),
32+
(
33+
"Base settings",
34+
{
35+
"classes": [DETAIL_STRUCTURE_RIGHT_CLASS],
36+
"fields": ["is_active", "slug", "sku", "categories", "manufacturer"],
37+
},
38+
),
39+
]
40+
41+
sbadmin_tabs = {
42+
"General": [
43+
"Appearance", # Refers to the fieldset titled "Appearance"
44+
"Base settings", # Refers to the fieldset titled "Base settings"
45+
],
46+
"Media": [
47+
ProductImageInline, # Refers to an inline model admin class
48+
],
49+
}
50+
```
51+
52+
</TabItem>
53+
<TabItem value="screenshot" label="Result">
54+
55+
![Category sbadmin](/img/screenshots/tabs.png)
56+
57+
</TabItem>
58+
59+
</Tabs>

‎docs/integrating_to_app.md‎ renamed to ‎docs/integrating.mdx‎

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Integrating to your Django App
2+
title: Integrate into Your Django App
33
sidebar_position: 2
44
---
55
import Tabs from '@theme/Tabs';
@@ -35,9 +35,11 @@ class ProductImageInline(SBAdminTableInline):
3535
You can learn more about inlines and different inline types in [🔗 Inlines section](/docs/inlines).
3636

3737

38-
### Product admin
38+
### 💡Example #1: Product admin
39+
3940
<Tabs groupId="1">
4041
<TabItem value="code" label="Code">
42+
4143
```python title="catalog/sb_admin.py"
4244
@admin.register(Product, site=sb_admin_site)
4345
class ProductSBAdmin(SBAdmin):
@@ -46,8 +48,8 @@ class ProductSBAdmin(SBAdmin):
4648
sbadmin_list_display = (
4749
"name",
4850
"sku",
49-
SBAdminField(name="price", title=_("Price")),
50-
SBAdminField(name="is_active", title=_("Active")),
51+
SBAdminField(name="price", title="Price"),
52+
SBAdminField(name="is_active", title="Active"),
5153
"manufacturer",
5254
)
5355
search_fields = ["name", "sku"]
@@ -64,9 +66,9 @@ class ProductSBAdmin(SBAdmin):
6466
},
6567
),
6668
(
67-
_("Base settings"),
69+
"Base settings",
6870
{
69-
"classes": [DETAIL_STRUCTURE_RIGHT_CLASS],
71+
"classes": [DETAIL_STRUCTURE_RIGHT_CLASS], # Fieldset Layout class
7072
"fields": [
7173
"is_active",
7274
"slug",
@@ -78,17 +80,21 @@ class ProductSBAdmin(SBAdmin):
7880
),
7981
]
8082
```
81-
</TabItem>
83+
</TabItem>
8284
<TabItem value="list" label="Result - List">
85+
8386
![Category sbadmin](/img/screenshots/product_list.png)
84-
</TabItem>
87+
88+
</TabItem>
8589
<TabItem value="detail" label="Result - Detail">
90+
8691
![Category sbadmin](/img/screenshots/product_detail.png)
87-
</TabItem>
92+
93+
</TabItem>
8894
</Tabs>
8995

90-
### Category admin
91-
<Tabs groupId="2">
96+
### 💡Example #2: Category admin
97+
<Tabs groupId="3">
9298
<TabItem value="code" label="Code">
9399
```python title="catalog/sb_admin.py"
94100
@admin.register(Category, site=sb_admin_site)
@@ -106,17 +112,17 @@ class CategorySBAdmin(SBAdmin):
106112
)
107113
]
108114
```
109-
</TabItem>
115+
</TabItem>
110116
<TabItem value="screenshot" label="Result - List">
111117
![Category sbadmin](/img/screenshots/category_list.png)
112-
</TabItem>
118+
</TabItem>
113119
<TabItem value="detail" label="Result - Detail">
114120
![Category sbadmin](/img/screenshots/category_detail.png)
115-
</TabItem>
121+
</TabItem>
116122
</Tabs>
117123

118-
### Manufacturer admin
119-
<Tabs groupId="3">
124+
### 💡Example #3: Manufacturer admin
125+
<Tabs groupId="4">
120126
<TabItem value="code" label="Code">
121127
```python title="catalog/sb_admin.py"
122128
@admin.register(Manufacturer, site=sb_admin_site)
@@ -133,11 +139,11 @@ class ManufacturerSBAdmin(SBAdmin):
133139
)
134140
]
135141
```
136-
</TabItem>
142+
</TabItem>
137143
<TabItem value="screenshot" label="Result - List">
138144
![Category sbadmin](/img/screenshots/manufacturer_list.png)
139-
</TabItem>
145+
</TabItem>
140146
<TabItem value="detail" label="Result - Detail">
141147
![Category sbadmin](/img/screenshots/manufacturer_detail.png)
142-
</TabItem>
148+
</TabItem>
143149
</Tabs>

‎docs/table/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Table",
3-
"position": 4,
3+
"position": 5,
44
"link": {
55
"type": "generated-index",
66
"description": "Table listing"

‎docs/table/filters.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ For example, administrator can save a view for only Active products
1818

1919
These saved views are accessible from the UI and persist across sessions, making the admin panel more user-friendly and workflow-driven.
2020

21-
## Usage example
21+
## 💡Usage example
2222

2323
Apply your preffered filters using the sidebar or column filters. Click the “Save View” button in the top-right corner of the list view interface.
2424
![Saved view sbadmin](/img/screenshots/save_view_1.png)

‎docs/table/getting_started.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ This allows you to display custom fields or apply formatting to existing fields
1919
- Saving filtered views
2020
- Performing bulk actions
2121

22-
## Defining the Table / List View
22+
## 💡Example: Defining the Table / List View
2323
To customize the list view, you define `sbadmin_list_display` with selected fields in your admin class:
2424

2525
<Tabs groupId="1">

0 commit comments

Comments
 (0)