django-spire 0.23.4__py3-none-any.whl

django_spire/contrib/constructor/django_model_constructor.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Type, Generic, TypeVar
+
+from django.db.models import Model
+
+from django_spire.contrib.constructor.constructor import BaseConstructor
+
+TypeDjangoModel = TypeVar('TypeDjangoModel', bound=Model, covariant=True)
+
+
+class BaseDjangoModelConstructor(
+    BaseConstructor[TypeDjangoModel],
+    ABC,
+    Generic[TypeDjangoModel]
+):
+    @property
+    def _model_obj_id_is_empty(self) -> bool:
+        return self.obj.id is None or self.obj.id == 0 or self.obj.id == ''
+
+    @property
+    def _model_obj_pk_is_empty(self) -> bool:
+        return self.obj.pk is None or self.obj.pk == 0 or self.obj.pk == ''
+
+    @property
+    def model_obj_is_created(self) -> bool:
+        return self._obj_is_valid and not self.model_obj_is_new
+
+    @property
+    def model_obj_is_new(self) -> bool:
+        return self._model_obj_id_is_empty or self._model_obj_pk_is_empty
+
+    @property
+    def obj_class(self) -> Type[TypeDjangoModel]:
+        return super().obj_class
+
+    @property
+    def _obj_is_valid(self) -> bool:
+        return super()._obj_is_valid and isinstance(self.obj, Model) and issubclass(self._obj_type, Model)

django_spire/contrib/constructor/exceptions.py

@@ -0,0 +1,5 @@
+from django_spire.exceptions import DjangoSpireException
+
+
+class ConstructorException(DjangoSpireException):
+    pass

django_spire/contrib/form/confirmation_forms.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Callable, TYPE_CHECKING
+
+from django import forms
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+
+
+class ConfirmationForm(forms.Form):
+    pass
+
+class DeleteConfirmationForm(ConfirmationForm):
+    should_delete = forms.BooleanField(required=False)
+
+    def __init__(self, *args, obj = None, **kwargs):
+        if obj is None:
+            message = 'Passing an object to DeleteConfirmationForm is required.'
+            raise ValueError(message)
+
+        self.obj = obj
+
+        super().__init__(*args, **kwargs)
+
+    def save(
+        self,
+        user: User,
+        verbs: tuple,
+        delete_func: Callable | None = None,
+        activity_func: Callable | None = None,
+        auto_add_activity: bool = True
+    ) -> None:
+        if delete_func is not None:
+            delete_func()
+        else:
+            self.obj.set_deleted()
+
+        if activity_func is not None:
+            activity_func()
+        elif hasattr(self.obj, 'add_activity') and auto_add_activity:
+            self.obj.add_activity(
+                user=user,
+                verb=verbs[1],
+                information=f'{user.get_full_name()} {verbs[1].lower()} {self.obj._meta.verbose_name} "{self.obj}".'
+            )

django_spire/contrib/form/templates/django_spire/contrib/form/button/form_submit_button.html

@@ -0,0 +1,46 @@
+<div x-data="{
+    loading: false,
+    init() {
+        this.loading = false
+    },
+    async submit (form) {
+        // The validate_form function must be on the parent element and handles any additional client side validation.
+        // This logic checks for a validate function and calls it if it exists
+        if (form.checkValidity() && ('validate_form' in this && await validate_form(form) || !('validate_form' in this))) {
+            this.loading = true
+            toggle_loading_overlay()
+            form.submit()
+        }
+        else {
+            form.reportValidity()
+        }
+    }
+ }">
+    <button
+        class="btn btn-app-primary {{ button_class }}"
+        id="form-submit-button"
+        x-show="loading === false"
+        @click.prevent="await submit($el.form)"
+    >
+        {% if button_text %}
+            {{ button_text }}
+        {% elif x_button_text %}
+            <span x-text="{{ x_button_text }}"></span>
+        {% else %}
+            Submit
+        {% endif %}
+    </button>
+    <div
+        class="btn btn-app-primary"
+        x-show="loading"
+        x-cloak
+    >
+        <div
+            class="spinner-border spinner-border-sm"
+            role="status"
+            x-transition
+        >
+        </div>
+        <span>Loading...</span>
+    </div>
+</div>

