Settings¶

Cubane provides a helper method for setting up its default setting environment. You can simply call default_env() from within your project’s settings file in order to setup all default settings for Cubane. Of course, you can then change those defaults to specific values you require.

Default Settings¶

The default settings helper has been designed to allow you to setup all common application settings to get you up and running quickly. Place the following code in your settings.py:

from cubane.settings import default_env
env = default_env(
    __name__,
    'my-website-domain.com'
)

And that’s it. You can now overwrite particular settings to your requirements. By default, Cubane will set up the database name to match the domain name, which would be my_website_domain_com. Please note that hyphen and dot characters have been replaced with underscore characters automatically.

Note

The default database engine used by Cubane is PostgreSQL (django.db.backends.postgresql_psycopg2). The settings variable DATABASES is setup automatically to reflect PostgreSQL with the default database name as described above.

If you like to use a different database engine altogether, you need to setup DATABASES by yourself manually.

The full signature of the default_env() method is given below. We will walk through the arguments that can be passed to default_env() in the following.

default_env(module_name, domain_name, admin_email, db_name=None, test=None, debug=None, debug_toolbar=False, high_res_images=False, image_credits=False, pull_host=None, pull_sudo=None, csrf=False, ssl=False)[source]¶: Applies a set of default settings for the given settings module.

module_name

The module_name argument is the first argument and is required. In order for Cubane to setup default settings, it needs to know the settings module to which settings are applied. When calling default_env() from within your application settings file, you would usually pass in __name__ to identify the settings module.

domain_name

The domain_name argument is the second argument and is required. Cubane will construct all internal website links based on the given domain name. It will also derive the name of the database from the given domain name unless the db_name argument (optional) is given. The name of the database is equivalent to the domain name, where hyphen and dot characters have been replaced with underscore characters.

admin_email

The admin_email argument is the third argument and is required. Cubane will set up the default administrator of the website with the email address provided. The default logging mechanism will send crash reports via email to this email address in Production mode.

db_name

Optional. Cubane will derive the database from the domain name if this argument is not given. However – if provided – the database name is configured to the given name.

test

Optional. By default None. If set to True, then Cubane will setup itself to run under unit test. By default, Cubane will determine automatically whether it is running under test or not.

debug

Optional. By default None. If set to True, Cubane will run in Debug mode and the settings variable DEBUG will be set to True. If set to False, then Cubane will run in Production mode and the settings variable DEBUG is set to False.

By default, Cubane will determine if it runs in Production or Debug mode automatically by evaluating the environment variable DEV_MODE. If it is set to 1, then Debug mode is assumed; otherwise Production mode.

debug_toolbar

Optional. By default False. If set to True, then Cubane will automatically load the Django Debug Toolbar. If you use this argument, you may have to install additional packages. Please refer to the documentation of Django Debug Toolbar for more information.

high_res_images

Optional. By default False. If set to True, then Cubane will extend the default set of image sizes by two high-resolution image sizes.

See also

Please refer to the IMAGE_SIZES settings variable for more information.

pull_host

Optional. By default None. If set, the pull_host argument declares the hostname of the production server from which the deployed website’s data (including database and media data) can be pulled from by using Cubane’s pull mechanism. By default, the host is determined by the domain name.

pull_sudo

Optional. By default None. If set, the pull_sudo argument declares the username of the account that is used for hosting the website on a production system. By default, the username is assumed to be identical with the domain name.

csrf

Optional. By default False. If the csrf argument is set to True, Cubane and the Cubane backend system are configured to use Django’s Cross Site Request Forgery Protection Mechanism (CSRF).

Enabling csrf will automatically set up the correct middleware for MIDDLEWARE_CLASSES.

ssl

Optional. By default False. If the ssl argument is set to True, the Cubane frontend and backend systems are configured to run in HTTPS mode. All internal URLs and redirects will be based on HTTPS rather than HTTP.

Enabling ssl will automatically set up an additional middleware for MIDDLEWARE_CLASSES, which makes sure that internal redirect responses will automatically include https.

Installed Apps¶

When using the default_env() helper function to set up the default settings environment for Cubane, a settings environment object is returned.

class cubane.settings.SettingWrapper¶: The settings environment object allows for further manipulation of the settings environment, for example, it allows you to add installed apps.

add_apps(self, apps=None)¶: Adds the given list of Django apps to the list of installed apps in the correct order, so that certain order constraints are maintained.

apps

List of Django apps to be added to the list of installed apps.

Note

It is important that django.contrib.staticfiles is loaded after cubane, because Cubane changes certain aspects of the runserver management command. Those overwrite would be invalidated by staticfiles, if the order is reversed.

The add_apps() method of the settings environment object will take care of this for you automatically.

Let’s consider a code example:

from cubane.settings import default_env
env = default_env(
    __name__,
    'my-website-domain.com'
)

...

env.add_apps([
    'cubane',
    'cubane.backend',
    'cubane.fonts',
    'cubane.svgicons',
    'myApp'
])

First, a default setting environment is created and returned by default_env(). Then we use the settings environment object to install additional Django apps.

add_apps(self, apps=None): Adds the given list of Django apps to the list of installed apps in the correct order, so that certain order constraints are maintained.

apps

List of Django apps to be added to the list of installed apps.

Setup Template Context Processors¶

Cubane will setup a default configuration for TEMPLATES automatically with a default set of template context processors.

The settings environment object provides a helper method for adding additional template context processors conveniently:

add_template_context_processors(self, template_context_processors)¶: Adds the given list of Django template context processors to the list of installed context processors for the default template setup.

template_context_processors

List of template context processors to be added to the default template settings.

Note

You may not be able to use this helper method if your template setup differs from the one Cubane is setting up by default.

System Settings¶

The following settings control various aspects of the Cubane platform in general and are not necessarily tied to one specific aspect of the platform or refer to standard Django settings variables.

DEBUG

