Skip to main content

Bringing component based design to Django templates.

Project description

Django Cotton

Build Status License

Bringing component-based design to Django templates.

Contents

Why?
Your First component
Attributes
Names Slots
Pass Template Variables
Template expressions in attributes
Boolean attributes
Passing Python data types
Default attributes
Increase Re-usability with {{ attrs }}
HTMLX Example
Usage Basics
Changelog

Why Cotton?

Cotton aims to overcome certain limitations that exist in the django template system that hold us back when we want to apply modern practises to compose UIs in a modular and reusable way.

Key Features

  • Modern UI Composition: Efficiently compose and reuse UI components.
  • Interoperable with Django: Cotton enhances django's existing template system.
  • HTML-like Syntax: Better code editor support and productivity as component tags are similar to html tags.
  • Minimal Overhead: Compiles to native Django components with dynamic caching.
  • Ideal for Tailwind usage: Helps encapsulate content and style in one file.
  • Compliments HTMX: Create smart components, reducing repetition and enhancing maintainability.

Walkthrough

Your first component

<!-- cotton/button.html -->
<a href="/" class="...">{{ slot }}</a>
<!-- template -->
<c-button>Contact</c-button>
<!-- output -->
<a href="/" class="...">Contact</a>

Everything provided between the opening and closing tag is provided to the component as {{ slot }}. It can contain HTML and any Django template expression.

Add attributes

<!-- cotton/button.html -->
<a href="{{ url }}" class="...">
    {{ slot }}
</a>
<!-- template -->
<c-button url="/contact">Contact</c-button>
<!-- output -->
<a href="/contact" class="...">
    Contact
</a>

Named slots

Named slots are a powerful concept. It allows us to provide HTML to appear in one or more areas in the component. Here we allow the button to optionally display an icon:

<!-- cotton/button.html -->
<a href="{{ url }}" class="...">
    {{ slot }}
  
    {% if icon %} 
        {{ icon }} 
    {% endif %}
</a>
<!-- template -->
<c-button url="/contact">
    Contact
    <c-slot name="icon">
        <svg>...</svg>
    </c-slot>
</c-button>

Named slots can also contain any django native template logic:

<!-- template -->
<c-button url="/contact">
    <c-slot name="icon">
      {% if mode == 'edit' %}
          <svg id="pencil">...</svg>
      {% else %}
          <svg id="disk">...</svg>
      {% endif %}
    </c-slot>
</c-button>

Pass template variable as an attribute

To pass a template variable you prepend the attribute name with a colon :. Consider a bio card component:

<!-- template -->
<c-bio-card :user="user" />

That has a component definition like:

<!-- cotton/bio_card.html -->
<div class="...">
  <img src="{{ user.avatar }}" alt="...">
  {{ user.username }} {{ user.country_code }}
</div>

Template expressions inside attributes

You can use template expression statements inside attributes.

<c-weather icon="fa-{{ icon }}"
           unit="{{ unit|default:'c' }}"
           condition="very {% get_intensity %}"
/>

Boolean attributes

Boolean attributes reduce boilerplate when we just want to indicate a certain attribute should be True or not.

<!-- template -->
<c-button url="/contact" external>Contact</c-button>

By passing just the attribute name without a value, it will automatically be provided to the component as True

<!-- cotton/button.html -->
<a href="{{ url }}" {% if external %} target="_blank" {% endif %} class="...">
    {{ slot }}
</a>

Passing Python data types

Using the ':' to prefix an attribute tells Cotton we're passing a dynamic type down. We already know we can use this to send a variable, but you can also send basic python types, namely:

  • Integers and Floats
  • None, True and False
  • Lists
  • Dictionaries

This benefits a number of use-cases, for example if you have a select component that you want to provide the possible options from the parent:

<!-- cotton/select.html -->
<select {{ attrs }}>
    {% for option in options %}
        <option value="{{ option }}">{{ option }}</option>
    {% endfor %}
