Configuration

The following configuration can be provided in your settings.py:

COTTON_DIR

str (default: 'cotton')

Change the default path in your templates directory where cotton components can be placed, for example "components". If a component is not found there, cotton still falls back to the default cotton directory.

COTTON_BASE_DIR

str (default: None)

The base directory where, in addition to the app folders, cotton will search for the "templates" directory (see above). If not set, the BASE_DIR generated by django-admin startproject is used as a fallback, if it exists.

COTTON_SNAKE_CASED_NAMES

bool (default: True)

By default component filenames are snake_case. Set this to False to use kebab-case filenames instead. If the kebab-case file is not found, cotton still falls back to the snake_case version.

For example, <c-my-button /> resolves to:

  • True (default): cotton/my_button.html
  • False: cotton/my-button.html

COTTON_ISOLATE_BY_DEFAULT

bool (default: False)

When set to True, every component is rendered with Smart Isolation: it cannot see variables from the surrounding parent template (preventing accidental context leaks), but it does still receive global context-processor output such as request, user, messages, perms and any of your own custom processors.

Processor output is captured once per request and reused across every component on the page, so there are no extra processor invocations regardless of how many components you render.

For total isolation (block context processors too), add the only flag to an individual component.

This setting replaces the experimental COTTON_ENABLE_CONTEXT_ISOLATION flag, which continues to work but emits a DeprecationWarning.

back Python API
next Ecosystem

View this page as markdown, handy as context for your AI tools. Full index at /llms.txt. Spotted a mistake? Edit this page on GitHub.