Divio Shell Required

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

Divio Cloud provides for such configuration through an Addon's aldryn_config.py file, which needs to be in the root directory of the Addon.

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

The aldryn_config.py file

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

from aldryn_client import forms


class Form(forms.BaseForm):
    ...

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 to return 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 dictionary as required, and return it.

If you wish to accept user-supplied configuration, you will need to add some form fields to the form. 

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  and max_length )
  • aldryn_client.forms.CheckboxField 
  • aldryn_client.forms.SelectField  (required second argument: a list of tuples)
  • aldryn_client.forms.NumberField  (optional arguments: min_value  and max_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 argument named required to indicate whether this field is required or not.

Here's an example:

class Form(forms.BaseForm):
    # get the company name
    company_name = aldryn_client.forms.CharField("Company name", required=True)

    def to_settings(self, cleaned_data, settings_dict):
        # set the COMPANY_NAME based on company_name
        settings_dict['COMPANY_NAME'] = cleaned_data[company_name"]

        # if we are in DEBUG mode, as on the Test server, use the Django console backend
        # rather than really sending out messages (see
        # https://docs.djangoproject.com/en/1.8/topics/email/#console-backend)
        if settings_dict.get('DEBUG'):
            settings_dict['EMAIL_BACKEND'] = 'django.core.mail.backends.console.EmailBackend'

        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 aldryn_client.forms.ValidationError with a useful message about why the validation failed.

Example:

from aldryn_client import forms


class FavouriteColourField(CharField):
    def clean(self, colour):
        colour = super(FavouriteColourField, self).clean(colour)
        if colour == "black":
            raise forms.ValidationError("You can have any colour you like except black")
        else:
            return colour

Managing URL configuration

Your Addon may have a set of URL patterns in urls.py  that need to be included in a project’s urls.py

Each urls.py  that a Divio Cloud project requires needs to be specified in its settings. We can use the to_settings() method to do this.

Divio Cloud offers four different ways of specifying URL patterns for insertion into a project’s urls.py .

  • ADDON_URLS  to insert them
  • ADDON_URLS_LAST  to insert them in last place
  • ADDON_URLS_I18N  to insert them as i18n_patterns  (i.e. translatable URL patterns)
  • ADDON_URLS_I18N_LAST  to insert them after the other translatable URL patterns

Here’s an example of aldryn_config.py  that inserts URLconfs into a project:

from aldryn_client import forms

class Form(forms.BaseForm):
    def to_settings(self, data, settings):
        # add the urls from the 'django_example_utilities module
        settings['ADDON_URLS'] = 'django_example_utilities.urls'

        # add the urls from the django_example module after other translatable URL patterns
        settings['ADDON_URLS_I18N_LAST'] = 'django_example.urls'

        return settings
Did this answer your question?