Namespaces based configuration for Apphooks
Project description
|PyPI Version| |Build Status| |Coverage Status|
======================
aldryn-apphooks-config
======================
Namespaces based configuration for Apphooks
Basic concepts
==============
The concept of apphooks-config is to store all the configuration
in an applications-specific model, and let the developer
specify the desired option in a form.
In the views the model instance specific for the current
application namespace is loaded (through a mixin) and it's
thus available in the view to provide the configuration for
the current namespace.
Namespaces can be created on the fly in the ``Page`` admin
**Advanced settings** by following the steps above.
When creating an application configuration, you are in fact defining a
namespace, which is saved in the same field in the ``Page`` model as the
plain namespaces.
Supported django CMS versions
-----------------------------
+----------------+-------+-------+-------+
| | 0.2.x | 0.3.x | 0.4.x |
+----------------+-------+-------+-------+
| django CMS 3.1 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.2 | ✔ | ✔ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.3 | ✗ | ✔ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.4 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django CMS 3.5 | ✗ | ✗ | ✔ |
+----------------+-------+-------+-------+
Supported Django versions
-------------------------
+----------------+-------+-------+-------+
| | 0.2.x | 0.3.x | 0.4.x |
+----------------+-------+-------+-------+
| django 1.6 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django 1.7 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django 1.8 | ✔ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.9 | ✔ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.10 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.11 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 2.0 | ✗ | ✗ | ✗ |
+----------------+-------+-------+-------+
Implementation step-guide
=========================
* Define a AppHookConfig model in ``cms_appconfig.py``::
from aldryn_apphooks_config.models import AppHookConfig
class NewsBlogConfig(AppHookConfig):
pass
Implementation can be completely empty as the schema is defined in the
parent (abstract) model
* Use apphooks managers in your model::
from aldryn_apphooks_config.managers import AppHookConfigManager
class Article(models.Model):
title = models.CharField()
objects = AppHookConfigManager()
``AppHookConfigManager`` adds ``namespace`` method to manager and queryset::
Article.objects.namespace('foobar')
There is also a proper queryset, the ``ApphooksConfigQueryset``. Parler
integrated variants can be found in ``aldryn_apphooks_config.managers.parler``.
Names are ``AppHookConfigTranslatableManager`` and
``AppHookConfigTranslatableQueryset``.
* Define a ConfigForm in ``cms_appconfig.py``::
from app_data import AppDataForm
from django import forms
from aldryn_newsblog.models import NewsBlogConfig
from aldryn_apphooks_config.utils import setup_config
class BlogOptionForm(AppDataForm):
# fields are totally arbitrary: any form field supported by
# django-appdata is supported
show_authors = forms.BooleanField(required=False)
...
# this function will register the provided form with the model created
# at the above step
setup_config(BlogOptionForm, NewsBlogConfig)
# setup_config can be used as a decorator too, but the `model`
# attribute must be added to the form class
@setup_config
class BlogOptionForm(AppDataForm):
model = NewsBlogConfig
* Define an admin class for the AppHookConfig model (usually in ``admin.py``::
from django.contrib import admin
from aldryn_apphooks_config.admin import BaseAppHookConfig
class BlogConfigAdmin(BaseAppHookConfig):
def get_config_fields(self):
# this method **must** be implemented and **must** return the
# fields defined in the above form, with the ``config`` prefix
# This is dependent on the django-appdata API
return ('config.show_authors', ...)
* Define a CMSApp derived from CMSConfigApp provided by this application
(in ``cms_app.py``/``cms_apps.py``)::
from aldryn_apphooks_config.app_base import CMSConfigApp
from cms.apphook_pool import apphook_pool
from django.utils.translation import ugettext_lazy as _
from .models import NewsBlogConfig
class NewsBlogApp(CMSConfigApp):
name = _('NewsBlogApp')
urls = ['aldryn_newsblog.urls']
app_name = 'aldryn_newsblog'
# this option is specific of CMSConfigApp, and links the
# CMSApp to a specific AppHookConfig model
app_config = NewsBlogConfig
apphook_pool.register(NewsBlogApp)
* Implements your views inheriting the ``AppConfigMixin``::
from django.views.generic.detail import DetailView
from aldryn_apphooks_config.mixins import AppConfigMixin
class ArticleDetail(AppConfigMixin, DetailView):
def get_queryset(self):
return Article.objects.namespace(self.namespace)
``AppConfigMixin`` provides a complete support to namespaces, so the view
is not required to set anything specific to support them; the following
attributes are set for the view class instance:
* current namespace in ``self.namespace``
* namespace configuration (the instance of NewsBlogConfig) in ``self.config``
* current application in the ``current_app`` parameter passed to the
Response class
Test setup
==========
To properly setup the data for tests to run for a apphook-config enabled application,
make sure you add the following code to your TestCase::
MyTestCase():
def setUp(self):
# This is the namespace represented by the AppHookConfig model instance
self.ns_newsblog = NewsBlogConfig.objects.create(namespace='NBNS')
self.page = api.create_page(
'page', self.template, self.language, published=True,
# this is the name of the apphook defined in the CMSApp class
apphook='NewsBlogApp',
# The namespace is the namespace field of the AppHookConfig instance created above
apphook_namespace=self.ns_newsblog.namespace)
# publish the page to make the apphook available
self.page.publish(self.language)
.. |PyPI Version| image:: http://img.shields.io/pypi/v/aldryn-apphooks-config.svg
:target: https://pypi.python.org/pypi/aldryn-apphooks-config
.. |Build Status| image:: http://img.shields.io/travis/aldryn/aldryn-apphooks-config/master.svg
:target: https://travis-ci.org/aldryn/aldryn-apphooks-config
.. |Coverage Status| image:: http://img.shields.io/coveralls/aldryn/aldryn-apphooks-config/master.svg
:target: https://coveralls.io/r/aldryn/aldryn-apphooks-config?branch=master
=========
Changelog
=========
0.4.2 (2018-12-17)
==================
* Fix issue with Django 1.10 and below in AppHookConfigWidget
0.4.1 (2018-04-10)
==================
* django-appdata>=0.2.0 is now required
0.4.0 (2018-03-19)
==================
* Add Django 1.11 compatibility
* Add django CMS 3.5 compatibility
* Implement django-appdata 0.2 interface
* Remove south migrations
* Drop support for django CMS 3.3 and below
* Allow use setup_config as decorators
0.3.3 (2017-03-06)
==================
* Fixed MANIFEST.in typo
0.3.2 (2017-03-06)
==================
* Fixed setup.py issue
* Added locale files to MANIFEST.in
0.3.1 (2017-03-02)
==================
* Added translation system
* Added german translation
0.3.0 (2017-01-06)
++++++++++++++++++
* Allowed override AppHookConfigField attributes
* Drop Django 1.7 and below
* Drop django CMS 3.1 and below
* Add Django 1.10 support
0.2.7 (2016-03-03)
++++++++++++++++++
* Set namespace as readonly
* Add official Django 1.9 support
* Update readme
* Use path_info instead of path in resolve
0.2.6 (2015-10-05)
++++++++++++++++++
* Add support for Python 3.5
* Add support for Django 1.9a1
* Code style cleanup and tests
0.2.5 (2015-09-25)
++++++++++++++++++
* Add support for Django 1.8, django CMS 3.2
* AppHookConfigTranslatableManager.get_queryset should use queryset_class
* Skip overriding admin form if app_config field not present
0.2.4 (2015-04-20)
++++++++++++++++++
* Fixes issue where an apphook could not be changed, once set.
* Addes optional 'default' kwarg to namespace_url templatetag
0.1.0 (2014-01-01)
++++++++++++++++++
* First release on PyPI.
======================
aldryn-apphooks-config
======================
Namespaces based configuration for Apphooks
Basic concepts
==============
The concept of apphooks-config is to store all the configuration
in an applications-specific model, and let the developer
specify the desired option in a form.
In the views the model instance specific for the current
application namespace is loaded (through a mixin) and it's
thus available in the view to provide the configuration for
the current namespace.
Namespaces can be created on the fly in the ``Page`` admin
**Advanced settings** by following the steps above.
When creating an application configuration, you are in fact defining a
namespace, which is saved in the same field in the ``Page`` model as the
plain namespaces.
Supported django CMS versions
-----------------------------
+----------------+-------+-------+-------+
| | 0.2.x | 0.3.x | 0.4.x |
+----------------+-------+-------+-------+
| django CMS 3.1 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.2 | ✔ | ✔ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.3 | ✗ | ✔ | ✗ |
+----------------+-------+-------+-------+
| django CMS 3.4 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django CMS 3.5 | ✗ | ✗ | ✔ |
+----------------+-------+-------+-------+
Supported Django versions
-------------------------
+----------------+-------+-------+-------+
| | 0.2.x | 0.3.x | 0.4.x |
+----------------+-------+-------+-------+
| django 1.6 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django 1.7 | ✔ | ✗ | ✗ |
+----------------+-------+-------+-------+
| django 1.8 | ✔ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.9 | ✔ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.10 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 1.11 | ✗ | ✔ | ✔ |
+----------------+-------+-------+-------+
| django 2.0 | ✗ | ✗ | ✗ |
+----------------+-------+-------+-------+
Implementation step-guide
=========================
* Define a AppHookConfig model in ``cms_appconfig.py``::
from aldryn_apphooks_config.models import AppHookConfig
class NewsBlogConfig(AppHookConfig):
pass
Implementation can be completely empty as the schema is defined in the
parent (abstract) model
* Use apphooks managers in your model::
from aldryn_apphooks_config.managers import AppHookConfigManager
class Article(models.Model):
title = models.CharField()
objects = AppHookConfigManager()
``AppHookConfigManager`` adds ``namespace`` method to manager and queryset::
Article.objects.namespace('foobar')
There is also a proper queryset, the ``ApphooksConfigQueryset``. Parler
integrated variants can be found in ``aldryn_apphooks_config.managers.parler``.
Names are ``AppHookConfigTranslatableManager`` and
``AppHookConfigTranslatableQueryset``.
* Define a ConfigForm in ``cms_appconfig.py``::
from app_data import AppDataForm
from django import forms
from aldryn_newsblog.models import NewsBlogConfig
from aldryn_apphooks_config.utils import setup_config
class BlogOptionForm(AppDataForm):
# fields are totally arbitrary: any form field supported by
# django-appdata is supported
show_authors = forms.BooleanField(required=False)
...
# this function will register the provided form with the model created
# at the above step
setup_config(BlogOptionForm, NewsBlogConfig)
# setup_config can be used as a decorator too, but the `model`
# attribute must be added to the form class
@setup_config
class BlogOptionForm(AppDataForm):
model = NewsBlogConfig
* Define an admin class for the AppHookConfig model (usually in ``admin.py``::
from django.contrib import admin
from aldryn_apphooks_config.admin import BaseAppHookConfig
class BlogConfigAdmin(BaseAppHookConfig):
def get_config_fields(self):
# this method **must** be implemented and **must** return the
# fields defined in the above form, with the ``config`` prefix
# This is dependent on the django-appdata API
return ('config.show_authors', ...)
* Define a CMSApp derived from CMSConfigApp provided by this application
(in ``cms_app.py``/``cms_apps.py``)::
from aldryn_apphooks_config.app_base import CMSConfigApp
from cms.apphook_pool import apphook_pool
from django.utils.translation import ugettext_lazy as _
from .models import NewsBlogConfig
class NewsBlogApp(CMSConfigApp):
name = _('NewsBlogApp')
urls = ['aldryn_newsblog.urls']
app_name = 'aldryn_newsblog'
# this option is specific of CMSConfigApp, and links the
# CMSApp to a specific AppHookConfig model
app_config = NewsBlogConfig
apphook_pool.register(NewsBlogApp)
* Implements your views inheriting the ``AppConfigMixin``::
from django.views.generic.detail import DetailView
from aldryn_apphooks_config.mixins import AppConfigMixin
class ArticleDetail(AppConfigMixin, DetailView):
def get_queryset(self):
return Article.objects.namespace(self.namespace)
``AppConfigMixin`` provides a complete support to namespaces, so the view
is not required to set anything specific to support them; the following
attributes are set for the view class instance:
* current namespace in ``self.namespace``
* namespace configuration (the instance of NewsBlogConfig) in ``self.config``
* current application in the ``current_app`` parameter passed to the
Response class
Test setup
==========
To properly setup the data for tests to run for a apphook-config enabled application,
make sure you add the following code to your TestCase::
MyTestCase():
def setUp(self):
# This is the namespace represented by the AppHookConfig model instance
self.ns_newsblog = NewsBlogConfig.objects.create(namespace='NBNS')
self.page = api.create_page(
'page', self.template, self.language, published=True,
# this is the name of the apphook defined in the CMSApp class
apphook='NewsBlogApp',
# The namespace is the namespace field of the AppHookConfig instance created above
apphook_namespace=self.ns_newsblog.namespace)
# publish the page to make the apphook available
self.page.publish(self.language)
.. |PyPI Version| image:: http://img.shields.io/pypi/v/aldryn-apphooks-config.svg
:target: https://pypi.python.org/pypi/aldryn-apphooks-config
.. |Build Status| image:: http://img.shields.io/travis/aldryn/aldryn-apphooks-config/master.svg
:target: https://travis-ci.org/aldryn/aldryn-apphooks-config
.. |Coverage Status| image:: http://img.shields.io/coveralls/aldryn/aldryn-apphooks-config/master.svg
:target: https://coveralls.io/r/aldryn/aldryn-apphooks-config?branch=master
=========
Changelog
=========
0.4.2 (2018-12-17)
==================
* Fix issue with Django 1.10 and below in AppHookConfigWidget
0.4.1 (2018-04-10)
==================
* django-appdata>=0.2.0 is now required
0.4.0 (2018-03-19)
==================
* Add Django 1.11 compatibility
* Add django CMS 3.5 compatibility
* Implement django-appdata 0.2 interface
* Remove south migrations
* Drop support for django CMS 3.3 and below
* Allow use setup_config as decorators
0.3.3 (2017-03-06)
==================
* Fixed MANIFEST.in typo
0.3.2 (2017-03-06)
==================
* Fixed setup.py issue
* Added locale files to MANIFEST.in
0.3.1 (2017-03-02)
==================
* Added translation system
* Added german translation
0.3.0 (2017-01-06)
++++++++++++++++++
* Allowed override AppHookConfigField attributes
* Drop Django 1.7 and below
* Drop django CMS 3.1 and below
* Add Django 1.10 support
0.2.7 (2016-03-03)
++++++++++++++++++
* Set namespace as readonly
* Add official Django 1.9 support
* Update readme
* Use path_info instead of path in resolve
0.2.6 (2015-10-05)
++++++++++++++++++
* Add support for Python 3.5
* Add support for Django 1.9a1
* Code style cleanup and tests
0.2.5 (2015-09-25)
++++++++++++++++++
* Add support for Django 1.8, django CMS 3.2
* AppHookConfigTranslatableManager.get_queryset should use queryset_class
* Skip overriding admin form if app_config field not present
0.2.4 (2015-04-20)
++++++++++++++++++
* Fixes issue where an apphook could not be changed, once set.
* Addes optional 'default' kwarg to namespace_url templatetag
0.1.0 (2014-01-01)
++++++++++++++++++
* First release on PyPI.