django_spire/contrib/form/utils.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.contrib import messages
+
+if TYPE_CHECKING:
+    from django.core.handlers.wsgi import WSGIRequest
+    from django.forms import Form
+
+
+def form_errors_as_list(form: Form) -> list[str]:
+    form_errors = []
+
+    for field_name, error_list in form.errors.items():
+        for error in error_list.data:
+            error_message = ''
+
+            if field_name != '__all__':
+                error_message += f'{field_name.title()}: '
+
+            if hasattr(error, 'message_responses'):
+                error_message += f'{" ".join(error.message_responses)}'
+
+            elif hasattr(error, 'messages'):
+                error_message += f'{" ".join(error.messages)}'
+
+            else:
+                message = 'Error message not found.'
+                raise Exception(message)
+
+            form_errors.append(error_message)
+
+    return form_errors
+
+
+def show_form_errors(request: WSGIRequest, *forms: Form) -> None:
+    for form in forms:
+        for error in form_errors_as_list(form):
+            messages.error(request=request, message=error)

django_spire/contrib/generic_views/__init__.py

@@ -0,0 +1,7 @@
+from django_spire.contrib.generic_views.modal_views import dispatch_modal_delete_form_content
+from django_spire.contrib.generic_views.portal_views import template_view
+
+__all__ = [
+    'dispatch_modal_delete_form_content',
+    'template_view',
+]

django_spire/contrib/generic_views/modal_views.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.http import HttpResponseRedirect
+from django.template.response import TemplateResponse
+
+from django_spire.core.redirect import safe_redirect_url
+from django_spire.contrib.form.confirmation_forms import DeleteConfirmationForm
+from django_spire.contrib.form.utils import show_form_errors
+
+if TYPE_CHECKING:
+    from django.core.handlers.wsgi import WSGIRequest
+
+
+def dispatch_modal_delete_form_content(
+    request: WSGIRequest,
+    *,
+    obj,
+    form_action: str,
+    context_data: dict | None = None,
+    activity_func: callable | None = None,
+    auto_add_activity: bool = True,
+    delete_func: callable | None = None,
+    # Present and past tense of verb
+    verbs: tuple[str, str] = ('delete', 'deleted'),
+    return_url: str | None = None,
+    template: str = 'django_spire/modal/content/dispatch_modal_delete_confirmation_content.html'
+) -> HttpResponseRedirect | TemplateResponse:
+    if context_data is None:
+        context_data = {}
+
+    model_name = obj._meta.model._meta.verbose_name
+
+    if request.method == 'POST':
+        form = DeleteConfirmationForm(request.POST, obj=obj)
+
+        if form.is_valid():
+            form.save(
+                user=request.user,
+                verbs=verbs,
+                delete_func=delete_func,
+                activity_func=activity_func,
+                auto_add_activity=auto_add_activity
+            )
+
+        else:
+            show_form_errors(request, form)
+
+        if return_url is None:
+            return_url = safe_redirect_url(request)
+
+        return HttpResponseRedirect(return_url)
+
+    base_context_data = {
+        'form_title': f'{model_name} - {verbs[0].title()} {obj}',
+        'form_action': form_action,
+        'form_description': f'Are you sure you would like to {verbs[0].lower()} {model_name} "{obj}"?',
+    }
+
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(
+        request,
+        template=template,
+        context=context_data
+    )

