Skip to content

Plugin Development Guide

Comprehensive guide to developing plugins for django-admin-deux.

Contents

1. Overview

Introduction to the plugin system architecture and key concepts.

Topics covered: - Why plugins? - Plugin discovery mechanism - Hook system overview - Feature validation - Built-in plugins (core and theme) - Common use cases

Start here if you're new to django-admin-deux plugins.

2. Creating Plugins

Step-by-step guide to building your first plugin.

Topics covered: - Quick start (Django app + djadmin_hooks.py) - Example: Export plugin implementation - Hook implementation patterns - Feature-driven development - Plugin structure recommendations - Testing plugins - Distribution and packaging

Start here to build your first plugin.

3. Hook Reference

Complete reference of all available hooks.

Hook categories: - Feature advertising - Action registration (general, bulk, record) - View customization (mixins, base classes, assets, attributes) - Dashboard hooks (future) - Action lifecycle (before/after execution) - Query and context modification

Use this as a reference when implementing specific hooks.

4. Custom Actions

Deep dive into creating custom actions.

Topics covered: - Action types (general, bulk, record) - Basic action structure - View-based actions (CRUD operations) - Permissions and visibility - Configurable actions - Testing actions - Advanced patterns (forms, modals, conditional actions)

Start here to add custom operations to your admin.

5. Custom Themes

Guide to creating custom themes.

Topics covered: - Theme architecture - Creating theme plugins - Asset management (CSS/JS) - Template overrides - CSS framework integration (Tailwind, Bootstrap) - Dark mode support - Multiple theme support - Testing themes

Start here to customize the admin UI.

6. Examples

Real-world plugin patterns and examples.

Examples included: - Export plugin (CSV/Excel) - Import plugin (bulk upload) - Audit log plugin - Search plugin - Filter plugin - Permissions plugin - Notification plugin - Multi-tenancy plugin - Versioning plugin

Use this for inspiration and common patterns.

Source Code

External Documentation

  • djp documentation: https://github.com/simonw/djp
  • pluggy documentation: https://pluggy.readthedocs.io/
  • Django CBV reference: https://ccbv.co.uk/

Project Documentation

Getting Started

For Plugin Authors

  1. Read Overview to understand the architecture
  2. Follow Creating Plugins to build your first plugin
  3. Reference Hook Reference as needed
  4. Browse Examples for patterns

For Action Developers

  1. Read Custom Actions for action patterns
  2. Study built-in actions in djadmin/plugins/core/actions.py
  3. Test using the webshop example: examples/webshop/

For Theme Developers

  1. Read Custom Themes for theming guide
  2. Study the default theme: djadmin/plugins/theme/
  3. Explore CSS framework integration patterns

Plugin Development Workflow

# 1. Create Django app for your plugin
python manage.py startapp myplugin

# 2. Add to INSTALLED_APPS
# settings.py: INSTALLED_APPS += ['myplugin']

# 3. Create plugin hook module
touch myplugin/djadmin_hooks.py

# 4. Implement hooks
# See creating-plugins.md for examples

# 5. Test plugin
pytest myplugin/tests/

# 6. Package for distribution
# See creating-plugins.md for packaging

Common Plugin Patterns

Use Case Hooks to Implement
Add custom actions djadmin_get_default_*_actions()
Modify querysets djadmin_modify_queryset()
Add context data djadmin_add_context_data()
Inject CSS/JS djadmin_get_action_view_assets()
Customize views djadmin_get_action_view_mixins()
Audit logging djadmin_before/after_action_execute()
Custom theme djadmin_provides_features() + assets

Contributing

Found a bug or have a feature request? Please open an issue on the project repository.

Want to contribute a plugin? Consider: 1. Publishing as a separate package (e.g., djadmin-export) 2. Adding to the community plugins list 3. Contributing documentation or examples

Support

  • Issues: GitHub issue tracker
  • Discussions: GitHub discussions
  • Documentation: This guide and project README

License

django-admin-deux is released under the MIT License. Plugins can use any compatible license.