Quickstart

Install cotton

Run the following command:

pip install django-cotton

Then update your settings.py:

For automatic configuration:

INSTALLED_APPS = [
    'django_cotton',
]

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

For custom 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>

Templates location

Cotton supports 2 common approaches regarding the location of the templates directory:

• App level - You can place your cotton folder in any of your installed app folders, like:
  [project]/[app]/templates/cotton/row.html
• Project root - You can place your cotton folder in a project level templates directory, like:
  [project]/templates/cotton/row.html
  ([project] location is provided by `BASE_DIR` if present or you may set it with `COTTON_BASE_DIR`)

Any style will allow you to include your component the same way: <c-row />

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 ('cotton' path is configurable using COTTON_DIR).
• The templates folder can be located in either an app-level or top-level project root folder.

Naming

Cotton uses the following naming conventions:

• Component file names by default are in snake_case: my_component.html (kebab-case filenames can be enabled, see configuration)
• and are included 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>