Django Cotton

Warnings

• breaking Internal template tag names changed in version 2.4.0. While these were not officially documented for external use, direct reliance on previous internal tag names would break upon upgrade.
  Fix: Review any custom code that might have directly referenced internal Django Cotton template tags. Migrate to documented public APIs or the HTML-like component syntax.
• gotcha If your project uses a custom `TEMPLATES` loader configuration, automatic setup by adding 'django_cotton' to `INSTALLED_APPS` might be insufficient. You may need to manually configure the `CottonLoader`.
  Fix: Explicitly add `django_cotton.template.loaders.CottonLoader` to your `TEMPLATES` `OPTIONS.loaders` list, ideally wrapped by `django.template.loaders.cached.Loader` for optimal performance.
• gotcha Components are referenced in templates using kebab-case (e.g., `<c-my-component />`), but component filenames typically use snake_case by default (e.g., `my_component.html`). This naming convention difference can sometimes be a source of confusion.
  Fix: Be mindful of the casing convention. You can configure `COTTON_SNAKE_CASED_NAMES = False` in `settings.py` to allow kebab-case filenames for components if preferred.
• gotcha In some setups, particularly older ones or with specific environment configurations, the HTML-like component syntax (`<c-component />`) might render as raw HTML in the browser rather than being processed by Django Cotton. The native `{% cotton %}` tag typically still works in such cases.
  Fix: Ensure `django_cotton` is correctly listed in `INSTALLED_APPS` and that the template loader configuration is valid. If using manual loader setup, double-check its correctness. If issues persist, consider using the native `{% cotton %}` tag as an alternative.

Install

• pip install django-cotton Install latest version

Imports

• django_cotton

  INSTALLED_APPS = ['django_cotton', ...]

  Add 'django_cotton' to your Django project's INSTALLED_APPS in settings.py. This usually handles automatic loader and templatetag configuration.

Quickstart

1. Add `django_cotton` to your `INSTALLED_APPS` in `settings.py`. This typically configures the necessary template loaders automatically. 2. Create a `cotton` directory within your Django app's `templates` folder or a project-level `templates` folder. 3. Define a component, for example, `button.html`, inside the `cotton` directory. The `{{ slot }}` variable renders any content passed between the component's opening and closing tags. 4. Use the component in your main Django templates using the HTML-like `c-` prefixed tag and kebab-case naming.

<!-- settings.py -->
INSTALLED_APPS = [
    # ... other apps
    'django_cotton',
]

# Optional: Manual TEMPLATES configuration if you have custom loaders
# TEMPLATES = [
#     {
#         'BACKEND': 'django.template.backends.django.DjangoTemplates',
#         'DIRS': [],
#         'APP_DIRS': False, # Set to False if DIRS is used for project-level templates
#         'OPTIONS': {
#             'loaders': [
#                 ('django.template.loaders.cached.Loader', [
#                     'django_cotton.template.loaders.CottonLoader',
#                     'django.template.loaders.filesystem.Loader',
#                     'django.template.loaders.app_directories.Loader',
#                 ]),
#             ],
#             'builtins': [
#                 'django_cotton.templatetags.cotton',
#             ],
#         },
#     },
# ]

# --- In your templates directory (e.g., myproject/templates/cotton/button.html) ---
<button class="p-2 rounded-md bg-blue-500 text-white hover:bg-blue-600">
    {{ slot }}
</button>

# --- In a main Django template (e.g., myproject/templates/index.html) ---
<h1 class="text-2xl font-bold">Welcome!</h1>
<c-button>Click Me</c-button>
<c-button class="bg-green-500 hover:bg-green-600">Submit</c-button>