Set by Cubane based on the debug argument of the default_env() helper function. If no such argument is given, Cubane will determine Debug mode based on the presence of the environment variable DEV_MODE. If DEV_MODE is equal to 1, then DEBUG is set to True, otherwise, Production mode is assumed and DEBUG is set to False.

DATABASES

Cubane will set up a default database configuration based on PostgreSQL, where the name of the database is derived from the given domain name. Hyphens and dot characters are replaced with underscore characters. If a specific database name is given, then such database name is used instead.
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': '<db_name>'
    }
}

INSTALLED_APPS

By default, Cubane will setup INSTALLED_APPS with a list of apps that are required by Cubane.
INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.sitemaps',
    'django.contrib.staticfiles'
)
Note

You can use the add_apps() settings environment method to add additional apps conveniently. However, you can also simply add your own apps to INSTALLED_APPS or overwrite the list entirely.

It is important that django.contrib.staticfiles is loaded after cubane as described within the Installed Apps section. The add_apps() settings environment method will take care of this automatically.

MIDDLEWARE_CLASSES

By default, Cubane will load a number of default middleware classes automatically. This set of middleware is important to Cubane and – in particular – Cubane’s backend system.

Feels free to add your own middleware as you require. This list is simply a default list of middleware that Cubane’s default_env() settings helper function will setup automatically:
MIDDLEWARE_CLASSES = (
    'django.middleware.common.CommonMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'cubane.middleware.SettingsMiddleware',
)
Note

When passing True for the csrf argument to the default_env() settings helper function, then one additional middleware is added to the beginning of the list of middleware:
MIDDLEWARE_CLASSES = (
    'django.middleware.csrf.CsrfViewMiddleware',
) + MIDDLEWARE_CLASSES
Likewise, when passing True for the ssl argument to the default_env() settings helper function, then one additional middleware is added to the end of the list of middleware:
MIDDLEWARE_CLASSES += (
    'cubane.middleware.SSLResponseRedirectMiddleware',
)
Finally, when passing True for the debug_toolbar argument to the default_env() settings helper function, then one additional middleware is added to the beginning of the list of middleware:
MIDDLEWARE_CLASSES = (
    'debug_toolbar.middleware.DebugToolbarMiddleware',
) + MIDDLEWARE_CLASSES

TEMPLATES

Cubane will setup templates automatically to use the Django template system.

The base path for templates is set to templates/ relative to your project’s base folder.

The following list of context processors are loaded:
[
    'django.contrib.auth.context_processors.auth',
    'django.template.context_processors.debug',
    'django.template.context_processors.media',
    'django.template.context_processors.request',
    'django.contrib.messages.context_processors.messages',
    'cubane.context_processors.config',
    'cubane.context_processors.backend'
]
See also

You can use the add_template_context_processors() method of the settings environment object in order to add additional template context processors conveniently.

Finally, the following template loaders are set up by default:
[
    'django.template.loaders.filesystem.Loader',
    'django.template.loaders.app_directories.Loader'
]
Note

In Production mode, the template loader system is set up using Django’s template cache loader instead:
[
    ('django.template.loaders.cached.Loader', [
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader'
    ])
]

APPEND_SLASH

Django can redirect automatically by adding a missing slash to the end of the current URL if the current URL would otherwise result in an HTTP 404 response. This mechanism is used by Cubane by default and has an impact in how Cubane constructs URLs in general.
APPEND_SLASH = True

PREPEND_WWW

Django can redirect automatically by adding a missing www sub-domain to the current URL. This mechanism is used by Cubane in Production mode and has an impact on how Cubane constructs URLs in general.
PREPEND_WWW = not DEBUG

LOGGING

Django provides a sophisticated logging mechanism. By default, Cubane will setup your website to send an email to all administrators on an error condition if the system is running in Production mode.

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse'
        }
    },
    'handlers': {
        'mail_admins': {
            'level': 'ERROR',
            'filters': ['require_debug_false'],
            'class': 'django.utils.log.AdminEmailHandler'
        }
    },
    'loggers': {
        'django.request': {
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': True,
        },
    }
}

Note

Cubane will set up one administrator for your website automatically by using the email address provided via the admin_email argument of the default_env() settings helper function.

HANDLER_404

Cubane declares a default view handler for presenting an HTTP 404 page:
HANDLER_404 = 'cubane.default_views.custom404'
The default HTTP 404 view handler will present a Cubane-specific default page in the case the document was not found (404).

If the CMS system is used then a particular CMS page is configured to be used for the purpose of presenting content to visitors in case of the HTTP 404 status code.

HANDLER_500

Cubane declares a default view handler for presenting an HTTP 500 page:
HANDLER_500 = 'cubane.default_views.custom500'
The default HTTP 500 view handler will present a Cubane-specific default page in the case that the system raises an error.

CUBANE_PULL

Cubane provides a mechanism by which a deployed website’s content including the database and uploaded media assets can be downloaded to a development environment in order to replicate the exact circumstances of a deployed website.

By default, Cubane will set up the pull mechanism based on the database name, the domain name and other arguments such as pull_host and pull_sudo of the default_env() settings helper function automatically.

See also

Please refer to the Pulling Production Data section for more information on how to configure and use the pull mechanism.

Cubane Base Path Settings¶

The following settings define some base paths that are relevant for Cubane. All paths are derived automatically when using the default_env() settings helper function.

CUBANE_PATH

The absolute full path to the Cubane package that is used. By default, Cubane will determine this path automatically.

BASE_PATH

The absolute full path to the application package for your application that is using Cubane. By default, Cubane will determine this path automatically.

PUBLIC_HTML_ROOT

The absolute path of the website’s public_html folder, which contains all static media assets as well as cached data as part of Cubane’s cache system in Production mode.

By default, the public_html folder is assumed to be two levels below the application’s execution folder:
<home-folder>/
    app/
        cubane/
        myAppRootFolder/
    public_html/
        static/
        media/
        cache/
