Merge d59828b into c869612

docs/source/general/extend_django_freeradius.rst

@@ -0,0 +1,148 @@
+======================================
+Customizing django-freeradius
+======================================
+
+`django-freeeadius` provieds set of models, admin and API classes which can be imported, extende and hence customized by third party apps.
+
+
+Extending models
+----------------
+Apart from extending implemented models, `django_freeradius` also provides flexibility to extend abstract class models from `django-freeradius.base.models`.
+
+Example:
+
+.. code-block:: python
+
+    #In sample_radius/models.py
+
+    from django.db import models
+    from django_freeradius.base.models import AbstractRadiusCheck
+    
+    class RadiusCheck(AbstractRadiusCheck):
+        #modify/extend the default behavour here
+
+        custom_field = models.TextField()
+
+
+Extending admin
+---------------
+
+Similar to models, abstract admin classes from `django_freeradius.base.admin` can also be extended to avoid duplicate code.
+
+.. code-block:: python
+
+    # In sample_radius/admin.py
+    
+    from django.contrib import admin 
+    from .models import RadiusCheck
+    from django_freeradius.base.admin import AbstractRadiusAccountingAdmin
+
+    class RadiusCheckAdmin(AbstractRadiusCheckAdmin):
+        model = RadiusCheck
+
+        #modify/extend default behaviour here
+
+        def __init__(self,*args,**kwargs):
+            #add your custom fields here
+
+            self.fields.append('custom_field')
+            self.list_display.append('custom_field')
+            
+            super(AbstractRadiusCheckAdmin, self).__init__(*args, **kwargs)
+
+    admin.site.register(RadiusCheck,RadiusCheckAdmin)
+
+        
+
+Extending API views
+-------------------
+
+Example of code:
+
+.. code-block:: python
+
+    #django_freeradius/base/admin.py
+
+    from django.contrib.admin import ModelAdmin
+    from openwisp_utils.admin import TimeReadonlyAdminMixin
+
+    
+    class TimeStampedEditableAdmin(TimeReadonlyAdminMixin, ModelAdmin):
+        pass
+
+
+    class AbstractRadiusReplyAdmin(TimeStampedEditableAdmin):
+        list_display = ['username', 'attribute', 'op',
+                    'value', 'created', 'modified']
+        autocomplete_fields = ['user']
+        form = ModeSwitcherForm
+        fields = ['mode',
+                'user',
+                'username',
+                'attribute',
+                'op',
+                'value',
+                'created',
+                'modified']
+
+
+Creating a Reusable App
+-----------------------
+
+Install `swapper` to begin with this.  If your reusable app is being published as a Python package,
+be sure to add `swapper` to your project's dependencies. Learn more about `swapper`  at the `Swapper Guide
+<https://github.com/wq/django-swappable-models>`
+
+Install swapper:
+
+.. code-block:: shell
+
+   pip install swapper
+
+
+In your reusable models, use ``import swapper``  and  add to Meta class  ``swappable = swapper.swappable_setting('reusable_app', 'model')``:
+
+.. code-block:: python
+
+    #django_freeradius/models.py
+
+    from swapper import swappable_setting
+
+    from .base.models import (
+            AbstractNas, AbstractRadiusAccounting, AbstractRadiusBatch, AbstractRadiusCheck, AbstractRadiusGroup,
+            AbstractRadiusGroupCheck, AbstractRadiusGroupReply, AbstractRadiusPostAuth, AbstractRadiusReply,
+            AbstractRadiusToken, AbstractRadiusUserGroup,
+        )
+
+
+    class RadiusCheck(AbstractRadiusCheck):
+        class Meta(AbstractRadiusCheck.Meta):
+            abstract = False
+            swappable = swappable_setting('django_freeradius', 'RadiusCheck')
+
+
+..  note::
+    Swapper can also be used in Django 1.7+ migration scripts to facilitate dependency ordering and
+    foreign key references. To use this feature in your library, generate a migration script with makemigrations
+    and make the following changes:
+
+---------------
+Update Settings
+---------------
+
+Update the settings to trigger the swapper:
+
+.. code-block:: python
+
+    #django_freeradius/tests/settings.py
+
+    if os.environ.get('SAMPLE_APP', False):
+        INSTALLED_APPS.append('sample_radius')
+        DJANGO_FREERADIUS_RADIUSREPLY_MODEL = "sample_radius.RadiusReply"
+        DJANGO_FREERADIUS_RADIUSGROUPREPLY_MODEL = "sample_radius.RadiusGroupReply"
+        DJANGO_FREERADIUS_RADIUSCHECK_MODEL = "sample_radius.RadiusCheck"
+        DJANGO_FREERADIUS_RADIUSGROUPCHECK_MODEL = "sample_radius.RadiusGroupCheck"
+        DJANGO_FREERADIUS_RADIUSACCOUNTING_MODEL = "sample_radius.RadiusAccounting"
+        DJANGO_FREERADIUS_NAS_MODEL = "sample_radius.Nas"
+        DJANGO_FREERADIUS_RADIUSUSERGROUP_MODEL = "sample_radius.RadiusUserGroup"
+        DJANGO_FREERADIUS_RADIUSPOSTAUTHENTICATION_MODEL = "sample_radius.RadiusPostAuth"