django-cotton-components 0.1.6

A Django package with pre-built cotton-based UI components for rapid development.

Django Cotton Components

A collection of pre-built, stylish, and functional form components to streamline your Django development process.

Key Features:

• Pre-built Components: Quickly add common form elements like text inputs, textareas, select boxes, and more.
• Alpine.js for Interactivity: Leverage Alpine.js to add dynamic behavior to your components without relying on full-fledged JavaScript frameworks.
• Easy to Use: Simple installation and configuration, allowing you to focus on building your application.

Dependencies:

• Django-Cotton
• AlpineJs
• TailwindCSS (optional)

Installation:

    pip install django-cotton-components

• Follow the Django-Cotton installation steps.
• Add AlpineJs and its plugins(collapse, focus, mask).
• Add TailwindCSS.

Add to installed apps

    INSTALLED_APPS = [
        ...
        "django_cotton",
        "django_cotton_components",
        ...
    ]

DISCLAIMER

The package is under active development. More changes will occur. The package is not yet stable. When using it and run into issues and/or have suggestions please create an ISSUE on GITHUB

Inheritance

In your 'templates' directory, create a cotton directory.

example: create input.html

<c-dcc-input class="styling classes" errorTimer="1000" attrs="{{attrs}}" />

In your project reference your component, <c-input id="thisInput" type="date" />.

Components

By default some components come with TailwindCSS styling.

Headers

<c-dcc-h title="" class="" url="" {{ attrs }}>`extra content`</c-dcc-h>

By default it is a h1, no styling is provided.

• id: Unique identifier for the input.
• class: Customise to your preference add your own.
• url: If provided, the heading becomes a link.

Input

<c-dcc-input
	id=""
	class=""
	type=""
	errorTimer=""
	borderErrorClass=""
	errorDivClass=""
	validationUrl=""
	{{attrs}}
/>

By default it is a text input if no type is provided..

• id: Unique identifier for the input.
• class: Customise to your preference add your own.
• type: By default this is text. Define your type (date, email, number, etc.).
• errorTimer: If variable is not passed the form errors will show indefinitely. Pass milliseconds to prop to display how long the error will be displayed for.
• validationUrl: Requires HTMX. This will validate your input such as username, checkout example.
• attrs: Do not reference attrs. Add extra attributes such as 'name', 'value', 'placeholder', 'required' etc.

Textarea

<c-dcc-textarea
	id=""
	class=""
	errorTimer=""
	errorDivClass=""
	validationUrl=""
	{{attrs}}
/>

• id: Unique identifier for the input.
• errorTimer: If variable is not passed the form errors will show indefinitely. Pass milliseconds to prop to display how long the error will be displayed for.
• validationUrl: Requires HTMX. This will validate your input such as username, checkout example.
• attrs: Do not reference attrs. Add extra attributes such as 'name', 'value', 'placeholder', 'rows' etc.

Password Input

<c-dcc-password-input id="" name="" show {{ attrs }} />

• id: Unique identifier for the password input.
• show: Enables password visibility toggle.
• attrs: Do not reference attrs. Add extra attributes such as 'name', 'value', 'placeholder', 'required' etc.

Button

<c-dcc-button id="" class="" title="" icon="" svg="" url="" />

• id: Unique identifier for the button.
• class: Add styling to your button.
• title: Button text.
• type: Button type(submit, reset etc.).
• url: If provided, the button renders as <a href="..."> otherwise, it renders as <button>.

Icon or SVG not both

• icon: Icon name to be displayed on the button.
• svg: Path to an SVG icon.

Extra

You can add extra attributes on the button, example, <c-button id="" title="Testing" hx-get="some_url" hx-trigger="click" hx-target="#some_id" />

Select options

Single Select

<c-dcc-select
	id=""
	name=""
	:list="['Option1','Option2']"
	:options=""
	:model="cars"
	search
	value=""
/>

• id: Unique identifier for the select.
• list: Array of list to be displayed in the select.
• model: Data passed from your view ( cars = Car.objects.all() ).
• search: Enables search functionality.
• value: When provided, the component checks each item in the values array against the model (e.g, an array of objects) and marks the matching list as selected.

Note: If you use ':model' and no model is provided an 'IndexError' will be produced.

MultiSelect

<c-dcc-select-multiple id="" label="" name="" :list="[]" :model="" :values="" />

• id: Unique identifier for the select.
• label: Label displayed above the select.
• list: Array of list to be displayed in the select.
• model: Data passed from your view ( cars = Car.objects.all() ).
• values: When provided, the component checks each item in the values array against the model (e.g, an array of objects) and marks the matching options as selected.

Note: Being worked on, display of selected options when using ':model' not on par with ':options'

Checkbox

<c-dcc-checkbox id="" label="" description="" value="" />

• id: Unique identifier for the checkbox.
• label: Label displayed above the checkbox.
• description: displayed below the checkbox.
• value: Value to be passed when clicked.

Toggle

<c-dcc-toggle id="" label="" value="" />

• id: Unique identifier for the toggle.
• label: Label displayed above the toggle.
• value: Value to be passed when toggled.

Radio

<c-dcc-radio id="" label="" description="" value="" />

• id: Unique identifier for the radio.
• label: Label displayed above the radio.
• description: displayed below the radio.
• value: Value to be passed when clicked.

Modal

<c-dcc-modal
	id=""
	buttonClass=""
	modalClass=""
	headerClass=""
	headerLabelClass=""
	bodyClass=""
	header=""
	label=""
>
	<!-- Your content -->
</c-dcc-modal>

• header: Header text for the modal.
• label: Label for the modal toggle.

Table

<c-dcc-table
	id=""
	:th="[]"
	thClass=""
	:tr=""
	trClass=""
	paginate_by=""
	search
/>

• id: Unique identifier for the table.
• th: Array of column names that specify which data fields will display.
• thClass: Custom class for <thead> styling.
• tr: Data from the view (must be a list of dictionaries). Example:
  cars = Car.objects.all()
context={"table_cars":list(cars.values())}
• trClass: Custom class for row styling.
• paginate_by: Number of rows displayed per page.
• search: Enables search functionality across the specified columns in :th.

Attributes

• You can add other attributes to the components such as aria-label etc.
• You can also add custom attributes to the components to suit your needs such as HTMX.
• Read more about {{ attrs }}

Mentions

• Penguin components.
• BugBytes educational content.