Quickstart

Install cotton

Run the following command:

pip install django-cotton

Then update your settings.py:

Automatic configuration:

INSTALLED_APPS = [
    'django_cotton',
]

This will automatically handle the settings.py adding the required loader and templatetags.

Customised configuration

If your project requires any non-default loaders or you do not wish Cotton to manage your settings, you should instead provide `django_cotton.apps.SimpleAppConfig` in your INSTALLED_APPS:

INSTALLED_APPS = [
    'django_cotton.apps.SimpleAppConfig',
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        ...
        "OPTIONS": {
            "loaders": [(
                "django.template.loaders.cached.Loader",
                [
                    "django_cotton.cotton_loader.Loader",
                    "django.template.loaders.filesystem.Loader",
                    "django.template.loaders.app_directories.Loader",
                ],
            )],
            "builtins": [
                "django_cotton.templatetags.cotton"
            ],
        }
    }
]

Create a component

Create a new directory in your templates directory called cotton. Inside this directory create a new file called card.html with the following content:

<div class="bg-white shadow rounded border p-4">
    <h2>{{ title }}</h2>
    <p>{{ slot }}</p>
    <button href="{% url url %}">Read more</button>
</div>

Include a component

def dashboard_view(request):
    return render(request, "dashboard.html")

<c-card title="Trees" url="trees">
    We have the best trees
</c-card>

<c-card title="Spades" url="spades">
    The best spades in the land
</c-card>

Usage

Basics

• Cotton components should be placed in the templates/cotton folder (unless you have set COTTON_DIR).

Naming

Cotton uses the following naming conventions:

• Component file names are in snake_case: my_component.html
• but are called using kebab-case: <c-my-component />

Subfolders

• Components in subfolders can be defined using dot notation
• A component in sidebar/menu/link.html would be included as <c-sidebar.menu.link />

Tag Style

• Components can either be self-closing <c-my-component /> or have a closing tag <c-my-component></c-my-component>