django-justmyresource 0.1.0
Use justmyresource resource packs in your Django and Jinja templates
License: MIT
Requires Python: >=3.10
Keywords: Django, Jinja, icons, justmyresource, resources

# django-justmyresource

Use [JustMyResource](https://github.com/kws/justmyresource) resource packs in your Django and Jinja templates.

## Requirements

Python 3.10+ supported.

Django 4.2+ supported (for Django integration).

Jinja2 3.0+ supported (for Jinja integration).

## Installation

Install with the appropriate extras:

```bash
# For Django templates
pip install django-justmyresource[django]

# For Jinja templates
pip install django-justmyresource[jinja]

# For both
pip install django-justmyresource[django,jinja]
```

You'll also need to install resource packs. For example, to use Lucide icons:

```bash
pip install justmyresource-lucide
```

## Usage

### Django Templates

1. Add to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...,
    "django_justmyresource",
    ...,
]
```

2. Load the template library in your templates:

```django
{% load justmyresource %}
```

Alternatively, make the library available in all templates by adding it to [the builtins option](https://docs.djangoproject.com/en/stable/topics/templates/#django.template.backends.django.DjangoTemplates):

```python
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        # ...
        "OPTIONS": {
            # ...
            "builtins": [
                ...,
                "django_justmyresource.templatetags.justmyresource",
                ...,
            ],
        },
    }
]
```

3. Use the `icon` tag to render SVG icons:

```django
{% icon "lucide:a-arrow-down" %}
```

The `icon` tag accepts these arguments:

- `name`, positional: The resource name with optional prefix (e.g., `"lucide:home"` or `"justmyresource-lucide/lucide:home"`).
- `size`, keyword: An integer for width and height attributes. Defaults to `24`. Can be `None` to preserve original size.
- Any number of keyword arguments: These are added as HTML attributes. Underscores are replaced with dashes (e.g., `data_test` becomes `data-test`).

Most attributes are added to the `<svg>` tag, but these are applied to `<path>` elements:

- `stroke-linecap`
- `stroke-linejoin`
- `vector-effect`

#### Examples

Basic icon:

```django
{% icon "lucide:a-arrow-down" %}
```

Custom size and CSS class:

```django
{% icon "lucide:a-arrow-down" size=40 class="mr-4" %}
```

With data attributes and path-level attributes:

```django
{% icon "lucide:a-arrow-down" stroke_width=1 data_controller="language" %}
```

### Jinja Templates

1. Add the `icon` function to your Jinja environment:

```python
from django_justmyresource.jinja import icon
from jinja2 import Environment

env = Environment()
env.globals.update({
    "icon": icon,
})
```

2. Use the `icon` function in your templates:

```jinja
{{ icon("lucide:a-arrow-down") }}
```

The function accepts the same arguments as the Django template tag:

- `name`, positional: The resource name with optional prefix.
- `size`, keyword: Size for width and height. Defaults to `24`. Can be `None`.
- Any number of keyword arguments: HTML attributes (underscores become dashes).

#### Examples

Basic icon:

```jinja
{{ icon("lucide:a-arrow-down") }}
```

Custom size and CSS class:

```jinja
{{ icon("lucide:a-arrow-down", size=40, class="mr-4") }}
```

With data attributes:

```jinja
{{ icon("lucide:a-arrow-down", stroke_width=1, data_controller="language") }}
```

## Configuration

You can configure the JustMyResource registry via Django settings:

### `JUSTMYRESOURCE_DEFAULT_PREFIX`

Set a default prefix for bare resource names (without a colon):

```python
JUSTMYRESOURCE_DEFAULT_PREFIX = "lucide"
```

Then you can use bare names in templates:

```django
{% icon "home" %}  # Resolves to "lucide:home"
```

### `JUSTMYRESOURCE_BLOCKLIST`

Exclude specific resource packs from discovery:

```python
# As a list
JUSTMYRESOURCE_BLOCKLIST = ["pack1", "pack2"]

# Or as a comma-separated string
JUSTMYRESOURCE_BLOCKLIST = "pack1,pack2"
```

### `JUSTMYRESOURCE_PREFIX_MAP`

Map custom aliases to qualified pack names:

```python
# As a dict
JUSTMYRESOURCE_PREFIX_MAP = {
    "icons": "justmyresource-lucide/lucide",
    "fa": "justmyresource-font-awesome/font-awesome",
}

# Or as a comma-separated string
JUSTMYRESOURCE_PREFIX_MAP = "icons=justmyresource-lucide/lucide,fa=justmyresource-font-awesome/font-awesome"
```

## Resource Name Resolution

Resource names can be specified in multiple formats:

- **Qualified name**: `"justmyresource-lucide/lucide:home"` - Always unique, no ambiguity
- **Short pack name**: `"lucide:home"` - Works if the pack name is unique
- **Alias**: `"luc:home"` - If the pack defines aliases via `get_prefixes()`
- **Bare name**: `"home"` - Requires `JUSTMYRESOURCE_DEFAULT_PREFIX` to be set

See the [JustMyResource documentation](https://github.com/kws/justmyresource) for more details on resource resolution.

## Available Resource Packs

Check the [JustMyResource Icons](https://github.com/kws/justmyresource-icons) repository for available icon packs:

- `justmyresource-lucide` - Lucide icons
- `justmyresource-heroicons` - Heroicons
- `justmyresource-phosphor` - Phosphor icons
- `justmyresource-font-awesome` - Font Awesome
- `justmyresource-material-icons` - Material Icons
- `justmyresource-mdi` - Material Design Icons

## Acknowledgements

This project was initially inspired by [lucide](https://github.com/franciscobmacedo/lucide), a Django/Jinja integration for Lucide icons. The lucide project itself is heavily inspired by [Adam Johnson's heroicons](https://github.com/adamchainz/heroicons), and much of the template tag implementation and SVG rendering logic follows similar patterns.

Special thanks to:
- [Francisco Macedo](https://github.com/franciscobmacedo) for the lucide project, which served as the initial reference
- [Adam Johnson](https://github.com/adamchainz) for the heroicons project, which established the pattern for Django icon template tags

## License

MIT