Fundamentals

Location

• 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:

• By default, component file names are in snake_case (my_component.html).
• kebab-case filenames (my-component.html) can be enabled with COTTON_SNAKE_CASED_NAMES = False see configuration.
• Components are included in templates using kebab-case name of the component: <c-my-component />

Subfolders

• Components in subfolders can be called using dot notation to represent folder levels.
• A component in sidebar/menu/link.html would be included with <c-sidebar.menu.link />

Tag Syntax

Cotton components can be used with HTML-like syntax or native Django template tags.

HTML-like Syntax

Cotton enables you to use html-like syntax to include your components. This tends to enhance productivity as editors and IDEs often provide autocompletion, auto closing and syntax highlighting of xml-like tags out of the box.

<c-button>
    Click me
</c-button>

{% cotton button %}
    Click me
{% endcotton %}

Native Template Tags

If you prefer using native template tags you can use Cotton's template tags.

HTML Syntax

<c-button title="Click me">
    Click here
</c-button>

Native Syntax

{% cotton button title="Click me" %}
    Click here
{% endcotton %}

Syntax Comparison