Provides persistant settings that can be edited in the Django admin. Settings can be any data type via polymorphic models. You can add support for new or custom types of settings.
Includes template tags and a dict-like interface to access settings, with an option to automatically create non-existent settings on first access with a default value.
Load the tag library:
{% load model_settings_tags %}
Get a settings object that will fetch and cache all setting values on first access:
{% get_settings as settings %}
{# Fetch and cache all the settings, then render `some_setting`. #}
{{ settings.some_setting }}
{# Only hits the database if `other_setting` isn't already in the cache. #}
{{ settings.other_setting }}
Settings can be used to store snippets of content or configuration:
{% if settings.some_boolean_configuration %}
... {{ settings.some_text_content }} ...
{% endif %}
Get a settings object that will automatically create non-existent settings with an empty string as the default value:
{% get_settings "" as settings %}
{# Create `new_setting`, if it doesn't already exist. #}
{{ settings.new_setting }}
If you only need to get one setting, or want to use a different default value for a particular setting:
{% get_setting "some_content" %}
{# Get or create a boolean setting that is enabled by default. #}
{% get_setting "some_feature" True as some_feature %}
{% if some_feature %}...{% endif %}
You can also use the included model_settings.context_processor.settings
context processor to add SETTINGS
to all RequestContext
objects. This
will be a SettingDict
object that automatically creates non-existent
settings on first access with an empty string as the default value.
Get a dict-like object for all settings:
from model_settings.models import Setting
settings = Setting.objects.as_dict()
Get a settings object that only populates the cache for a subset of settings:
settings = Setting.objects.filter(name__startswith='foo').as_dict()
Get a settings object that will automatically create non-existent settings with an empty string as the default value:
settings = Setting.object.as_dict(default='')
You can create settings of a particular type by using the SettingValueModel
subclasses:
Boolean.objects.create(name='foo', value=True)
Integer.objects.create(name='bar', value=123)
You can automatically create a setting of the correct type by using the
Setting
model directly:
Setting.objects.create(name='foo', value=True)
Setting.objects.create(name='bar', value=123)
Each SettingValueModel
subclass has a value_type
attribute and an
is_compatible()
method, which are used to determine whether or not the
subclass can store a particular value.
Support for common types of settings is built-in, e.g. boolean, date, datetime,
decimal, file, float, integer, text, and time. You can add support for custom
types by subclassing Setting
and SettingValueModel
:
class Foo(Setting, SettingValueModel):
value = FooField()
value_type = FooType
If you need more than a simple type check against value_type
to determine
whether or not a value is comatible, you can override the is_compatible()
method.
This method takes a value and should return True
if the value is
compatible, or False
if it is not. You can use this to create sub-types
that are rendered differently or utilise a different widget on the admin form.
For example, single line and multi-line text:
class SingleLineText(Setting, SettingValueModel):
value = models.CharField(max_length=255)
@classmethod
def is_compatible(self, value):
if isinstance(value, unicode) and '\n' not in value:
return True
return False
class MultiLineText(Setting, SettingValueModel):
value = models.TextField()
@classmethod
def is_compatible(self, value):
if isintance(value, unicode) and '\n' in value:
return True
return False
The value_type
attribute and is_compatible()
method are only by
Setting.objects.create()
, when it tries to determine which subclass to use.
- Customise label, help text, etc. for settings in the admin edit form.
- Add plugins for Rich Text and Raw code (HTML, CSS, JS) settings.
- Add tests.