Home

Advanced CRUD for perfectionists with deadlines. An opinionated Django package for shipping production-grade CRUD screens with filtering, bulk operations, inline editing, and async workflows.

PowerCRUD extends Neapolitan’s view layer with the practical infrastructure needed for real operational interfaces.

Where to start

1. First view online

   • Getting Started for installation and base template requirements.
   • Setup & Core CRUD basics for the first full view configuration.
   • Filtering for default vs optional filters, sorting, null helpers, and custom filterset behavior.

2. Improve day-to-day editing

   • Inline editing to adjust rows in place.
   • Forms for generated vs custom forms, contextual display fields, disabled inputs, and parent/child dropdown queryset scoping.
   • Bulk editing (synchronous) for multi-record updates with validation controls.
   • Persistence Hooks for moving validated writes into app services without scattering save logic.

3. Handle long-running work

   • Async Manager explains locks, progress storage, and reusable helpers.
   • Bulk editing (async) queues jobs through django-q2.
   • Async Bulk Persistence shows how to keep sync and async bulk update behavior aligned.
   • Async dashboard add-on persists lifecycle data.

4. Tune styling and behaviour

   • Styling & Tailwind covers framework options and safelists.
   • Customisation tips shows template overrides, extra actions, and mixin hooks.
   • PowerCRUD Concepts puts the setup guides in perspective and explains the mental model behind surfaces, field intent, actions, presentation, selection, bulk work, and async work.
   • Structured API explains when to use PowerField, PowerAction, and PowerButton for repeated field and action config.
   • Advanced Guides collects deeper implementation walkthroughs for trickier extension patterns, including the optional saved favourites add-on.
   • PowerCRUD Recipes shows Base Configuration API patterns you can adapt.

Two API styles

PowerCRUD's Base Configuration API uses class attributes, hooks, lists, and dictionaries directly. The Structured Declaration API uses PowerField, PowerAction, and PowerButton to group repeated intent into reusable declaration objects. Both styles use the same runtime behavior.

What ships in the box

• Enhanced CRUD views with property support, field exclusions, and customizable display options
• Modal-based create, edit, and delete forms with HTMX integration
• Inline row editing with HTMX-powered reactive updates and conflict detection
• Sortable tables with pagination and responsive column controls
• Reactive filtering and search with M2M logic and custom queryset handling
• Bulk edit and delete operations with atomic transactions and async processing
• Async task management with progress tracking, conflict locks, and lifecycle monitoring
• daisyUI/Tailwind styling with template flexibility and framework extension points
• Crispy forms integration and HTML5 widgets
• Management commands for template bootstrapping and asset utilities
• Comprehensive sample app and Docker development setup

Async in brief

1. View reserves locks and enqueues a worker.
2. Worker runs via django-q2, updates progress, and returns results.
3. Completion hook clears locks, emits lifecycle events, and optionally records dashboard rows.
4. Cleanup command or schedule reconciles anything stuck.

See Async architecture for details.

Reference map

• Base Configuration API reference: config_options.md
• Concepts guide: concepts.md
• Structured API guide: Choosing an API Style
• PowerField guide/reference: guide, reference
• PowerAction and PowerButton guide/reference: guide, reference
• Hooks reference: hooks.md
• Complete class example: complete_example.md
• Tooling: dockerised_dev.md, mgmt_commands.md, testing.md
• Sample app overview: sample_app.md