Submitter:	Christian Hammond	Reviewers
Branch:	trunk	Groups:	reviewboard
Bugs:		People:
Change Number:	None	Repository:	Navi

Description:

Django's settings file is nice for customizing site settings, so long as the values don't need to be changed often. It's less useful when you want to give users the ability to quickly change things or experiment with the site configuration, since it requires logging into the server, hand-editting a file, and restarting.

The new djblets.siteconfig app provides a means to fix this. Settings data is stored in a SiteConfiguration model linked to the active Site. The setting values can be of any type supported by Django's simplejson, meaning dictionary values, arrays, and other such things work fine.

To ease customization of settings, a special Form object is provided that settings pages can subclass. Each field in the Form can be a stored setting and Djblets will handle the loading/saving automatically. These Forms support fieldsets for grouping objects, descriptions of fieldsets, and disabled fields (with reasons why they're disabled).

Mapping tables and utility functions exist to transition to and from many of the built-in Django settings. Not all settings are provided, but the ones sites would most likely want to customize are. Sites are meant to add these mapping tables as defaults, which will ensure that accessing the siteconfig version of the setting would return the value saved in the settings.py file, and forms that change these settings can call a function in their save handler to write the values back to the in-memory Settings object, meaning that the database will always take precedence but that apps accessing the Settings object instead of the SiteConfiguration will receive the correct value.

Testing Done:

Tested with my upcoming change for Review Board. Settings of various types are loaded and saved as expected. The Django Settings compatibility appears to work perfectly fine.

Diff revision 1 (Latest)

Files Changed:

/trunk/djblets/djblets/siteconfig/admin.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/context_processors.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/django_settings.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/forms.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/managers.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/models.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/views.py: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/templates/siteconfig/settings.html: 1 change [ new content ]
/trunk/djblets/djblets/siteconfig/templates/siteconfig/settings_field.html: 1 change [ new content ]
/trunk/djblets/djblets/util/templatetags/djblets_forms.py: 1 change [ new content ]
/trunk/djblets/djblets/util/templatetags/djblets_utils.py: 3 changes [ 1 2 3 ]

Expand changes

+#
 # djblets/siteconfig/admin.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django.contrib import admin
 from djblets.siteconfig.models import SiteConfiguration
 class SiteConfigurationAdmin(admin.ModelAdmin):
     list_display = ('site', 'version')
 admin.site.register(SiteConfiguration, SiteConfigurationAdmin)

+#
 # djblets/siteconfig/context_processors.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from djblets.siteconfig.models import SiteConfiguration
 def siteconfig(request):
     """
     Exposes the site configuration as a siteconfig variable in templates.
     """
     return {'siteconfig': SiteConfiguration.objects.get_current()}

+#
 # djblets/siteconfig/django_settings.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django.conf import settings
 locale_settings_map = {
     'locale_timezone':             'TIME_ZONE',
     'locale_language_code':        'LANGUAGE_CODE',
     'locale_date_format':          'DATE_FORMAT',
     'locale_datetime_format':      'DATETIME_FORMAT',
     'locale_default_charset':      'DEFAULT_CHARSET',
     'locale_language_code':        'LANGUAGE_CODE',
     'locale_month_day_format':     'MONTH_DAY_FORMAT',
     'locale_time_format':          'TIME_FORMAT',
     'locale_time_zone':            'TIME_ZONE',
+}
 mail_settings_map = {
     'locale_year_month_format':    'YEAR_MONTH_FORMAT',
     'mail_server_address':         'SERVER_EMAIL',
     'mail_default_from':           'DEFAULT_FROM_EMAIL',
     'mail_host':                   'EMAIL_HOST',
     'mail_port':                   'EMAIL_PORT',
     'mail_host_user':              'EMAIL_HOST_USER',
     'mail_host_password':          'EMAIL_HOST_PASSWORD',
     'mail_use_tls':                'EMAIL_USE_TLS',
+}
 site_settings_map = {
     'site_media_root':             'MEDIA_ROOT',
     'site_media_url':              'MEDIA_URL',
     'site_prepend_www':            'PREPEND_WWW',
     'site_upload_temp_dir':        'FILE_UPLOAD_TEMP_DIR',
     'site_upload_max_memory_size': 'FILE_UPLOAD_MAX_MEMORY_SIZE',
+}
 cache_settings_map = {
     'cache_backend':               'CACHE_BACKEND',
     'cache_expiration_time':       'CACHE_EXPIRATION_TIME',
+}
 # Don't build unless we need it.
 _django_settings_map = {}
 def get_django_settings_map():
     """
     Returns the settings map for all Django settings that users may need
     to customize.
     """
     if not _django_settings_map:
         _django_settings_map.update(locale_settings_map)
         _django_settings_map.update(mail_settings_map)
         _django_settings_map.update(site_settings_map)
         _django_settings_map.update(cache_settings_map)
     return _django_settings_map
 def _generate_defaults(settings_map):
     """
     Utility function to generate a defaults mapping.
     """
     defaults = {}
     for siteconfig_key, settings_key in settings_map.iteritems():
         if hasattr(settings, settings_key):
             defaults[siteconfig_key] = getattr(settings, settings_key)
     return defaults
 def get_locale_defaults():
     """
     Returns the locale-related Django defaults that projects may want to
     let users customize.
     """
     return _generate_defaults(locale_settings_map)
 def get_mail_defaults():
     """
     Returns the mail-related Django defaults that projects may want to
     let users customize.
     """
     return _generate_defaults(mail_settings_map)
 def get_site_defaults():
     """
     Returns the site-related Django defaults that projects may want to
     let users customize.
     """
     return _generate_defaults(site_settings_map)
 def get_cache_defaults():
     """
     Returns the cache-related Django defaults that projects may want to
     let users customize.
     """
     return _generate_defaults(cache_settings_map)
 def get_django_defaults():
     """
     Returns all Django defaults that projects may want to let users customize.
     """
     return _generate_defaults(get_django_settings_map())
 def apply_django_settings(siteconfig, settings_map=None):
     """
     Applies all settings from the site configuration to the Django settings
     object.
     """
     if settings_map is None:
         settings_map = get_django_settings_map()
     for key, value in settings_map.iteritems():
         if key in siteconfig.settings:
             setattr(settings, key, siteconfig.get(key))

+#
 # djblets/siteconfig/forms.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django import forms
 class SiteSettingsForm(forms.Form):
     """
     A base form for loading/saving settings for a SiteConfiguration. This is
     meant to be subclassed for different settings pages. Any fields defined
     by the form will be loaded/saved automatically.
     """
     def __init__(self, siteconfig, *args, **kwargs):
         forms.Form.__init__(self, *args, **kwargs)
         self.siteconfig = siteconfig
         self.disabled_fields = {}
         self.disabled_reasons = {}
         self.load()
     def load(self):
         """
         Loads settings from the ```SiteConfiguration''' into this form.
         The default values in the form will be the values in the settings.
         This also handles setting disabled fields based on the
         ```disabled_fields''' and ```disabled_reasons''' variables set on
         this form.
         """
         if hasattr(self, "Meta"):
             save_blacklist = getattr(self.Meta, "save_blacklist", [])
         for field in self.fields:
             value = self.siteconfig.get(field)
             if isinstance(value, bool) or value:
                 self.fields[field].initial = value
             if field in self.disabled_fields:
                 self.fields[field].widget.attrs['disabled'] = 'disabled'
     def save(self):
         """
         Saves settings from the form back into the ```SiteConfiguration'''.
         """
         if not self.errors:
             if hasattr(self, "Meta"):
                 save_blacklist = getattr(self.Meta, "save_blacklist", [])
             for key, value in self.cleaned_data.iteritems():
                 if key not in save_blacklist:
                     self.siteconfig.settings[key] = value
             self.siteconfig.save()

+#
 # djblets/siteconfig/managers.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django.conf import settings
 from django.contrib.sites.models import Site
 from django.db import models
 _SITECONFIG_CACHE = {}
 class SiteConfigurationManager(models.Manager):
     """
     A Manager that provides a get_current function for retrieving the
     SiteConfiguration for this particular running site.
     """
     def get_current(self):
         """
         Returns the site configuration on the active site.
         """
         # This will handle raising a ImproperlyConfigured if not set up
         # properly.
         site = Site.objects.get_current()
         if site.id not in _SITECONFIG_CACHE:
             _SITECONFIG_CACHE[site.id] = site.config.get()
         return _SITECONFIG_CACHE[site.id]

+#
 # djblets/siteconfig/models.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django.contrib.sites.models import Site
 from django.db import models
 from djblets.siteconfig.managers import SiteConfigurationManager
 from djblets.util.fields import JSONField
 _DEFAULTS = {}
 class SiteConfiguration(models.Model):
     """
     Configuration data for a site. The version and all persistent settings
     are stored here.
     The usual way to retrieve a SiteConfiguration is to do:
     >>> siteconfig = SiteConfiguration.objects.get_current()
     """
     site = models.ForeignKey(Site, related_name="config")
     version = models.CharField(max_length=20)
     settings = JSONField()
     objects = SiteConfigurationManager()
     def get(self, key, default=None):
         """
         Retrieves a setting. If the setting is not found, the default value
         will be returned. This is represented by the default parameter, if
         passed in, or a global default if set.
         """
         if default is None and self.id in _DEFAULTS:
             default = _DEFAULTS[self.id].get(key, None)
         return self.settings.get(key, default)
     def set(self, key, value):
         """
         Sets a setting. The key should be a string, but the value can be
         any native Python object.
         """
         self.settings[key] = value
     def add_defaults(self, defaults_dict):
         """
         Adds a dictionary of defaults to this SiteConfiguration. These
         defaults will be used when calling ```get''', if that setting wasn't
         saved in the database.
         """
         if self.id not in _DEFAULTS:
             _DEFAULTS[self.id] = {}
         _DEFAULTS[self.id].update(defaults_dict)
     def add_default(self, key, default_value):
         """
         Adds a single default setting.
         """
         self.add_defaults({key: default_value})
     def get_defaults(self):
         """
         Returns all default settings registered with this SiteConfiguration.
         """
         if self.id not in _DEFAULTS:
             _DEFAULTS[self.id] = {}
         return _DEFAULTS[self.id]
     def __unicode__(self):
         return "%s (version %s)" % (unicode(self.site), self.version)

+#
 # djblets/siteconfig/views.py
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
 from django.contrib.admin.views.decorators import staff_member_required
 from django.contrib.sites.models import Site
 from django.http import HttpResponseRedirect
 from django.shortcuts import render_to_response
 from django.template.context import RequestContext
 from djblets.siteconfig.models import SiteConfiguration
 @staff_member_required
 def site_settings(request, form_class,
                   template_name="siteconfig/settings.html"):
     """
     Provides a front-end for customizing Review Board settings.
     """
     siteconfig = SiteConfiguration.objects.get_current()
     if request.method == "POST":
         form = form_class(siteconfig, request.POST, request.FILES)
         if form.is_valid():
             form.save()
             return HttpResponseRedirect(".?saved=1")
     else:
         form = form_class(siteconfig)
     return render_to_response(template_name, RequestContext(request, {
         'form': form,
         'saved': request.GET.get('saved', 0)
     }))

 {% extends "admin/base_site.html" %}
 {% load adminmedia admin_list djblets_utils i18n %}
 {% block stylesheet %}{% admin_media_prefix %}css/forms.css{% endblock %}
 {% block title %}{{form.Meta.title}} {{block.super}}{% endblock %}
 {% block content %}
 <div id="content-main">
 {%  if form.error_dict %}
  <p class="errornote">
   {% blocktrans count form.error_dict.items|length as counter %}Please correct the error below.{% plural %}Please correct the errors below.{% endblocktrans %}
  </p>
 {%  endif %}
 {% if saved %}
  <ul class="messagelist">
   <li>{% trans "The settings have been saved." %}</li>
  </ul>
 {% endif %}
  <h1>{{form.Meta.title}}</h1>
  <form action="." method="post"{% if form.is_multipart %} enctype="multipart/form-data"{% endif %}>
 {% if form.Meta.fieldsets %}
 {%  for fieldset in form.Meta.fieldsets %}
   <fieldset class="module aligned{% if fieldset.classes %}{% for class in fieldset.classes %} {{class}}{% endfor %}{% endif %}"{% if fieldset.id %} id="fieldset_{{fieldset.id}}"{% endif %}>
 {% if fieldset.title %}<h2>{{fieldset.title}}</h2>{% endif %}
 {%   if fieldset.description %}
    <div class="description">
     {{fieldset.description|paragraphs}}
    </div>
 {% endif %}
 {%   for fieldname in fieldset.fields %}
 {%    with form|getitem:fieldname as field %}
 {%     include "siteconfig/settings_field.html" %}
 {%    endwith %}
 {%   endfor %}
   </fieldset>
 {%  endfor %}
 {% else %}
   <fieldset class="module aligned">
 {%   for field in form %}
 {%    include "siteconfig/settings_field.html" %}
 {%   endfor %}
   </fieldset>
 {% endif %}
   <div class="submit-row">
    <input type="submit" value="{% trans "Save" %}" class="default" />
   </div>
  </form>
 </div>
 {% endblock %}

 {% load djblets_forms %}
 {% load djblets_utils %}
 {%    if field.is_hidden %}
    {{field}}
 {%    else %}
 {%     with field|form_field_has_label_first as label_first %}
    <div class="form-row{% if not label_first %} checkbox-row{% endif%}{% if field.errors %} error{% endif %}">
     {{field.errors}}
     {% if not label_first %}{{field}}{% endif %}
     {% label_tag field %}
     {% if label_first %}{{field}}{% endif %}
     {% if field.help_text %}<p class="help">{{field.help_text}}</p>{% endif %}
     {% if form.disabled_reasons|contains:fieldname %}<p class="disabled-reason">{{form.disabled_reasons|getitem:fieldname|safe}}</p>{% endif %}
    </div>
 {%     endwith %}
 {%    endif %}

+#
 # djblets_forms.py -- Form-related template tags
+#
 # Copyright (c) 2008  Christian Hammond
+#
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
+#
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

Review Board

beta

This change has been marked as submitted.

Add the new siteconfig app for Djblets for dynamic site-wide configuration

Diff revision 1 (Latest)