API Reference

This page contains the complete API reference for Django Cruder.

Core Functions

cruder.crud_view(model_class, framework='bootstrap', **kwargs)

Create a complete CRUD view for a Django model with one function call.

This function generates a Django view that handles all CRUD operations: Create, Read, Update, Delete, and List with search and pagination.

Parameters:

• model_class (django.db.models.Model) – The Django model to create CRUD operations for.

• framework (str, optional) – CSS framework to use. Defaults to ‘bootstrap’. Supported: ‘bootstrap’, ‘bulma’.

• **kwargs –

  Additional configuration options:

  Display Options:

  exclude_fields (list): Fields to exclude from forms. list_fields (list): Fields to show in list view. readonly_fields (list): Fields that should be read-only in forms. readonly_mode (bool): Make entire interface read-only.

  Search & Pagination:

  search_fields (list): Fields to enable search across (OR logic). per_page (int): Items per page for pagination. Default: 25.

  Permissions:

  permissions (dict): Role-based permissions mapping.

  Example: {‘C’: [‘admin’], ‘U’: [‘admin’], ‘D’: [‘admin’]}

  permission_required (str): Django permission required for access.

  Templates:

  template_name (str): Custom template to use instead of defaults.

Returns:

A Django view function that handles all CRUD operations.

Return type:

function

Example

Basic usage:

>>> from cruder import crud_view
>>> from .models import Contact
>>>
>>> @login_required
>>> def contact_crud(request, pk=None, action='list'):
...     return crud_view(
...         Contact,
...         search_fields=['name', 'email', 'phone'],
...         readonly_fields=['created_at'],
...         per_page=10
...     )(request, pk, action)

With permissions:

>>> def secure_crud(request, pk=None, action='list'):
...     return crud_view(
...         MyModel,
...         permissions={
...             'C': ['admin', 'editor'],
...             'U': ['admin'],
...             'D': ['admin']
...         }
...     )(request, pk, action)

Note

The returned view function expects three parameters: request, pk (optional), and action (defaults to ‘list’). The action parameter determines which CRUD operation to perform: ‘list’, ‘create’, ‘view’, ‘edit’, or ‘delete’.

URL Helpers

cruder.urls.crud_urlpatterns(url_prefix, view_func, name_prefix=None)

Automatically generate all 5 CRUD URL patterns for a view function.

This helper function creates URL patterns for all standard CRUD operations: list, create, view, edit, and delete. This eliminates the need to manually define multiple URL patterns for each CRUD interface.

Parameters:

• url_prefix (str) – URL prefix for the CRUD routes (e.g., ‘contacts’, ‘products’). Should not include leading/trailing slashes.

• view_func (callable) – The view function that handles CRUD operations. This should be a function created with crud_view() or compatible.

• name_prefix (str, optional) – Prefix for URL names. If None, derived from url_prefix. Example: ‘contacts’ -> ‘contacts’, ‘contacts_create’, etc.

Returns:

List of Django URL patterns for all CRUD operations:

• GET /{url_prefix}/ (list)

• GET /{url_prefix}/create/ (create form)

• POST /{url_prefix}/create/ (create form submission)

• GET /{url_prefix}/<int:pk>/ (view details)

• GET /{url_prefix}/<int:pk>/edit/ (edit form)

• POST /{url_prefix}/<int:pk>/edit/ (edit form submission)

• GET /{url_prefix}/<int:pk>/delete/ (delete confirmation)

• POST /{url_prefix}/<int:pk>/delete/ (delete confirmation)

Return type:

list

Example

Basic usage:

>>> # urls.py
>>> from cruder.urls import crud_urlpatterns
>>> from . import views
>>>
>>> urlpatterns = [
...     path('', views.dashboard, name='dashboard'),
... ] + crud_urlpatterns('contacts', views.contact_crud)

Multiple CRUD interfaces:

>>> urlpatterns = [
...     path('', views.dashboard, name='dashboard'),
... ] + crud_urlpatterns('contacts', views.contact_crud)         ...   + crud_urlpatterns('products', views.product_crud)         ...   + crud_urlpatterns('orders', views.order_crud)

Custom name prefix:

>>> urlpatterns = crud_urlpatterns(
...     'admin/users',
...     views.user_crud,
...     name_prefix='admin_users'
... )

Note

The view function must accept the parameters (request, pk=None, action=’list’) where action can be ‘list’, ‘create’, ‘view’, ‘edit’, or ‘delete’.

Class-Based Views

class cruder.views.CRUDView(**kwargs)

Bases: View

Generic CRUD view class that handles all CRUD operations for a model

model = None

framework = 'bootstrap'

template_name = None

exclude_fields = None

list_fields = None

per_page = 25

search_fields = None

search_field = None

permission_required = None

readonly_fields = None

permissions = None

readonly_mode = False

has_crud_permission(user, operation)

Check if user has permission for CRUD operation

Parameters:

• user – Django user object

• operation – ‘C’, ‘R’, ‘U’, or ‘D’

Returns:

True if user has permission

Return type:

bool

dispatch(request, *args, **kwargs)

Check permissions before processing request

get(request, pk=None, action='list')

Handle GET requests for list, create, edit, view actions

post(request, pk=None, action='create')

Handle POST requests for create, update, delete actions

