` tags.
Add HTML attributes (classes, `data-*`, `title`, etc.) to elements in the changelist table (rows, cells).
1. Define `baton_cl_rows_attributes` method in your `ModelAdmin`. It takes `request` and `cl` (changelist instance) as arguments.
2. Return a JSON string dictionary. Keys usually match instance IDs. Values are dicts specifying attributes and selectors.
```python
# admin.py
import json
from django.utils.safestring import mark_safe
# from myapp.models import News # Assuming News model
class NewsAdmin(admin.ModelAdmin):
list_display = ('title', 'get_category_display', 'status') # Use the method name
def get_category_display(self, instance):
# Helper for targeting specific cells if needed by selector
if instance.category: # Check if category exists
return mark_safe(f'{instance.category.name}')
return "-" # Fallback if no category
get_category_display.short_description = 'Category'
get_category_display.admin_order_field = 'category' # Optional: if you want to allow ordering
def baton_cl_rows_attributes(self, request, cl):
data = {}
# Example 1: Add 'table-info' class to rows of news items in category ID 2
for news_item in cl.queryset.filter(category__id=2):
data[str(news_item.id)] = { # Ensure key is string for JSON
'class': 'table-info',
}
# Example 2: More complex - target a specific cell for a specific news item
# This example assumes you want to style a cell for a news item with ID=1 and category_id=1
try:
news_to_style = cl.queryset.get(id=1, category__id=1) # More specific lookup
data[f"customkey_cell_{news_to_style.id}"] = { # Key can be arbitrary if selector is specific
'class': 'table-success font-weight-bold', # Example: bold success
'data-category-name': news_to_style.category.name if news_to_style.category else '',
'title': f'Special: {news_to_style.title}',
# This selector targets the span created by get_category_display
# It assumes the changelist renders the output of get_category_display in a cell
'selector': f'#result_list tr input[name=_selected_action][value="{news_to_style.pk}"] ~ td .category-span-{news_to_style.category_id}',
'getParent': 'td', # Applies attributes to the parent of the found span
}
except cl.model.DoesNotExist: # Or your specific model DoesNotExist
pass # Item not found, or doesn't match criteria
return json.dumps(data)
```
**Rules for the returned dictionary values:**
* **Keys:** Typically the primary key of the model instance (as a string). If using a custom `selector` that doesn't rely on the instance ID, the key can be any unique string.
* **`selector`** (optional): CSS selector to find the target element.
* Default: `'#result_list tr input[name=_selected_action][value="' + key + '"]'` (targets the checkbox for the row of instance `key`). This works if `actions` are enabled.
* **`getParent`** (optional):
* Default: `'tr'` (attributes are applied to the row).
* You can specify another selector (e.g., `'td'`, `'.field-my_field'`) to find a parent of the element matched by `selector`.
* Set to `false` (boolean, not string) or an empty string to apply attributes directly to the element matched by `selector`.
* **Other keys:** Treated as HTML attributes to be added to the target element.
## ๐ Form Tabs
Organize your admin forms with tabs for fieldsets and inlines. Titles are derived automatically.
**Configuration (in `ModelAdmin.fieldsets` or `ModelAdmin.inlines`):**
```python
# admin.py
# from myapp.models import Attribute, Feature # Your models
# class AttributeInline(admin.StackedInline):
# model = Attribute # Your model
# extra = 1
# class FeatureInline(admin.StackedInline):
# model = Feature # Your model
# extra = 1
class ItemAdmin(admin.ModelAdmin):
# list_display = ('label', 'description', 'main_feature')
# inlines = [AttributeInline, FeatureInline] # Order of inlines matters for grouping
fieldsets = (
('Main Info', { # This fieldset will be the first tab (or part of it)
'fields': ('label', 'description'),
'classes': ('baton-tabs-init', 'order-0', 'baton-tab-group-main--inline-attribute'),
# 'baton-tabs-init': REQUIRED on the first fieldset to enable tabs.
# 'order-X': (Optional) Defines the tab order for this fieldset. Default 0.
# 'baton-tab-inline-MODELNAME': Creates a tab for the inline 'attribute' (lowercase model name).
# 'baton-tab-fs-CUSTOMNAME': Creates a tab for this fieldset (Main Info -> content_tab).
# 'baton-tab-group-GROUPNAME--item1type-ITEMNAME--item2type-ITEMNAME': Creates a group tab.
# GROUPNAME is arbitrary. ITEMNAME can be fs-FIELDSETNAME or inline-INLINEMODELNAME.
# Example: 'baton-tab-group-overview--fs-main_info--inline-attribute'
# This creates a group tab named "Overview" containing the "Main Info" fieldset and the "Attribute" inline.
'description': 'This is the main information for the item.'
}),
('Content Details', {
'fields': ('text', ),
'classes': ('baton-tab-fs-content', ), # This fieldset becomes a tab named "Content"
'description': 'Detailed content for the item.'
}),
('Technical Specs', {
'fields': ('main_feature', ),
# This fieldset is part of a group tab defined in the "Main Info" fieldset:
# e.g. 'baton-tab-group-main--inline-attribute--fs-tech--inline-feature' in 'Main Info' would group this.
'classes': ('baton-tab-fs-tech', ),
'description': 'Technical specifications and features.'
}),
)
```
**Rules for Tab Classes (applied to a fieldset's `classes` tuple):**
* **`baton-tabs-init`**: **Required** on the *first* fieldset definition to activate the tabbing system.
* **`order-X`**: (Optional, on the first fieldset) Sets the display order of the tab generated by the first fieldset itself. `X` is a number (e.g., `order-0`, `order-1`).
* **`baton-tab-inline-MODELNAME`**: Creates a separate tab for the inline whose model is `MODELNAME` (lowercase). If you used `related_name` for the inline, use `baton-tab-inline-RELATEDNAME`.
* **`baton-tab-fs-CUSTOMNAME`**: Creates a separate tab for the fieldset that *also* has the class `tab-fs-CUSTOMNAME`. `CUSTOMNAME` is an arbitrary name you choose.
* **`baton-tab-group-GROUPNAME--item1type-ITEM1NAME--item2type-ITEM2NAME...`**: Creates a group tab.
* `GROUPNAME` is an arbitrary name for your tab.
* `itemXtype` is either `fs` (for fieldset) or `inline`.
* `ITEMXNAME` is your `CUSTOMNAME` (for fieldsets) or `MODELNAME`/`RELATEDNAME` (for inlines).
* Example: `baton-tab-group-overview--fs-main_content--inline-attributes`
* Fieldsets without a `baton-tab-fs-*` class that are *not* part of a group will be appended to the first tab.
* To make a fieldset *always visible* (not part of any tab), add the class `tab-fs-none` to that fieldset.
**Other Tab Features:**
* If a form field has an error, the first tab containing that field is automatically opened.
* Deep link to a tab by adding its hash to the URL (e.g., `#inline-feature`, `#fs-content`, `#group-overview--fs-main_content--inline-attributes`). The hash is derived from the tab class names.
## ๐ Form Includes
>
> Requires browser support for HTML `` tags.
Embed custom templates near specific fields in change forms.
```python
# admin.py
class NewsAdmin(admin.ModelAdmin):
# ...
baton_form_includes = [
('myapp/admin_includes/datetime_helper.html', 'publication_date', 'top'),
('myapp/admin_includes/content_notes.html', 'body_content', 'above'),
('myapp/admin_includes/field_icon.html', 'title', 'right'),
]
```
**Positions:**
| Position | Description |
| :------- | :------------------------------------------- |
| `top` | Inside the field's form row, at the top. |
| `bottom` | Inside the field's form row, at the bottom. |
| `above` | Above the field's form row. |
| `below` | Below the field's form row. |
| `right` | Inline, to the right of the input field. |
The `{{ original }}` object (the model instance) is available in your included template. Works with tabs.
**Object Tools Includes:**
Inject templates into the object tools bar (top right of change form). Templates are injected inside a ``.
```python
# admin.py
class NewsAdmin(admin.ModelAdmin):
# ...
baton_form_object_tools_include = ('myapp/admin_includes/custom_object_action.html', 'left') # or 'right'
```
## ๐ค Collapsable Stacked Inlines
Make individual entries in `admin.StackedInline` collapsable.
Add `collapse-entry` to the inline's `classes`:
```python
# admin.py
class VideoInline(admin.StackedInline):
# model = Video # Your model
extra = 1
classes = ('collapse-entry', ) # Can be combined with Django's 'collapse'
```
To have the first entry expanded by default:
```python
# admin.py
class VideoInline(admin.StackedInline):
# model = Video # Your model
extra = 1
classes = ('collapse-entry', 'expand-first')
```
## ๐จ Themes & Customization
Easily customize Baton's appearance:
1. **CSS Variables:**
Create a `baton/css/root.css` file in one of your app's static directories (ensure this app is listed *before* `baton` in `INSTALLED_APPS`). Override any CSS variables defined in Baton's default [root.css](https://github.com/otto-torino/django-baton/tree/master/baton/static/baton/css/root.css).
Example:
```css
/* myapp/static/baton/css/root.css */
:root {
--bs-primary: #FF6347;
--bs-primary-rgb: 255,99,71;
--baton-sidebar-active-bg: #FF6347;
}
```
2. **Admin Themes:**
Create and manage themes directly from the admin site at `/admin/baton/batontheme/`. Only one theme can be active. Its CSS content (which should define CSS variables) will override the `baton/css/root.css` file.
> **Caution:** Theme content is marked safe and injected as-is. Be careful.
> โจ Find ready-to-use themes at [django-baton-themes](https://github.com/otto-torino/django-baton-themes).
3. **Heavy Customization (Recompiling JS App):**
For changes to primary/secondary Bootstrap colors or extensive modifications, you can recompile Baton's JavaScript application.
1. Clone `django-baton`.
2. Navigate to `django-baton/baton/static/baton/app/`.
3. Run `npm install`.
4. Edit `src/styles/_variables.scss` (and other SCSS/JS files as needed).
5. Run `npm run compile`.
6. Copy the compiled `dist/baton.min.js` to your project: `YOUR_APP/static/baton/app/dist/`.
7. Ensure `YOUR_APP` is listed *before* `baton` in `INSTALLED_APPS`.
For live development with automatic recompilation:
1. `cd django-baton/baton/static/baton/app/`
2. Run `npm run dev:baton` (starts Webpack dev server, usually on `http://localhost:8080`).
3. In your project's `admin/base_site.html` (you might need to override it), change the script source to point to the dev server:
```html
{# #}
```
Now, changes in the JS app will auto-update, just refresh your Django admin page.
## ๐งช Tests
Baton includes unit and end-to-end (e2e) tests using Selenium. To run e2e tests, ensure the test application (found in the `testapp` directory of the Baton repository) is running on `localhost:8000`.
## ๐ป Development
To contribute or develop locally:
1. **Set up the test app:**
```bash
cd testapp
python3 -m venv .virtualenv
source .virtualenv/bin/activate # On Windows: .virtualenv\Scripts\activate
pip install -e .. # django-baton itself
pip install Django
pip install -r test-requirements.txt
cd app
python manage.py migrate
python manage.py createsuperuser # If needed
python manage.py runserver
```
(Default login after `createsuperuser`: `admin` / `admin`, or as you defined).
2. **Enable live JS recompilation for development:**
* In `testapp/app/templates/admin/base_site.html`, switch the script source to Webpack dev server:
```html
{# #}
```
* In a new terminal, navigate to Baton's frontend app directory and start the dev server:
```bash
cd /path/to/your/django-baton/baton/static/baton/app/
npm install
npm run dev # For continuous development, watches for changes
```
Changes to Baton's frontend app will now auto-recompile. Refresh your browser to see them.
### Commands
Install `invoke` and `sphinx_rtd_theme` in your Python environment for documentation generation:
```bash
pip install invoke sphinx_rtd_theme
```
To generate documentation locally (from the root directory of the `django-baton` repository):
```bash
invoke docs
```
## ๐ค Contributing
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. We welcome contributions!
## ๐ Star History
[](https://star-history.com/#otto-torino/django-baton&Date)
|