django-colors 1.1.0

An application to assist with css framework color selections.

django-colors

A Django app providing customizable color selection fields for your models with Bootstrap color integration. Can be used with or without Bootstrap and can be easily extended to support any CSS framework or custom color palette.

Overview

Django Colors offers a simple yet powerful way to add color selection capabilities to your Django models. It provides:

• Custom model fields for color selection
• Pre-defined Bootstrap color choices
• Support for both background and text color CSS classes
• Ability to define your own color palettes
• Ability to define color palettes from any CSS framework
• Custom widget for color selection in forms

The app is designed to be flexible, allowing you to use either the built-in Bootstrap color options or define your own custom colors through Django models.

Installation

pip install django-colors

Add 'django_colors' to your INSTALLED_APPS setting:

INSTALLED_APPS = [
    ...
    'django_colors',
    ...
]

Usage

Basic Usage

Add a color field to your model:

from django.db import models
from django_colors.fields import ColorModelField

class MyModel(models.Model):
    name = models.CharField(max_length=100)
    color = ColorModelField()

By default, this will use Bootstrap color choices for background colors.

Using Text Colors

To use text colors instead of background colors:

from django_colors.field_type import FieldType

class MyModel(models.Model):
    name = models.CharField(max_length=100)
    color = ColorModelField(color_type=FieldType.TEXT)

Custom Color Models

Create a model for custom colors:

from django_colors.models import ColorModel

class MyCustomColor(ColorModel):
    """Custom color definitions for my app."""
    class Meta:
        verbose_name = "Custom Color"
        verbose_name_plural = "Custom Colors"

Use your custom colors in a field:

class MyModel(models.Model):
    name = models.CharField(max_length=100)
    color = ColorModelField(model=MyCustomColor)

Global Configuration

You can configure the app globally in your settings.py:

COLORS_APP_CONFIG = {
    'default': {
        'default_color_choices': 'django_colors.color_definitions.BootstrapColorChoices',
        'color_type': 'BACKGROUND',
    },
    'my_app': {
        'default_color_choices': 'myapp.MyCustomColorChoices',
        'color_type': 'TEXT',
    },
    'my_app.MyModel.color_field': {
        'model': 'my_app.MyCustomColor',
        'only_use_custom_colors': True,
    },
}
# You can also import your custom color choices directly

from django_colors.color_definitions import BootstrapColorChoices
COLORS_APP_CONFIG = {
    'default': {
        'default_color_choices': BootstrapColorChoices,
        'color_type': 'BACKGROUND',
    },
    'my_app': {
        'default_color_choices': 'myapp.MyCustomColorChoices',
        'color_type': 'TEXT',
    },
    'my_app.MyModel.color_field': {
        'model': 'my_app.MyCustomColor',
        'only_use_custom_colors': True,
    },
}

• note: When using only_use_custom_colors, you must set a model, as it will not use the default color choices.

Templates

The app includes templates for rendering color selections:

• color_select.html - Main template for the color selection widget
• color_select_option.html - Template for individual color options

You can override these templates in your project by creating your own versions in your templates directory.

API Reference

ColorOption

A dataclass representing a single color option with the following attributes:

• value: Unique identifier for the color
• label: Human-readable label
• background_css: CSS class for background color
• text_css: CSS class for text color

ColorChoices

Base class for defining a collection of color options with methods to:

• Get choices as a list of tuples for Django choice fields
• Look up color options by value
• Iterate over available color options

BootstrapColorChoices

Pre-defined color choices based on Bootstrap's color system, including:

• Primary colors (blue: bg-primary, text-primary)
• Success (green: bg-success, text-success)
• Warning (yellow: bg-warning, text-warning)
• Danger (red: bg-danger, text-danger)
• Various other colors (purple, indigo, pink, etc.)

FieldType

Enum defining the type of color field:

• BACKGROUND: For background color CSS classes
• TEXT: For text color CSS classes

ColorModelField

A custom Django field for selecting colors, with options for:

• Using predefined or custom colors
• Specifying field type (background or text)
• Using a custom model or queryset for color options
• get_choices() can pass additional_filters to make the field do additional filtering on the model (and any existing filters applied to it)
• get_choices(): can pass model_priority to make the field return all model objects instead of any queryset filtered objects.

ColorModel

Abstract base model for custom color definitions with fields for:

• name: Color name
• background_css: CSS class for background color
• text_css: CSS class for text color

ColorChoiceWidget

Custom form widget for color selection.

Forms

The ColorModelField class will render as a Select field in forms.

Model form example

# models.py
class TestAppColor(ColorModel):
    active = models.BooleanField(default=True)

    def __str__(self) -> str:
        return f"{self.name}"


class TestThing(models.Model):
    identity = models.CharField(max_length=100)
    background_color = ColorModelField(
        model=TestAppColor,
        # Show only active colors along with default colors
        model_filters={"active": True},
        only_use_custom_colors=False,
        null=True,
        blank=True,
    )
    # show only default colors
    text_color = ColorModelField()

# forms.py
class TestThingForm(forms.ModelForm):
    class Meta:
        model = TestThing
        fields = ["background_color"]

Standard form example

# models.py
class TestAppColor(ColorModel):
    active = models.BooleanField(default=True)

    def __str__(self) -> str:
        return f"{self.name}"


class TestThing(models.Model):
    identity = models.CharField(max_length=100)
    background_color = ColorModelField(
        model=TestAppColor,
        # Show only active colors along with default colors
        model_filters={"active": True},
        only_use_custom_colors=False,
        null=True,
        blank=True,
    )
    # show only default colors
    text_color = ColorModelField()

# forms.py
class StandardForm(forms.Form):
    color = forms.ChoiceField(
        required=False,
        choices=TestThing._meta.get_field("background_color").get_choices,
        widget=ColorChoiceWidget(
            attrs={"class": "form-control", "hx-target": "#something"}
        ),
    )

Advanced form example

• This showcases how to use the get_choices method to override the presets in the form.

# models.py
class TestAppColor(ColorModel):
    active = models.BooleanField(default=True)

    def __str__(self) -> str:
        return f"{self.name}"


class TestThing(models.Model):
    identity = models.CharField(max_length=100)
    background_color = ColorModelField(
        model=TestAppColor,
        # Show only active colors along with default colors
        model_filters={"active": True},
        only_use_custom_colors=False,
        null=True,
        blank=True,
    )
    # show only default colors
    text_color = ColorModelField()

# forms.py
class AdvancedForm(forms.Form):
    # Need to see ALL options including inactive colors
    color = forms.ChoiceField(
        required=False,
        choices=partial(
            TestThing._meta.get_field("background_color").get_choices,
            model_priority=True,
        ),
        widget=ColorChoiceWidget(
            attrs={"class": "form-control", "hx-target": "#something"}
        ),
    )

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

1. Code should be properly linted and formatted according to the ruff settings in pyproject.toml
2. All tests must pass, and new code must have tests
3. Add documentation for new features
4. Follow type hinting conventions
5. Include docstrings with argument and return type information
6. All contributions must pass pre-commit checks
7. All new contributions should include relevant tests
8. Run ruff linting and formatting checks before submitting your PR

Development Setup

1. Clone the repository
2. Create a virtual environment
3. Install development dependencies: pip install -e ".[dev]"
4. Install pre-commit hooks: pre-commit install
5. Run tests: pytest
6. Run linting: ruff check .
7. Run formatting: ruff format .

When submitting a PR, ensure all pre-commit hooks pass successfully. The CI pipeline will automatically check these for you, but it's best to verify locally first.

License

This project is licensed under the MIT License - see the LICENSE file for details.