django-colors 1.0.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.

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
• 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.colors.MyCustomColorChoices',
        'color_type': 'TEXT',
    },
    'my_app.MyModel.color_field': {
        'only_use_custom_colors': True,
    },
}

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)
• Success (green)
• Warning (yellow)
• Danger (red)
• 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

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.

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

Development Setup

1. Clone the repository
2. Create a virtual environment
3. Install development dependencies: pip install -e ".[dev]"
4. Run tests: pytest

License

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