list_view(request)

Display list of model objects

create_view(request)

Display create form

create_post(request)

Handle create form submission

edit_view(request, pk)

Display edit form

edit_post(request, pk)

Handle edit form submission

detail_view(request, pk)

Display object details

delete_view(request, pk)

Display delete confirmation

delete_post(request, pk)

Handle delete confirmation

Form Generation

Form generation and rendering for Django models

class cruder.forms.CRUDForm(*args, **kwargs)

Dynamic form class for any Django model

__init__(*args, **kwargs)

class Meta

model = None

fields = '__all__'

base_fields = {}

declared_fields = {}

property media

Return all media required to render the widgets on this form.

cruder.forms.create_model_form(model_class, framework='bootstrap', exclude_fields=None)

Create a dynamic form class for a given model

cruder.forms.render_form(model_class, instance=None, framework='bootstrap', exclude_fields=None, action='', method='POST')

Render a complete form for a Django model

Parameters:

• model_class – Django model class

• instance – Model instance for editing (None for create)

• framework – CSS framework to use (‘bootstrap’, etc.)

• exclude_fields – List of fields to exclude

• action – Form action URL

• method – HTTP method (‘POST’, ‘GET’)

Returns:

HTML string of the complete form

cruder.forms.get_field_type(model_field)

Convert Django model field to HTML input type

Template Rendering

Template rendering for list views and data tables

cruder.templates.render_list(model_class, queryset=None, framework='bootstrap', fields=None, per_page=25, page=1, search_fields=None, search_query=None, base_url=None, url_pattern=None, permissions=None, search_field=None)

Render a list/table view for a Django model

Parameters:

• model_class – Django model class

• queryset – QuerySet to display (defaults to all objects)

• framework – CSS framework to use

• fields – List of fields to display (defaults to all)

• per_page – Number of items per page

• page – Current page number

• search_fields – List of fields to search in (OR logic)

• search_query – Search query string

• search_field – Single field to search in (deprecated, use search_fields)

Returns:

Dict with HTML and pagination info

cruder.templates.generate_pagination_html(page_obj, framework_class)

Generate pagination HTML

cruder.templates.generate_search_html(search_fields, search_query, framework_class)

Generate search form HTML

Framework Support

Base framework class for CSS framework support

class cruder.frameworks.base.BaseFramework

Base class for CSS framework implementations

name = 'base'

form_classes = {'checkbox': '', 'error': '', 'field': '', 'form': '', 'help_text': '', 'input': '', 'label': '', 'radio': '', 'select': '', 'submit': '', 'textarea': ''}

table_classes = {'actions': '', 'table': '', 'table_responsive': '', 'tbody': '', 'td': '', 'th': '', 'thead': '', 'tr': ''}

button_classes = {'danger': '', 'dark': '', 'info': '', 'light': '', 'primary': '', 'secondary': '', 'success': '', 'warning': ''}

get_form_field_html(field, field_type='text')

Generate HTML for a form field

get_table_html(headers, rows)

Generate HTML for a data table

get_button_html(text, button_type='primary', href=None)

Generate HTML for a button

Bootstrap 5 framework implementation

class cruder.frameworks.bootstrap.BootstrapFramework

Bootstrap 5 CSS framework implementation

name = 'bootstrap5'

form_classes = {'checkbox': 'form-check-input', 'error': 'invalid-feedback', 'field': 'mb-3', 'form': 'needs-validation', 'help_text': 'form-text text-muted', 'input': 'form-control', 'label': 'form-label', 'radio': 'form-check-input', 'select': 'form-select', 'submit': 'btn btn-primary', 'textarea': 'form-control'}

table_classes = {'actions': 'text-end', 'table': 'table table-dark table-striped table-hover', 'table_responsive': 'table-responsive', 'tbody': '', 'td': '', 'th': '', 'thead': '', 'tr': ''}

button_classes = {'danger': 'btn btn-danger', 'dark': 'btn btn-dark', 'info': 'btn btn-info', 'light': 'btn btn-light', 'primary': 'btn btn-primary', 'secondary': 'btn btn-secondary', 'success': 'btn btn-success', 'warning': 'btn btn-warning'}

get_form_field_html(field, field_type='text', errors=None, help_text=None)

Generate Bootstrap form field HTML

Bulma CSS framework implementation

class cruder.frameworks.bulma.BulmaFramework

Bulma CSS framework implementation

name = 'bulma'

form_classes = {'checkbox': 'checkbox', 'error': 'help is-danger', 'field': 'field', 'form': '', 'help_text': 'help', 'input': 'input', 'label': 'label', 'radio': 'radio', 'select': 'select', 'submit': 'button is-primary', 'textarea': 'textarea'}

table_classes = {'actions': 'has-text-right', 'table': 'table is-striped is-hoverable is-fullwidth', 'table_responsive': '', 'tbody': '', 'td': '', 'th': '', 'thead': '', 'tr': ''}

button_classes = {'danger': 'button is-danger', 'dark': 'button is-dark', 'info': 'button is-info', 'light': 'button is-light', 'primary': 'button is-primary', 'secondary': 'button', 'success': 'button is-success', 'warning': 'button is-warning'}

get_form_field_html(field, field_type='text', errors=None, help_text=None)

Generate Bulma form field HTML