If you applications execution folder is myAppRootFolder, then we assume that the public_html folder is two levels below as outlined in the example above.

You can read more about this particular layout within the Deployment section.

CACHE_ROOT

The absolute folder where Cubane’s cache system will generate full page cache data for the website. Once a cached version of a page has been generated, it is assumed that such file is accessible through the web server.

By default, Cubane will set the CACHE_ROOT folder to be /cache/ relative to the public_html folder for the website (See PUBLIC_HTML_ROOT).

Timezone, Language and Formatting Settings¶

The default settings helper default_env() will set up a number of Django’s settings variables for timezone, language, and formatting. You can change those to your requirements.

In addition, Cubane provides a few date and time-related settings variables, such as STR_DATE_FORMAT as well.

TIME_ZONE

The default time zone for a new Cubane setup is Europe/London:
TIME_ZONE = 'Europe/London'

LANGUAGE_CODE

The default language code for a new Cubane setup is British English:
LANGUAGE_CODE = 'en-GB'

USE_I18N

Django’s internationalisation is turned off by default:
USE_I18N = False

DATE_FORMAT

The default date format for a new Cubane setup is dd/mm/YYYY, for example 24/01/2017:
DATE_FORMAT = 'd/m/Y'

TIME_FORMAT

The default time format for a new Cubane setup is P, for example, 4 p.m.:
TIME_FORMAT = 'P'

DATETIME_FORMAT

The default format for a timestamp for a new Cubane setup is dd/mm/YYYY HH:MM, for example, 24/01/2017 07:49:
DATETIME_FORMAT = 'd/m/Y H:i'

DATE_INPUT_FORMATS

Cubane set up a number of default date input patterns when parsing dates:

DATE_INPUT_FORMATS = (
    '%Y-%m-%d',   # 2006-10-25s
    '%d/%m/%Y',   # 25/10/2006
    '%d/%m/%y',   # 25/10/06
    '%d-%b-%y',   # 30-Dec-06
)

DATETIME_INPUT_FORMATS

Cubane setups a number of default timestamp input patterns when parsing timestamps:

DATETIME_INPUT_FORMATS = (
    '%Y-%m-%dT%H:%M',        # '2010-10-10T10:15'
    '%d/%m/%Y %H:%M:%S',     # '25/10/2006 14:30:59'
    '%d/%m/%Y %H:%M:%S.%f',  # '25/10/2006 14:30:59.000200'
    '%d/%m/%Y %H:%M',        # '25/10/2006 14:30'
    '%d/%m/%Y',              # '25/10/2006'
    '%d/%m/%y %H:%M:%S',     # '25/10/06 14:30:59'
    '%d/%m/%y %H:%M:%S.%f',  # '25/10/06 14:30:59.000200'
    '%d/%m/%y %H:%M',        # '25/10/06 14:30'
    '%d/%m/%y',              # '25/10/06'
)

STR_DATE_FORMAT

Whenever Cubane generates specific files, such as exporting data within Cubane’s backend system as CSV files, the generated filename may contain information about the date and time when the file was generated.

The date and time format used within those filenames is determined by STR_DATE_FORMAT. By default, the current date is used in the format dd/mm/YYYY, e.g. 24/01/2017:
STR_DATE_FORMAT = '%d_%m_%Y'

Backend Settings¶

The following settings control various aspect of Cubane’s backend system. You can read more about Cubane’s backend system within the Backend System section.

CUBANE_BACKEND_PERMISSIONS

Cubane’s backend system tests if the current user has permission to execute certain actions in the system. Generally, a specific view may declare that a create action is not available, to begin with.

However – in addition – the Cubane backend system can also verify permissions on a per-user basis. Therefore a set of users may have a specific permission to edit a certain type of entity in the system; others may not have such permission.

By default, Cubane will not enforce permissions on a per-user basis:
CUBANE_BACKEND_PERMISSIONS = False
However, you can enable such permissions to take effect by setting CUBANE_BACKEND_PERMISSIONS to True.

CUBANE_BACKEND_MEDIA

Cubane’s backend system required Cubane’s media component and will present a section within the backend for managing media assets by default.
CUBANE_BACKEND_MEDIA = True
If you do not require media assets to be managed within the backend system, you can turn the media gallery off by setting CUBANE_BACKEND_MEDIA to False.

CLIENT_LOGO

Cubane’s backend system will present an image on the login page that is meant to represent the logo of the website’s business or owner.

By default, the image is resolved by the path img/client-logo.png by using Django’s staticfiles resolution mechanism.
CLIENT_LOGO = 'client-logo.png'
If no file is available, then the name of the website as configured by the website’s CMS settings are used.

If no such name is available, then the domain name as specified through the domain_name argument of the default_env() function is used instead.

MAX_LISTING_COLUMNS

Defines the maximum number of columns for table-based views within Cubane’s backend system.

By default, the maximum number of full columns in the backend is limited to six:
MAX_LISTING_COLUMNS = 6
Note

Cubane’s backend system may present certain columns as half columns, which means that Cubane’s backend system may present up to 12 half columns.

Authentication Settings¶

Cubane is using Django’s default authentication system for user authentication for the backend system as well as the frontend if required.

AUTHENTICATION_BACKENDS

Django’s default user authentication backend is django.contrib.auth.backends.ModelBackend, which authenticates user accounts via their username and password.

By default, Cubane adds an additional authentication backend that allows users to be authenticated via their email address and password as well.
AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.ModelBackend',
    'cubane.backends.EmailAuthBackend',
)

Static Assets Settings¶

Cubane is using Django’s staticfiles app for managing static media assets. The settings helper function default_env() will set up a number of settings variables regarding static media assets automatically, so you do not have to.

You can read more about how Django manages static files by referring to the Managing static files section of the Django documentation.

STATIC_URL

The STATIC_URL settings variable declares the relative URL path to static media. Cubane will set this by default to /static/:
STATIC_URL = '/static/'

