Application configuration with aldryn_config.py¶

A Django application may require some configuration when it is deployed in aproject. Typically this will include settings in settings.py, but it can also include things like URL patterns that need tobe set up.

Divio Cloud provides for such configuration through an addon’saldryn_config.py file. This file needs to be in the root directory of theAddon.

Through this mechanism you can also allow the user to provide configuration ina simple web form that will be available in the Control Panel.

When the user saves the web form, the data will be stored in the addon’s settings.json file inthe project repository.

An example from a django CMS addon instance:

  1. {
  2.     "boilerplate_name": "html5",
  3.     "cms_content_cache_duration": 60,
  4.     "cms_menus_cache_duration": 3600,
  5.     "cms_templates": "[[\"content.html\", \"Content\"], [\"sales.html\", \"Sales\"]]",
  6.     "permissions_enabled": true
  7. }

The aldryn_config.py file¶

See the Application configuration with aldryn_config.py reference for more detail.

This file contain a class named Form that sub-classesaldryn_client.forms.BaseForm:

  1. from aldryn_client import forms
  2.  
  3.  
  4. class Form(forms.BaseForm):
  5.     ...

The Form class will contain the logic required to manage configuration.

Managing settings¶

A to_settings() method on the Form class will be called. Use this toreturn a dictionary of settings.

It takes two arguments:

  • the cleaned_data from the form
  • a dictionary containing the existing settings
    Add or manipulate the settings in the dictionary as required, and return it.

If you wish to accept user-supplied configuration, you will need to add someform fields to the form (see Adding form fields for user-configuration of the Addon below).

Managing URL configuration¶

ADDON_URLS (and related settings) to help manage URLconfigurations via settings.

We can define them in the to_settings() method of an application to do this.

Here’s an example of aldryn_config.py that inserts URL configurations intoa project:

  1. from aldryn_client import forms
  2.  
  3. class Form(forms.BaseForm):
  4.     def to_settings(self, data, settings):
  5.  
  6.         settings['ADDON_URLS'] = 'django_example_utilities.urls'
  7.  
  8.         return settings

See addon URLs for details.

Adding form fields for user-configuration of the Addon¶

The Form class may contain any number of form fields.

Available fields are:

  • aldryn_client.forms.CharField (optional arguments: min_length andmax_length )
  • aldryn_client.forms.CheckboxField
  • aldryn_client.forms.SelectField (required second argument: a list oftuples)
  • aldryn_client.forms.NumberField (optional arguments: min_value andmax_value )
  • aldryn_client.forms.StaticFileField (optional argument: extensions ,a list of valid file extensions.)
    All fields must provide a label as first argument and take a keyword argumentnamed required to indicate whether this field is required or not.

Here’s an example:

  1. class Form(forms.BaseForm):
  2.     # get the company name
  3.     company_name = aldryn_client.forms.CharField("Company name", required=True)
  4.  
  5.     def to_settings(self, cleaned_data, settings_dict):
  6.         # set the COMPANY_NAME based on company_name
  7.         settings_dict['COMPANY_NAME'] = cleaned_data[company_name"]
  8.  
  9.         # if we are in DEBUG mode, as on the Test server, use the Django console backend
  10.         # rather than really sending out messages (see
  11.         # https://docs.djangoproject.com/en/1.8/topics/email/#console-backend)
  12.         if settings_dict.get('DEBUG'):
  13.             settings_dict['EMAIL_BACKEND'] = 'django.core.mail.backends.console.EmailBackend'
  14.  
  15.         return settings_dict

Custom field validation¶

For custom field validation, sub-class a field and overwrite its clean() method. The clean() method takes a single argument (the value to be cleaned) and should either return a cleaned value or raise a aldryn_client
.forms.ValidationError with a useful message about why the validation failed.

Example:

  1. from aldryn_client import forms
  2.  
  3.  
  4. class FavouriteColourField(CharField):
  5.     def clean(self, colour):
  6.         colour = super(FavouriteColourField, self).clean(colour)
  7.         if colour == "black":
  8.             raise forms.ValidationError("You can have any colour you like except black")
  9.         else:
  10.             return colour

原文: http://docs.divio.com/en/latest/reference/configuration-aldryn-config.html