From a38cf0f1968d564f73473017921b286b471ae16f Mon Sep 17 00:00:00 2001 From: Trey Hunner Date: Sun, 3 Dec 2023 10:40:47 -0800 Subject: [PATCH] Start docs updates --- docs/{usage.rst => change.rst} | 210 +++++++++++++-------------------- docs/changelist.rst | 18 +++ docs/index.rst | 4 +- docs/installation.rst | 21 ++++ 4 files changed, 125 insertions(+), 128 deletions(-) rename docs/{usage.rst => change.rst} (79%) create mode 100644 docs/changelist.rst create mode 100644 docs/installation.rst diff --git a/docs/usage.rst b/docs/change.rst similarity index 79% rename from docs/usage.rst rename to docs/change.rst index 73e3713..feae34b 100644 --- a/docs/usage.rst +++ b/docs/change.rst @@ -1,24 +1,94 @@ -Usage -===== +Links on Change Pages +===================== -Installation ------------- -Install from `PyPI`_: +Linking all foreign keys +----------------------- + +The :func:`contents_or_fk_link ` template filter can be used to link to foreign keys for readonly admin form fields. + +Django Relatives also provides a replacement for the ``admin/includes/fieldset.html`` template which can be used to automatically link to all readonly foreign key fields in change forms. + +To use the custom fieldset template you must add ``relatives`` to +``INSTALLED_APPS`` in your settings file: + +.. code-block:: python + + INSTALLED_APPS = ( + ... + 'relatives', + ) + +Next create a ``admin/includes/fieldset.html`` template file:: + + {% extends "relatives/includes/fieldset.html" %} + +Also make sure this template file is in a custom template directory or an app +listed before your admin app in ``INSTALLED_APPS``. + +Example +~~~~~~~ -.. code-block:: bash +.. figure:: images/contents_or_fk_link_example.png - $ pip install django-relatives -.. _PyPI: https://pypi.python.org/pypi/django-relatives/ +Linking to reverse relations +---------------------------- +The :func:`related_objects ` template tag makes it easy to link to change lists +filtered for reverse relations (objects that have a foreign key to a given +object). -Since relatives uses cache, you can set settings to change the defaults: +Django Relatives also provides a custom ``change_form.html`` template that may +be used to add a "Relations" sidebar to change forms. This sidebar provides +links to change list queries for all objects that contain a foreign key to the +current object. + +To use the custom fieldset template you must add ``relatives`` to +``INSTALLED_APPS`` in your settings file: .. code-block:: python - RELATIVES_CACHE_KEY = 'relatives_cache' - RELATIVES_CACHE_TIME = int(60*60*24) + INSTALLED_APPS = ( + ... + 'relatives', + ) + +Now you can customize the change form template for your desired models/apps. +The easiest way to link to reverse relations is to override the +``change_form_template`` in your ``ModelAdmin`` subclass. + +Example +~~~~~~~ + +.. figure:: images/related_objects_example.png + +.. code-block:: python + + from django.contrib import admin + + from models import Company, Employee + + + class CompanyAdmin(admin.ModelAdmin): + change_form_template = 'relatives/change_form.html' + + admin.site.register(Company, CompanyAdmin) + + + admin.site.register(Employee) + + +Linking to reverse relations with custom template +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don't have access to change the ``ModelAdmin`` for your model or you are already customizing your model's admin change form, you will need to use a custom admin template instead. + +Create a ``admin/YOURAPP/YOURMODEL/change_form.html`` template file that extends from ``relatives/change_form.html``:: + + {% extends "relatives/change_form.html" %} + +Also make sure this template file is in a custom template directory or an app listed before your admin app in ``INSTALLED_APPS``. Edit links in inlines @@ -31,8 +101,7 @@ admin inline's ``fields`` list and ``readonly_fields`` list. Example ~~~~~~~ -Code -++++ +.. figure:: images/object_link_example.png .. code-block:: python @@ -59,11 +128,6 @@ Code admin.site.register(Employee) -Screenshot -++++++++++ - -.. figure:: images/object_link_example.png - Customizing inline edit links ----------------------------- @@ -76,8 +140,7 @@ and blank text (both are optional). Example ~~~~~~~ -Code -++++ +.. figure:: images/object_edit_link_example.png .. code-block:: python @@ -101,110 +164,3 @@ Code admin.site.register(Employee) - -Screenshot -++++++++++ - -.. figure:: images/object_edit_link_example.png - - -Linking to foreign keys ------------------------ - -The :func:`contents_or_fk_link ` template filter can be used to link to foreign keys -for readonly admin form fields. - -Django Relatives also provides a replacement for the -``admin/includes/fieldset.html`` template which can be used to automatically -link to all readonly foreign key fields in change forms. - -To use the custom fieldset template you must add ``relatives`` to -``INSTALLED_APPS`` in your settings file: - -.. code-block:: python - - INSTALLED_APPS = ( - ... - 'relatives', - ) - -Next create a ``admin/includes/fieldset.html`` template file:: - - {% extends "relatives/includes/fieldset.html" %} - -Also make sure this template file is in a custom template directory or an app -listed before your admin app in ``INSTALLED_APPS``. - -Example Screenshot -~~~~~~~~~~~~~~~~~~ - -.. figure:: images/contents_or_fk_link_example.png - - -Linking to reverse relations ----------------------------- - -The :func:`related_objects ` template tag makes it easy to link to change lists -filtered for reverse relations (objects that have a foreign key to a given -object). - -Django Relatives also provides a custom ``change_form.html`` template that may -be used to add a "Relations" sidebar to change forms. This sidebar provides -links to change list queries for all objects that contain a foreign key to the -current object. - -To use the custom fieldset template you must add ``relatives`` to -``INSTALLED_APPS`` in your settings file: - -.. code-block:: python - - INSTALLED_APPS = ( - ... - 'relatives', - ) - -Now you can customize the change form template for your desired models/apps. -The easiest way to link to reverse relations is to override the -``change_form_template`` in your ``ModelAdmin`` subclass. - -Example -~~~~~~~ - -Code -++++ - -.. code-block:: python - - from django.contrib import admin - - from models import Company, Employee - - - class CompanyAdmin(admin.ModelAdmin): - change_form_template = 'relatives/change_form.html' - - admin.site.register(Company, CompanyAdmin) - - - admin.site.register(Employee) - -Screenshot -++++++++++ - -.. figure:: images/related_objects_example.png - - -Linking to reverse relations with custom template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you don't have access to change the ``ModelAdmin`` for your model or you are -already customizing your model's admin change form, you will need to use a -custom admin template instead. - -Create a ``admin/YOURAPP/YOURMODEL/change_form.html`` template file that -extends from ``relatives/change_form.html``:: - - {% extends "relatives/change_form.html" %} - -Also make sure this template file is in a custom template directory or an app -listed before your admin app in ``INSTALLED_APPS``. diff --git a/docs/changelist.rst b/docs/changelist.rst new file mode 100644 index 0000000..53f6652 --- /dev/null +++ b/docs/changelist.rst @@ -0,0 +1,18 @@ +Links in Change Lists +===================== + + +Linking related fields +---------------------- + +To automatically link foreign key and one-to-one fields to the relevant admin change page, inherit from ``RelativesAdmin``. + +TODO show code example and screenshot + + +Linking ModelAdmin methods +-------------------------- + +To turn a ``ModelAdmin`` method to a specific foreign key or one-to-one field, use the ``link_related`` decorator. + +TODO show code example and screenshot diff --git a/docs/index.rst b/docs/index.rst index 8924c73..e040ad6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,9 @@ Contents .. toctree:: :maxdepth: 2 - usage + installation + changelist + change api Contributing diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..c768a00 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,21 @@ +Usage +===== + +Installation +------------ + +Install from `PyPI`_: + +.. code-block:: bash + + $ pip install django-relatives + +.. _PyPI: https://pypi.python.org/pypi/django-relatives/ + + +Since relatives uses cache, you can set settings to change the defaults: + +.. code-block:: python + + RELATIVES_CACHE_KEY = 'relatives_cache' + RELATIVES_CACHE_TIME = 60*60*24