cotton
for

Quickstart

Install cotton

Run the following command:

pip install django-cotton

Then update your settings.py:

settings.py
INSTALLED_APPS = [
    ...
    'django_cotton',
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['your_project/templates'], # Add your template directories here
        'APP_DIRS': False,
        'OPTIONS': {
            'loaders': [
                'django_cotton.cotton_loader.Loader', # First position
                # continue with default loaders, typically:
                # "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:

templates/cotton/card.html
<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

views.py
def dashboard_view(request):
    return render(request, "dashboard.html")
templates/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>
preview

Trees

We have the best trees

Spades

The best spades in the land

Usage

Basics

  • Cotton components should be placed in the templates/cotton folder

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>
back Home
next Components