</select>
<c-select name="q1" :options="['yes', 'no', 'maybe']" />
<!-- cotton/output -->
<select name="q1">
    <option value="yes">yes</option>
    <option value="no">no</option>
    <option value="maybe">maybe</option>
</select>

Default attributes with <c-vars>

Django templates adhere quite strictly to the MVC model and does not permit a lot of data manipulation in the View. Fair enough, but what if we want to handle data for the purpose of UI state only? Having this in the back would surely convolute the backend code. For this, Cotton can set simple attribute values that help allow us to set default values for our component attributes.

<!-- cotton/button.html -->
<c-vars theme="bg-purple-500" />

<a href="..." class="{{ theme }}">
    {{ slot }}
</a>
<!-- template -->
<c-button>I'm a purple button</c-button>
<!-- output -->
<a href="..." class="bg-purple-500">
    I'm a purple button
</a>

Now we have a default theme for our button, but it is overridable:

<!-- template -->
<c-button theme="bg-green-500">But I'm green</c-button>
<!-- output -->
<a href="..." class="bg-green-500">
    But I'm green
</a>

Increase Re-usability with {{ attrs }}

{{ attrs }} is a special variable that contains all the attributes passed to the component in an key="value" format. This is useful when you want to pass all attributes to a child element. For example, you have inputs that can have any number of attributes defined:

<!-- cotton/input.html -->
<input type="text" class="..." {{ attrs }} />
<!-- example usage -->
<c-input placeholder="Enter your name" />
<c-input name="country" id="country" value="Japan" />
<c-input class="highlighted" required />

If you combine this with the c-vars tag, any property defined there will be excluded from {{ attrs }}. For example:

<!-- cotton/input.html -->
<c-vars type="text" />

<input {{ attrs }} class="..." />
<!-- example usage -->
<c-input type="password" placeholder="Password" />
<!-- `type` will not be in {{ attrs }} -->

An example with HTMLX

Cotton helps carve out re-usable components, here we show how to make a re-usable form, reducing code repetition and improving maintainability:

<!-- cotton/form.html -->
<div id="result" class="..."></div>

<form {{ attrs }} hx-target="#result" hx-swap="outerHTML">
    {{ slot }}
    <button type="submit">Submit</button>
</form>
<!-- template -->
<c-form hx-post="/contact">
    <input type="text" name="name" placeholder="Name" />
    <input type="text" name="email" placeholder="Email" />
    <input type="checkbox" name="signup" />
</c-form>

<c-form url="/buy">
    <input type="text" name="type" />
    <input type="text" name="quantity" />
</c-form>

Usage Basics

  • Component Placement: Components should be placed in the templates/cotton folder.
  • Naming Conventions:
    • Component filenames use snake_case: my_component.html
    • Components are called using kebab-case: <c-my-component />

For full docs and demos, checkout django-cotton.com

Changelog

Date Version Title and Description
2024.07-03 v0.9.12 Dropped ".cotton.html" Requirement
Cotton no longer requires the .cotton.html suffix on component or view templates. A simple .html will do.
2024-06-24 v0.9.11 Attribute Ordering Fix
Attribute ordering was not being kept during compilation which was breaking situations when using template expressions inside tags.
2024-06-22 v0.9.10 Template Expression Attributes
Ensures that the new template expression attributes are also provided in {{ attrs }} alongside all normal attributes.
2024-06-22 v0.9.9 Native Tags in Attributes
Cotton now allows you to include template variables inside attributes. Added expression attributes to {{ attrs }}.
2024-06-21 v0.9.7 Dynamic Type Attributes
Using the : to prefix an attribute tells Cotton we're passing a dynamic type down. You can also send basic Python types.
2024-06-17 v0.9.6 Rename c-props to c-vars
Rename c props, all <c-props /> are now <c-vars />.
2024-06-11 v0.9.4 Boolean Attributes
Support for Boolean attributes added with docs update.
2024-06-08 v0.9.1 Open Source Release
Open source release.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_cotton-0.9.13.tar.gz (15.7 kB view hashes)

Uploaded Source

Built Distribution

django_cotton-0.9.13-py3-none-any.whl (15.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page