STATIC_ROOT

The absolute path where static media assets are stored. By default, Cubane will set this path to /static/ relative to the public_html folder (See PUBLIC_HTML_ROOT).

STATICFILES_DIRS

List of absolute paths to where Django will look for additional static media assets that are not bound to a particular app. Cubane sets this variable to point to the /static/ folder relative to the base path of the application.
STATICFILES_DIRS = (
    os.path.join(m.BASE_PATH, 'static'),
)

RESOURCES

The RESOURCES settings variable declares a number of resource buckets. All resources from each app listed per bucket are then combined and minified for each resource type.

By default, Cubane declares an empty set of resources:
RESOURCES = {}
You need to declare your own resources in your application’s settings file.

See also

Please refer to the Declaring Resource Buckets section for more information on how to declare resource buckets.

CSS_MEDIA

When using Cubane’s resource system, Cubane allows for different CSS media types. The CSS_MEDIA settings variable defines a list of allowed CSS media types.

By default, Cubane understands the two CSS media types screen and print:
CSS_MEDIA = ['screen', 'print']

REQUIRE_JS

Cubane can compile RequireJS based javascript sources. RequireJS is a Javascript file and module loader.

The REQUIRE_JS settings variable declares a list of javascript sources that are using RequireJS.

By default, no RequireJS sources are setup:
REQUIRE_JS = []
See also

Please refer to the Using RequireJS section for more information on how to use RequireJS in your project.

Favicon Settings¶

Cubane can generate a number of different favicon versions based on one input image. There are a number of settings variables that control the way favourite icons are generated.

Media Settings¶

Cubane provides a number of ways to work with Media. Please read more about Media in general within the Media section. The following settings control various aspects of Cubane’s media pipeline:

MEDIA_ROOT

The absolute path to the folder containing user-uploaded content. In Debug mode, MEDIA_ROOT is set to a folder /media/ relative to the base path of your application.

In Production mode, MEDIA_ROOT is set to a folder /media/ relative to the public_html folder PUBLIC_HTML_ROOT.

MEDIA_URL

The MEDIA_URL settings variable defines the prefix for the URL to media assets, which is set to media/ by default:
MEDIA_URL = 'media/'

MEDIA_API_URL

The media API is introduced by Cubane to serve user-uploaded assets not directly through the web server in Production mode, but through the entire python/Django/Cubane pipeline in order to pre-process media assets before they are served to clients.

By default, MEDIA_API_URL is set to media-api/:
MEDIA_API_URL = 'media-api/'
See also

You can find more information on the media API within the Media API URLs section.

MINIFY_CMD_JS

The command line that is executed in order to compress Javascript resources. The Javascript source is piped into the process on the standard input channel and the (compressed) result is read from the standard output channel of the process. By default Google’s Closure compiler is used for compressing Javascript sources.

MINIFY_CMD_CSS

The command line that is executed in order to compress CSS resources. The CSS source is piped into the process on the standard input channel and the (compressed) result is read from the standard output channel of the process. By default Yahoo’s YUI Compressor is used for compressing CSS sources.

Note

The YUI library is no longer actively maintained and we will change the default dependency to the YUI Compressor eventually.

IMAGE_SIZES

Cubane’s media system can generate responsive image versions in different resolution, so that the correct image can be delivered to the correct client based on physical device properties, such as resolution.

The following (named) image sizes are supported by Cubane:

xx-small

x-small

small

medium

large

x-large

Optionally this list can be extended by:

xx-large

xxx-large

The settings variable IMAGE_SIZES declares a list of image sizes that are used by your application alongside the corresponding width (in pixels) for each of them. You may define a subset of all supported image sizes but you cannot invent new image sizes.
IMAGE_SIZES = {
    'xx-small':  50,
    'x-small':  160,
    'small':    320,
    'medium':   640,
    'large':    900,
    'x-large': 1200
}
Those default image sizes are somewhat arbitrary and in most cases you would want to adjust those values depending on your specific requirements for optimal performance.

See also

You can read more about responsive image versions within the Responsive Image Sizes section.

DEFAULT_IMAGE_SIZE

In order to support a default version for response image sizes (see IMAGE_SIZES), a default image size is defined via DEFAULT_IMAGE_SIZE.

Please refer to IMAGE_SIZES for a list of all supported image sizes.

The DEFAULT_IMAGE_SIZE declares the default size which is used for clients that are not interested in downloading a responsive image based on client properties, such as resolution.

By default, Cubane is using the x-large image version as the default image version:
DEFAULT_IMAGE_SIZE = 'x-large'
See also

You can read more about responsive image versions within the Responsive Image Sizes section.

CMS_EDITOR_DEFAULT_IMAGE_SIZE

When working with images within Cubane’s content management editor, a default image version is used that is not necessarily depending on properties of the device, such as screen resolution.

Of course, this is only for the purpose of the editor. When presenting a page to the general public, the full responsive image machinery is used instead.

By default, Cubane is using the x-large image size for this purpose:
CMS_EDITOR_DEFAULT_IMAGE_SIZE = 'x-large'

DISABLE_DEVICE_RATIO

By default, cubane.medialoader will take the device pixel ratio into consideration when determining the actual image resolution that is required when loading an image on the website. Some devices may have a high-resolution display, where the device pixel ratio is greater than one.
DISABLE_DEVICE_RATIO = False
You can ignore the device pixel ratio, by setting DISABLE_DEVICE_RATIO to True.

IMAGE_COMPRESSION_QUALITY

The default compression level for jpeg images as an integer. Whenever Cubane saves a jpeg image, then the given jpeg compression is used to compress the image. The compression level only applies to jpeg images has no effect on any other image file format.
IMAGE_COMPRESSION_QUALITY = 85
Note

Cubane may apply a lower compression level as specified under some circumstances, for example for very low-resolution image versions or if the image source is a jpeg and the compression level of that file is estimated to be lower than the default compression level.