django_spire/contrib/generic_views/portal_views.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TYPE_CHECKING
+
+from django.db.models import QuerySet
+from django.http import HttpResponseRedirect
+from django.template.response import TemplateResponse
+
+from django_spire.contrib.breadcrumb.breadcrumbs import Breadcrumbs
+from django_spire.contrib.form.confirmation_forms import DeleteConfirmationForm
+
+if TYPE_CHECKING:
+    from django.core.handlers.wsgi import WSGIRequest
+
+
+# Takes breadcrumb as parameter and returns None
+BreadCrumbCallable = Callable[[Breadcrumbs], None]
+
+
+def detail_view(
+    request: WSGIRequest,
+    *,
+    context_data: dict | None = None,
+    breadcrumbs_func: BreadCrumbCallable | None = None,
+    obj,
+    template: str
+) -> TemplateResponse:
+    if context_data is None:
+        context_data = {}
+
+    breadcrumbs = Breadcrumbs()
+
+    if breadcrumbs_func is None:
+        breadcrumbs.add_obj_breadcrumbs(obj)
+    else:
+        breadcrumbs_func(breadcrumbs)
+
+    base_context_data = {
+        'page_title': obj._meta.model._meta.verbose_name,
+        'page_description': obj.__str__(),
+        'breadcrumbs': breadcrumbs
+    }
+
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(
+        request,
+        template=template,
+        context=context_data
+    )
+
+
+def delete_form_view(
+    request: WSGIRequest,
+    *,
+    context_data: dict | None = None,
+    obj,
+    activity_func: callable | None = None,
+    auto_add_activity: bool = True,
+    breadcrumbs_func: BreadCrumbCallable | None = None,
+    delete_func: callable | None = None,
+    # Present and past tense of verb
+    verbs: tuple[str, str] = ('delete', 'deleted'),
+    return_url: str,
+    template: str = 'django_spire/page/delete_confirmation_form_page.html'
+) -> HttpResponseRedirect | TemplateResponse:
+    if context_data is None:
+        context_data = {}
+
+    model_name = obj._meta.model._meta.verbose_name
+
+    if request.method == 'POST':
+        form = DeleteConfirmationForm(data=request.POST, obj=obj)
+
+        if form.is_valid():
+            if form.cleaned_data['should_delete']:
+                if delete_func is not None:
+                    delete_func()
+                else:
+                    obj.set_deleted()
+
+                if activity_func is not None:
+                    activity_func()
+                elif hasattr(obj, 'add_activity') and auto_add_activity:
+                    obj.add_activity(
+                        user=request.user,
+                        verb=verbs[1],
+                        information=f'{request.user.get_full_name()} {verbs[1].lower()} {model_name} "{obj}".'
+                    )
+
+            return HttpResponseRedirect(return_url)
+    else:
+        form = DeleteConfirmationForm(obj=obj)
+
+    breadcrumbs = Breadcrumbs()
+
+    if breadcrumbs_func is None:
+        breadcrumbs.add_obj_breadcrumbs(obj)
+        breadcrumbs.add_breadcrumb(name=verbs[0].title())
+    else:
+        breadcrumbs_func(breadcrumbs)
+
+    base_context_data = {
+        'page_title': obj.__str__(),
+        'page_description': verbs[0].title(),
+        'breadcrumbs': breadcrumbs,
+        'form': form,
+        'form_title': f'{verbs[0].title()} {obj}',
+        'form_description': f'Are you sure you would like to {verbs[0].lower()} {model_name} "{obj}"?',
+    }
+
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(
+        request,
+        template=template,
+        context=context_data
+    )
+
+
+def infinite_scrolling_view(
+    request: WSGIRequest,
+    *,
+    queryset: QuerySet | list,
+    queryset_name: str,
+    template: str,
+    context_data: dict[str, Any] | None = None
+) -> TemplateResponse:
+    if context_data is None:
+        context_data = {}
+
+    default_batch_size = 25
+
+    page = int(request.GET.get('page', 1))
+
+    batch_size = (
+        context_data.get('batch_size')
+        if 'batch_size' in context_data
+        else request.GET.get('batch_size', default_batch_size)
+    )
+
+    batch_size = int(batch_size)
+    offset = (page - 1) * batch_size
+
+    total_count = (
+        queryset.count()
+        if isinstance(queryset, QuerySet)
+        else len(queryset)
+    )
+
+    object_list = queryset[offset:offset + batch_size]
+    has_next = offset + batch_size < total_count
+
+    base_context_data = {
+        'batch_size': batch_size,
+        'has_next': has_next,
+        'total_count': total_count,
+        queryset_name: object_list
+    }
+
+    context_data.update(base_context_data)
+
+    return TemplateResponse(
+        request,
+        context=context_data,
+        template=template
+    )
+
+
+def list_view(
+    request: WSGIRequest,
+    *,
+    context_data: dict | None = None,
+    breadcrumbs_func: BreadCrumbCallable | None = None,
+    model,
+    template: str
+) -> TemplateResponse:
+
+    if context_data is None:
+        context_data = {}
+
+    breadcrumbs = Breadcrumbs()
+
+    if breadcrumbs_func is None:
+        breadcrumbs.add_breadcrumb(name=f'{model._meta.verbose_name} List')
+    else:
+        breadcrumbs_func(breadcrumbs)
+
+    base_context_data = {
+        'page_title': model._meta.verbose_name,
+        'page_description': 'List View',
+        'breadcrumbs': breadcrumbs
+    }
+
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(
+        request,
+        template=template,
+        context=context_data
+    )
+
+
+def form_view(
+    request: WSGIRequest,
+    *,
+    form,
+    context_data: dict | None = None,
+    obj,
+    breadcrumbs_func: BreadCrumbCallable | None = None,
+    verb: str | None = None,
+    template: str = 'django_spire/page/form_full_page.html'
+) -> TemplateResponse:
+
+    if context_data is None:
+        context_data = {}
+
+    model = obj._meta.model
+
+    breadcrumbs = Breadcrumbs()
+
+    if breadcrumbs_func is None:
+        breadcrumbs.add_form_breadcrumbs(obj=obj)
+    else:
+        breadcrumbs_func(breadcrumbs)
+
+    if verb is None:
+        verb = 'Edit' if obj.pk else 'Create'
+
+    if obj.pk:
+        form_title = f'{verb.title()} {model._meta.verbose_name} {obj}'
+        form_description = f'Are you sure you would like to {verb} {model._meta.verbose_name} "{obj}"?'
+    else:
+        form_title = f'{verb} {model._meta.verbose_name}'
+        form_description = ''
+
+    base_context_data = {
+        'page_title': model._meta.verbose_name,
+        'page_description': f'{verb} {obj}'.title(),
+        'breadcrumbs': breadcrumbs,
+        'form': form,
+        'form_title': form_title,
+        'form_description': form_description,
+    }
+
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(request, template, context=context_data)
+
+
+def model_form_view(
+    request: WSGIRequest,
+    *,
+    form,
+    context_data: dict | None = None,
+    obj,
+    breadcrumbs_func: BreadCrumbCallable | None = None,
+    verb: str | None = None,
+    template: str = 'django_spire/page/form_full_page.html'
+) -> TemplateResponse:
+    if breadcrumbs_func is None:
+        def breadcrumbs_func(crumbs: Breadcrumbs) -> None:
+            if obj.pk is None:
+                crumbs.add_form_breadcrumbs(obj)
+            else:
+                crumbs.add_form_breadcrumbs(obj)
+
+    return form_view(
+        request,
+        form=form,
+        context_data=context_data,
+        obj=obj,
+        breadcrumbs_func=breadcrumbs_func,
+        verb=verb,
+        template=template
+    )
+
+
+def template_view(
+    request: WSGIRequest,
+    page_title: str,
+    page_description: str,
+    breadcrumbs: Breadcrumbs,
+    template: str,
+    context_data: dict | None = None
+) -> TemplateResponse:
+    if context_data is None:
+        context_data = {}
+
+    base_context_data = {
+        'page_title': page_title,
+        'page_description': page_description,
+        'breadcrumbs': breadcrumbs
+    }
+    context_data = {**base_context_data, **context_data}
+
+    return TemplateResponse(request, template, context=context_data)

