# django-colors

[![PyPI version](https://badge.fury.io/py/django-colors.svg)](https://badge.fury.io/py/django-colors)
[![Build Status](https://travis-ci.org/username/django-colors.svg?branch=master)](https://travis-ci.org/username/django-colors)
[![Coverage Status](https://coveralls.io/repos/github/username/django-colors/badge.svg?branch=master)](https://coveralls.io/github/username/django-colors?branch=master)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

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

```bash
pip install django-colors
```

Add 'django_colors' to your `INSTALLED_APPS` setting:

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

## Usage

### Basic Usage

Add a color field to your model:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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.