Further, the original image that is uploaded might be resized (and subsequently compressed again) if the original image is too large (See IMG_MAX_WIDTH). In this case, the highest possible compression quality is used and IMAGE_COMPRESSION_QUALITY is ignored.

IMG_MAX_WIDTH

The maximum width for an original image that is uploaded in pixels. When uploading media assets using Cubane’s media system, any original image may be resized if the width of the original image is larger than the maximum width as specified by IMG_MAX_WIDTH.

By default, the maximum image width is 2,400 pixels:
IMG_MAX_WIDTH = 2400
This process exists in order to keep uploaded media assets to a certain maximum size and preventing storing original images that are too large. Also, the processing time for resizing and generating different image version based on the original image is greatly improved if the original image size is reduced.

Note

You can turn off this behaviour by setting IMG_MAX_WIDTH to None.

See also

For more information on Cubane’s maximum image size, please refer to the Maximum Image Width section.

IMAGE_SHAPES

Cubane can manage a set of distinct image shapes. Whenever an image is referenced within a template, for example, a shape can be specified. Then Cubane’s media system will render the particular image in a specific shape as specified.

A shape is ultimately a specific aspect ratio for an image and Cubane will crop uploaded media assets to match all shapes specified automatically.

By default, no image shapes are specified:
IMAGE_SHAPES = {}
See also

Please refer to the Image Shapes section for more information on image shapes and how to declare and use them.

DEFAULT_IMAGE_SHAPE

Cubane’s image shapes are declared via IMAGE_SHAPES. In addition, the general image shape original is reserved in order to refer to the actual image aspect ratio of the image as it has been uploaded.

Whenever an image is requested, where the target image shape is not further specified, then Cubane will simply return the image in the shape as specified by DEFAULT_IMAGE_SHAPE. By default, this is the original shape, which means that the image shape is the actual shape of the image as it has been uploaded.
DEFAULT_IMAGE_SHAPE = 'original'

IMAGE_ART_DIRECTION

Cubane can use different shapes for different devices dynamically based on properties if the screen for example. This process is called Art Direction and can greatly improve the visual quality of your website.

By default, art direction is not configured:
IMAGE_ART_DIRECTION = {}
See also

You can find more information on how to use art direction in the Art Direction section.

IMAGE_CREDITS

For some applications, you may want to store some additional credit information with each uploaded media asset. You can enable image credits by setting IMAGE_CREDITS to True.

By default, Cubane will not store or maintain image credits information:
IMAGE_CREDITS = False

IMAGE_EXTRA_TITLE

For some application, you may require additional meta information about uploaded media assets, such as an additional title or description. You can enable this functionality by setting IMAGE_EXTRA_TITLE to True.

By default, Cubane will not store or maintain an extra image title:
IMAGE_EXTRA_TITLE = False

FILE_UPLOAD_HANDLERS

Cubane will setup your website to use temporary files when uploading media assets:
FILE_UPLOAD_HANDLERS = (
    'django.core.files.uploadhandler.TemporaryFileUploadHandler',
)

Font Settings¶

Cubane’s font system allows for custom web fonts to be integrated into your applications very easily. There are a few settings variables that control the integration. You can read more about Cubane’s font system within the Fonts section.

CUBANE_FONT_ROOT

The absolute path to a folder that will be used to store font files. Cubane’s font system will create a sub-folder within CUBANE_FONT_ROOT for each font that is used.

By default, CUBANE_FONT_ROOT is set to /fonts/ relative to the media root folder MEDIA_ROOT.

See also

You can read more about Cubane’s font caching mechanism within the Font Cache section.

CUBANE_FONT_BACKENDS

Cubane’s font system has the concept of font backends. A font backend is responsible for finding and downloading a font by its name from an external source. Multiple font backends can be set up to be used as font sources simultaneously.

By default, Cubane provides and set up one default font backend, which is based on the google-webfonts-helper by Mario Ranftl:
CUBANE_FONT_BACKENDS = [
    'cubane.fonts.backends.GoogleFontsBackend',
]
See also

You can read more about Cubane’s font backend mechanism within the Font Backends section.

CMS Settings¶

Cubane’s Content Management Component is controlled by the following settings. Please read more about Cubane’s CMS system within the Content Management section.

CMS

When using Cubane’s content management system (CMS), you need to derive your own class from cubane.cms.views.CMS. The base class implementation provides a number of core services for Cubane’s CMS component and gives your application the opportunity to overwrite specific aspects of the system as required.

In your application settings, you would need to declare to Cubane what the CMS class implementation is. You do this by declaring the CMS settings variable to a string that reflects the full python path and the name of your class that derives from the CMS base class cubane.cms.views.CMS.

By default, the CMS settings variable is not set and you’re application will not start if CMS remains unset (assuming the CMS component is used).

Let’s assume that you’ve declared your CMS class in the python module myApp.views and the derived class is named MyAppCMS, then you would declare the CMS settings variable in the following way:
CMS = 'myApp.views.MyAppCMS'
See also

Please refer to the Content Management section for further information on Cubane’s content management system.

CMS_SETTINGS_MODEL

Cubane’s content management system (CMS) requires a database model to store application setting. Those settings can typically be changed by website owners or content authors.

You have to derive your own class from the base model class cubane.cms.models.SettingsBase. The base model class is defined as an abstract Django model class.

Deriving from cubane.cms.models.SettingsBase gives you the opportunity to add your own application settings as required.

In your application settings, you would need to declare to Cubane what the settings model class implementation is. You do this by declaring the CMS_SETTINGS_MODEL settings variable to a string that reflects the full python path and the name of your class that derives from the settings model base class cubane.cms.models.SettingsBase.

By default, the CMS_SETTINGS_MODEL settings variable is not set and your application will not start if CMS_SETTINGS_MODEL remains unset (assuming the CMS component is used).

