.. auto generated by export_components.py ********** Interfaces ********** |experimental| |area| Tools for automating interactions. **Version:** 0.1.0-x .. _interfaces-interfaces-ajax: AJAX ==== |experimental| |interface| **Version:** 0.5.0-x Conveniently and consistently register AJAX views across a project. Developer Reference: :ref:`interfaces-interfaces-ajax-developer` **Provides** - Library - Registry Abstract --------- The apps within a project often require the creation of AJAX views. These may be ad hoc or part of a more organized structure. SuperDjango's AJAX app provides a simple interface for registering AJAX views across a project. Install ------- Update project settings: .. code-block:: python # settings.py INSTALLED_APPS = [ # ... "superdjango.interfaces.ajax.apps.AutoConfig", # ... ] # Default module name is ajax. SUPERDJANGO_AJAX_MODULE_NAME = "ajax" If you wish to manually manage an AJAX registry, use ``superdjango.ajax.apps.DefaultConfig`` instead. Utilize the URLs: .. code-block:: python # main/urls.py from superdjango.interfaces.ajax import ajax urlpatterns = [ # ... path('ajax/', include(ajax.get_urls())), # ... ] Usage ----- Create your AJAX views as normal, utilizing a viewset to capture the views within your app: .. code-block:: python # views.py from superdjango.views import GenericView, JSONMixin, ViewSet class SomeAjaxCall(JSONMixin, GenericView): # ... class SomeOtherAjaxCall(JSONMixin, GenericView): # ... class MyAjaxViewSet(ViewSet): views = [ SomeAjaxCall, SomeOtherAjaxCall, ] # ajax.py from superdjango.ajax import ajax from .views import MyAjaxViewSet ajax.register("myapp", MyAjaxViewSet) You could, of course, home your AJAX views in the ``views.py`` of your app instead of the ``ajax.py``. .. _interfaces-interfaces-cli: CLI === |experimental| |library| **Version:** 0.2.0-x Utilities for working with command line interfaces. Developer Reference: :ref:`interfaces-interfaces-cli-developer` **Provides** - Constants - Library **Dependencies** - `tabulate `_ (required) *Used to print tabulate output on the command line.* .. _interfaces-interfaces-hooks: Hooks ===== |experimental| |interface| **Version:** 0.4.0-x A simple alternative to Django's signal handling system. Developer Reference: :ref:`interfaces-interfaces-hooks-developer` **Provides** - Library - Registry Abstract -------- Inspired by Wagtail's hooks, SuperDjango's hooks system is simple, yet powerful alternative to Django's signals and receivers. Install ------- No additional installation steps are required to use hooks. Usage ----- Defining a Hook ............... Hooks may be defined anywhere in code that is loaded and executed as part of Django operation. For example, the :py:class:`superdjango.contrib.accounts.auth.views.LoginRedirect` view defines a hook that may be used to override the post-login redirect URL: .. code-block:: python from superdjango.interfaces.hooks import hooks class LoginRedirect(RedirectView): # ... def get_redirect_url(self, *args, **kwargs): results = hooks.get_hooks("get_login_redirect_url") if results: return results[0](self.request) # ... Documenting a Hook .................. To help others understand how a hook works, you may define the hook in the ``meta.ini`` file of the app or package. For example: .. code-block:: ini [hooks] get_login_redirect_url = (request): Return a URL string to override the post-login redirect behavior. Auto-documentation scripts may now provide a list of provided hooks dynamically. Responding to a Hook .................... Responding to a hook requires 1) defining a function, 2) registering the function, and 3) making sure the code is loaded. For example: .. code-block:: python # myapp/hooks.py from superdjango.interfaces.hooks import hooks def get_login_redirect_url(request): if request.user.is_superuser: return "/admin/" else: return "/" hooks.register(get_login_redirect_url, hook="get_login_redirect_url") The hook name, if omitted defaults to the name of the provided function. So the register statement could simply be written as: .. code-block:: python hooks.register(get_login_redirect_url) Finally, you can use the ``ready()`` method to load the hooks: .. code-block:: python # myapp/apps.py from django.apps import AppConfig class DefaultConfig(AppConfig): name = 'myapp' def ready(self): from . import hooks .. _interfaces-interfaces-rest: REST ==== |experimental| |interface| **Version:** 0.5.0-x A lightweight interface for easily registering Django REST Framework resources. Developer Reference: :ref:`interfaces-interfaces-rest-developer` **Provides** - Library - Registry Abstract -------- Projects and apps that implement a REST API often choose `Django REST Framework`_. This package focuses on making the registration of REST resources easy; it's usefulness is derived from a simple yet effective system of definition and auto-discovery of REST APIs across a project. .. _Django REST Framework: https://www.django-rest-framework.org Benefits include: - Use Django REST Framework as usual, but with auto-discovery of API resources. - Consistent view names that use a convention similar to the Django Admin to avoid collisions. - Built-in support for new API versions. Install ------- Django REST Framework is required: ``pip install django-rest-framework;`` Update project settings: .. code-block:: python # settings.py INSTALLED_APPS = [ "rest_framework", # ... "superdjango.interfaces.reset.apps.AutoConfig", # ... ] SUPERDJANGO_API_MODULE_NAME = "api" The ``SUPERDJANGO_API_MODULE_NAME`` may be used to identify the package or module name used to find your API definition. It defaults to ``api``, but may be set to anything you like, provided it is consistent across your project. Utilize the URLs: .. code-block:: python # main/urls.py from rest_framework import routers from superdjango.interfaces.reset import api router = routers.DefaultRouter() urlpatterns = [ # ... path('api/v1/', include(api.get_urls(router))), path('api-auth/', include('rest_framework.urls', namespace='rest_framework')), # ... ] Usage ----- Create serializers and viewsets. See `Django REST Framework Quickstart`_. .. _Django REST Framework Quickstart: https://www.django-rest-framework.org/tutorial/quickstart/#serializers In the ``__init__.py`` of the app's api module, create and register the interface. .. code-block:: python # api/__init__.py from superdjango.interfaces.reset import api, REST from .views import MyViewSet, MyOtherViewSet class MyAPI(REST): viewsets = [ MyViewSet, MyOtherViewSet, ] api.register("myapp", MyAPI)