django_spire/contrib/help/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class HelpConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    label = 'django_spire_help'
+    name = 'django_spire.contrib.help'

django_spire/contrib/help/templates/django_spire/contrib/help/help_button.html

@@ -0,0 +1,8 @@
+<button
+    class="btn btn-app-primary-outlined py-0 px-2 me-1"
+    type="button"
+    data-bs-toggle="modal"
+    data-bs-target="#{{ help_id }}"
+>
+    ?
+</button>

django_spire/contrib/help/templates/django_spire/contrib/help/help_modal.html

@@ -0,0 +1,41 @@
+<div
+    class="modal fade"
+    id="{{ help_id }}"
+    tabindex="-1"
+    aria-labelledby="exampleModalLabel"
+    aria-hidden="true"
+>
+    <div class="modal-dialog modal-dialog-centered modal-dialog-scrollable modal-lg">
+        <div class="modal-content">
+            {% if help_title %}
+                <div class="modal-header">
+                    <h3
+                        class="modal-title"
+                        id="exampleModalLabel"
+                    >
+                        {{ help_title }}
+                    </h3>
+                    <button
+                        class="btn-close"
+                        type="button"
+                        data-bs-dismiss="modal"
+                        aria-label="Close"
+                    >
+                    </button>
+                </div>
+            {% endif %}
+            <div class="modal-body">
+                {{ help_content }}
+            </div>
+            <div class="modal-footer">
+                <button
+                    class="btn btn-app-secondary"
+                    type="button"
+                    data-bs-dismiss="modal"
+                >
+                    Close
+                </button>
+            </div>
+        </div>
+    </div>
+</div>

django_spire/contrib/help/templatetags/help.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import uuid
+
+from django import template
+from django.template.loader import render_to_string
+
+register = template.Library()
+
+
+@register.simple_tag()
+def help_button(help_template, help_title: str | None = None):
+    help_id = f'help-{uuid.uuid4()}'
+
+    rendered_help_button = render_to_string(
+        'django_spire/contrib/help/../templates/django_spire/help/help_button.html',
+        {
+            'help_id': help_id,
+            'help_title': help_title,
+        }
+    )
+
+    rendered_help_template = render_to_string(
+        'django_spire/contrib/help/../templates/django_spire/help/help_modal.html',
+        {
+            'help_id': help_id,
+            'help_title': help_title,
+            'help_content': render_to_string(help_template),
+        }
+    )
+
+    return rendered_help_button + rendered_help_template