Let’s assume that you’ve declared your settings model class in the python module myApp.models and the derived class is named Settings, then you would declare the CMS_SETTINGS_MODEL settings variable in the following way:
CMS_SETTINGS_MODEL = 'myApp.models.Settings'
See also

Please refer to the Content Management section for further information on Cubane’s content management system.

CMS_PAGE_MODEL

Cubane’s content management system (CMS) requires a database model to represent basic CMS pages. By default, Cubane’s CMS system is configured to use the model class cubane.cms.models.Page which is ready to go and suitable for most basic needs.

However, if you ever wish to extend Cubane’s page model in the future or you have specific requirements that would require you to add custom fields for every page then you can also derive your own class from cubane.cms.models.PageAbstract instead.

If you derive your own class, then you need to declare to Cubane what the page model class implementation is within your application settings. You do this by declaring the CMS_PAGE_MODEL settings variable to a string that reflects the full python path and the name of your class that derives from the abstract page model class cubane.cms.models.PageAbstract.

By default, the CMS_PAGE_MODEL settings variable is not set. However, you do not necessarily use your own page model, in which case the default page model cubane.cms.models.Page is used instead.

Tip

We advise deriving your own class in any case so that you could extend the page model later in the process if you ever needed to. Declaring your own page model later in the process with existing data already on production system tends to be much more difficult.

Let’s assume that you’ve declared your page model class in the python module myApp.models and the derived class is named CustomPage, then you would declare the CMS_PAGE_MODEL settings variable in the following way:
CMS_PAGE_MODEL = 'myApp.models.CustomPage'
See also

Please refer to the Content Management section for further information on Cubane’s content management system.

CMS_NAVIGATION

Cubane’s content management system has a concept for navigation. A navigation is a set of navigable targets, such as pages. Multiple navigations can be set up, for example, you may define a navigation for the main header navigation of the website and one for the footer.

The CMS_NAVIGATION settings variable declares a list of known navigation areas and assigns a unique name to each of them. The list is constructed out of tuples, where the first component is the unique name of the navigation area and the second element is the name of the area as it is displayed within the backend system for example. Structurally CMS_NAVIGATION is similarly constructed as Django’s form field choices.
CMS_NAVIGATION = (
    ('header', 'Header'),
    ('footer', 'Footer')
)
By default, Cubane will set up two navigation areas for you automatically, a header navigation and a footer navigation.

CMS_NAVIGATION_RELATED_FIELDS

When Cubane loads the navigation for a website, you can easily control how related data (such as images for example) are fetched at the same time. By default, Cubane will load related images for each navigable target as part of the navigation:
CMS_NAVIGATION_RELATED_FIELDS = ['image']
Note

Related fields must exist and are applied for loading items derived from PageAbstract.

CMS_NAVIGATION_INCLUDE_CHILD_PAGES

Cubane’s CMS system provides the concept for modelling child pages that may be attached to certain pages, like blog posts, projects or services. The navigation system can load child pages as part of the navigation if CMS_NAVIGATION_INCLUDE_CHILD_PAGES is set to True; however, by default child pages are not loaded as part of the navigation.
CMS_NAVIGATION_INCLUDE_CHILD_PAGES = False

CMS_TEMPLATES

Cubane’s CMS system allows for multiple page templates. A template can be chosen by content authors on a per-page basis if required. In our experience, the fewer templates authors can choose from the better. However, sometimes you simply need to provide multiple arrangements for your content, in which case you can define multiple page templates as a list of tuples.

The first element declares the relative path to the template file that is used to render the page while the second element gives a name of the template that is displayed to content authors to choose from.

By default, Cubane will provide a standard template like the code example below. In most cases, you would want to replace the default settings to declare your own templates.
CMS_TEMPLATES = [
    ('cubane/cms/default_template.html', 'Default Template')
]

CMS_SLOTNAMES

Cubane’s CMS system organises editable content in content slots. Each slot is an area of a page that content authors can fill with arbitrary content.

Simply declare a list of unique names for your slots. Not all page templates may use all slots, but every slot is used by any template must be declared through the CMS_SLOTNAMES settings variable.

By default, Cubane declares only one slot with the name content:
CMS_SLOTNAMES = ['content']

CMS_DEFAULT_SLOTNAME

When presenting multiple slots for any given page within Cubane’s backend system, one slot is activated by default. Content authors can then use the content editor as part of the system to write content for the active slot.

The settings variable CMS_DEFAULT_SLOTNAME gives the unique name of the slot that is activated by default when editing a page within the backend system.

If CMS_DEFAULT_SLOTNAME is set to None, then the first slot on the page (in DOM order) is activated automatically.

By default, the slot with the name content is activated automatically:
CMS_DEFAULT_SLOTNAME = 'content'

CMS_RENDER_SLOT_CONTAINER

When rendering the content for any given slot, the system will simply render the content for the given slot when using the slot template tag.

However, if the settings variable CMS_RENDER_SLOT_CONTAINER is set to True, then Cubane will wrap any slot content with a container element in the following way:
<div class="cms-slot-container">
    ... slot content ...
</div>
By default, Cubane will not wrap slot content automatically.
CMS_RENDER_SLOT_CONTAINER = False
Note

When rendering content in preview mode, Cubane will automatically wrap slot content by using the following markup:
<div class="cms-slot" data-slotname="content">
    ... slot content ...
</div>
This is independent of the CMS_RENDER_SLOT_CONTAINER variable; therefore when rendering slot content in preview mode with CMS_RENDER_SLOT_CONTAINER set to True, slot content is actually wrapped twice:
<div class="cms-slot" data-slotname="content">
    <div class="cms-slot-container">
        ... slot content ...
    </div>
</div>

CMS_EXCERPT_LENGTH

Cubane’s CMS system can present brief excerpt text for content items, such as pages or child pages. The settings variable CMS_EXCERPT_LENGTH defines the maximum number of characters that is used to present excerpt text before it is truncated with ….

This maximum character limit is imposed on custom excerpt text provided by content authors and automatically generated excerpt text alike.

By default, the maximum amount of characters for any excerpt text is 60 characters:
CMS_EXCERPT_LENGTH = 60

CMS_NO_AUTO_EXCERPT

Cubane’s CMS system can generate a brief excerpt for each content item, such as a page or child page automatically based on the actual content of the page assigned to slots.

By default, an excerpt text is provided by content authors. If no excerpt text has been provided, it is generated automatically unless the settings variable CMS_NO_AUTO_EXCERPT is set to True.

By default, the settings variable CMS_NO_AUTO_EXCERPT is set to False and missing excerpt text is generated automatically:
CMS_NO_AUTO_EXCERPT = False

CMS_TEST_SPF

The Sender Policy Framework (SPF) is a simple validation system to detect email spoofing. Mail Exchangers can check that incoming mail from a domain name comes from a host authorised by the domain name system. See more information on the Sender Policy Framework on Wikipedia.

Most websites need to send an email. Perhaps your website provides a simple inquiry form or even offers products for sale. In order to help you to setup and verify the correct presence of an SPF record for your website, Cubane will automatically check that SPF is verified whenever you change the settings of your website within the Cubane’s backend system (this is usually where to setup email details for the website).

When saving settings in Debug mode, Cubane will generate an error message regarding SPF but will allow you to save the settings. In Production mode, however, Cubane will not accept changes to settings if the SPF validation does not succeed or no SPF record is in place, to begin with.

You can turn SPF validation off by setting CMS_TEST_SPF to False. However, SPF validation is turned on by default:
CMS_TEST_SPF = True

CMS_BACKEND_SITEMAP

Cubane’s backend system can present a sitemap-like structural view of all your content within the backend. This feature is currently still in development and is turned off by default:
CMS_BACKEND_SITEMAP = False
You can turn this feature on by setting CMS_BACKEND_SITEMAP to True.

CMS_ADV_EDITOR_PLUGINS

By default, Cubane’s content editor is restricted to regular editing functionality only, which does not include visual aspects such as colours. In our experience, content authors should not be concerned about visual aspects of the site, they should only be concerned about the content itself.
CMS_ADV_EDITOR_PLUGINS = False
However, if you require additional capabilities, such as access to colour options within Cubane’s backend system for editing content, then you can enable this functionality by setting CMS_ADV_EDITOR_PLUGINS to True.

CACHE_ENABLED

Cubane’s CMS system provides a full page cache system that will speed up page loads drastically. Cubane’s cache system is designed to bypass the execution of WSGI, python, and Django all together for most of a website’s content.

The cache system is enabled by default:
CACHE_ENABLED = True

CACHE_PUBLISH_ENABLED

By default, a publish button is presented via the backend system that allows content editors to trigger the regeneration of the cache system manually.

Even with the cache system still active, the publish button can be disabled.

The publish button is enabled by default and is shown within the backend system whenever the cached data must be re-generated because content potentially changed.
CACHE_PUBLISH_ENABLED = True

PAGE_HIERARCHY

By default, Cubane allows for a flat list of pages to be created. Each page may declare a list of child pages of a certain type, such as blog post or service, but there is no real hierarchy of pages involved.

Cubane can support arbitrarily nested pages. Such hierarchy can then be used for example to drive the navigation structure of the website or to generate a list of nested sections for any given page. To enable support for nested page hierarchies, set the PAGE_HIERARCHY settings variable to True.

However, by default page hierarchies are not enabled:
PAGE_HIERARCHY = False

Enquiry Settings¶

Cubane’s Enquiry system (in combination with its content management component) can present contact forms and send rich HTML emails based on content controlled by content authors.

Please read more about Cubane’s enquiry system within the Enquiry Forms section.

ENQUIRY_MODEL

The enquiry system stores enquiry messages in a data model and makes enquiries accessible within Cubane’s backend system.

Additional metadata may be managed this way, such as information about actions are taken etc.

Because enquiries can be very specific to each business needs, you need to derive your own enquiry data model from cubane.enquiry.models.EnquiryBase.

Tip

We would advise keeping the amount of information that your customers would need to enter into an enquiry form as low as possible. There appears to be a direct relationship between the complexity of an enquiry form and the resulting conversion rate for successful enquiries.

Generally speaking: Increasing the complexity has a negative impact on the conversion rate.

In your application settings, you need to declare what your specific enquiry data model class is by declaring the python path and name of your class as a string.

Let’s assume that you’ve declared your enquiry model class in the python module myApp.models and the derived class is named Enquiry, then you would declare the ENQUIRY_MODEL settings variable in the following way:
ENQUIRY_MODEL = 'myApp.models.Enquiry'
See also

Please refer to the Enquiry Forms section for further information on Cubane’s enquiry system.

ENQUIRY_CLIENT_TEMPLATE

Cubane’s enquiry system may send two emails on every successful enquiry: One email is sent to the customer to acknowledge the reception of the enquiry; the second is sent to a dedicated email address that you decide in order to notify you about the enquiry.

While the template for rendering the email content for the first email is controlled through Cubane’s CMS system, the template that is used for the second email is controlled in your application setting.

Simply declare the path to any Django template file in your application settings file, for example:
ENQUIRY_CLIENT_TEMPLATE = 'myApp/mail/enquiry_client.html'
See also

Please refer to the Enquiry Forms section for further information on Cubane’s enquiry system.

Google Analytics¶

Cubane can integrate with Google Analytics out of the box. The google analytics key is usually configured within Cubane’s backend system (settings).

DEBUG_GOOGLE_ANALYTICS

Cubane provides various template tags for including Google Analytics on your website. All template tags require a valid Google Analytics Key to connect your website with a specific Google Analytics account.

In Production mode, this key is usually configured in your website’s CMS settings. In Debug mode, however, you may not want to pollute your production analytics account with development traffic.

Therefore, Cubane will not inject the Google Analytics key in Debug mode under any circumstances. The key is simply left empty. However, if you wish to use a specific Google Analytics key in Debug mode, for example, to test various aspects of your custom Google Analytics integration, then you can set this key up by setting DEBUG_GOOGLE_ANALYTICS equivalently.

By default, DEBUG_GOOGLE_ANALYTICS is set to None, which indicates that the system will not use any Google Analytics key at all.
DEBUG_GOOGLE_ANALYTICS = None

CUBANE_GOOGLE_ANALYTICS_ASYNC

By default, Cubane will generate markup for loading the Google Analytics client API code in the default way, which is synchronous:
CUBANE_GOOGLE_ANALYTICS_ASYNC = False
You can load the Google Analytics client API asynchronously by setting CUBANE_GOOGLE_ANALYTICS_ASYNC to True.

Google Maps¶

Cubane can integrate with the Google Maps API out of the box. You simply need to tell Cubane about the Google Map API key to use.

CUBANE_GOOGLE_MAP_API_KEY

The google map API key to use for integrating with the Google Map API. Please refer to the Google Map API Documentation for more information about how to receive a Google Map API key.

By default, the Google Map API key is not defined and you may not be able to use the Google Map API:
CUBANE_GOOGLE_MAP_API_KEY = ''

DEFAULT_MAP_LOCATION

When integrating the Google Map API, the backend system may present a google map control that allows your authors and website owners to declare a geographic position by moving a marker on a map or by searching for places.

The default geographic location that is used for the initial marker position and the centre position of the map is derived from DEFAULT_MAP_LOCATION.

By default, Cubane sets the following geographic location, which reflects Norwich, United Kingdom – The place where Cubane has been developed.
DEFAULT_MAP_LOCATION = [52.6370209, 1.2996577]

Pagination Settings¶

Cubane provides a default implementation for pagination of items, for example, blog posts. The following settings variable control the default settings for pagination.

DEFAULT_PAGE_SIZE

Defines the default number of items per page if no other CMS configuration has been provided.

By default, the number of items per page is ten:
DEFAULT_PAGE_SIZE = 10

DEFAULT_MIN_PAGE_SIZE

Declares the default minimum number of items per page. Visitors can switch between the minimum and the maximum number of items when using the pagination system to either show a limited number of items with a small page size or (usually) a very large number of items at once.

Usually, the minimum number of items is identical to the default page size:
DEFAULT_MIN_PAGE_SIZE = 10

DEFAULT_MAX_PAGE_SIZE

Defines the default maximum number of items per page. Visitors can switch between the minimum and the maximum number of items when using the pagination system to either show a limited number of items with a small page size or (usually) a very large number of items at once.

By the default, the maximum number of items per page when switching to a large page size is declared as 100 items per page.
DEFAULT_MAX_PAGE_SIZE = 100

Captcha Settings¶

Cubane can use a number of captcha implementations to be used for an enquiry form or used by yourself directly if needed.

CAPTCHA

Declares the type of captcha to use. By default, Cubane will not use any captcha by setting CAPTCHA to None.
CAPTCHA = None
Currently, only Google’s reCaptcha is supported. Please find more information about Google’s reCaptcha. Possible values for CAPTCHA are:

List of valid values for CAPTCHA settings variable.¶

Value Description

new_recaptcha Google’s reCaptcha

recaptcha Google’s previous version of reCaptcha (deprecated)

CAPTCHA_SITE_KEY

The site key for using Google’s reCaptcha. Please sign up with Google’s reCaptcha in order to receive a site key.

CAPTCHA_SECRET_KEY

The secret captcha key for using Google’s reCaptcha. Please sign up with Google’s reCaptcha in order to receive a secret key.

Email Settings¶

Cubane and Django can send emails on crash reports. Also, Cubane will send emails for other reasons, for example when using the built-in contact form. A number of configuration options are set by default_env() automatically, so you do not have to necessarily set those up.

EMAIL_SUBJECT_PREFIX

The default email subject prefix, which is used by Django whenever an email is sent to administrators or site managers is configured to include the domain name of your website:
EMAIL_SUBJECT_PREFIX = '[%s] ' % domain_name
domain_name refers to the domain_name argument of the default_env() settings helper function.

EMAIL_BACKEND

When in Debug mode, the email backend is set to django.core.mail.backends.console.EmailBackend in order to prevent emails being sent to real email accounts. This email backend will print emails on the console instead, rather than actually sending emails out:
if DEBUG:
    EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
In Test mode, EMAIL_BACKEND is set to django.core.mail.backends.locmem.EmailBackend instead, which will keep outgoing emails in local memory. This allows tests to inspect outgoing emails while under unit test:
if TEST:
    EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

Test Settings¶

A few settings variables are concerned about testing Cubane. By default, the settings helper function default_env() will determine automatically if the system is under test and will set the corresponding settings variables accordingly.

You can read more about testing Cubane within the Testing Cubane section.

TEST

Cubane will set TEST to True or False automatically based on command line arguments that invoked Cubane unless the test argument of the default_env() helper function has been set explicitly.

Note

Cubane will disable Django migrations if the system is under test.

TEST_FULL

When running under test, we distinguish two test modes: Full Testing and Fast Testing. In Full Testing mode, all unit tests are executed within the system using the default database driver for PostgreSQL. On an average machine, this process may take a few minutes.

In contrast to Full Testing, in Fast Testing mode Cubane will only execute a subset of unit tests (about 90 per cent of them). In particular slow tests are skipped. Further, the default database driver for Fast Testing mode is SqlLite, which tends to be a lot faster than PostgreSQL.

By default, TEST_FULL is set to False, unless the environment variable DEV_TEST_FULL is set to 1.

Note

Cubane provides two shell scripts to execute unit tests for Cubane: test will simply execute the default tests in Fast Testing mode, while test full will set the corresponding environment variables to put Cubane into Full Testing mode.

Please refer to the Testing Cubane section for more information on testing Cubane.