Metadata-Version: 2.4
Name: wagtail-icon-chooser
Version: 0.3.3
Summary: Wagtail Icon Chooser
Home-page: https://github.com/erick-otenyo/wagtail-icon-chooser
Author: Erick Otenyo
Author-email: otenyo.erick@gmail.com
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: wagtail>=5.0

# Wagtail Icon Chooser

Icon chooser widget for Page/Model fields and Stream Field

# Installation

```
pip install wagtail-icon-chooser
```

Add `wagtailiconchooser` to your installed apps

```
 INSTALLED_APPS = [
        ...
        "wagtailiconchooser",
        ...
        ]
```

# Usage

- Use `wagtailiconchooser.widgets.IconChooserWidget` in FieldPanels
- Use `wagtailiconchooser.blocks.IconChooserBlock` in StreamField blocks

```python
from django.db import models
from wagtail.admin.panels import FieldPanel
from wagtail.fields import StreamField
from wagtail.models import Page

from wagtailiconchooser.blocks import IconChooserBlock
from wagtailiconchooser.widgets import IconChooserWidget


class MyPage(Page):
    icon = models.CharField(max_length=100, null=True, blank=True)
    stream_field_with_icon = StreamField([
        ('icon', IconChooserBlock()),
    ], use_json_field=True, blank=True, null=True)

    content_panels = Page.content_panels + [
        FieldPanel("icon", widget=IconChooserWidget),
        FieldPanel("stream_field_with_icon"),
    ]
```

# Limiting available icons

You can restrict which icons are shown in the chooser modal by passing an `icons` allowlist.

**In a FieldPanel:**

```python
FieldPanel("icon", widget=IconChooserWidget(icons=["cross", "tick", "home"]))
```

**In a StreamField block:**

```python
stream_field_with_icon = StreamField([
    ('icon', IconChooserBlock(icons=["cross", "tick", "home"])),
], use_json_field=True, blank=True, null=True)
```

Only the icons named in the list will appear in the modal. Omitting `icons` (or passing `None`) shows all available icons.

# Screenshots

- Icon Chooser Widgets for Page field and Stream field

![Sample Panels](screenshots/img-in-admin.png)

- Icon List Modal

![Icon Modal](screenshots/icon-list-modal.png)

# Showing icons on your frontend templates

The Icons can be used out of the box in templates rendered on the Wagtail admin, without any custom configuration.

Below are two possible ways of getting your svg icon to show on your custom frontend template:

### 1. Including individual SVG markup

You can use the `svg_icon` template tag as below:

```html
{% load wagtailiconchooser_tags %}

....

{% block content %}

<div>
    {% svg_icon name=page.icon classname="your-custom-class" %}
</div>

{% endblock content %}

.....
```

### 2. Using SVG Sprites

- Add all icons to your template's context, and have them as a svg sprite. Wagtail provides a way to get all the admin
  icons as a svg sprite, using a view found at `wagtail.admin.views.home.icons`
- Add the svg sprite to your template
- use the `icon` template tag from `wagtailadmin_tags` to render your svg, which will the link with the icon from the
  svg sprite
- or directly render the svg to the template

We provide custom abstract page `CustomIconPage`, that helps you to achieve the above.

This just overrides the `get_context` method of the Wagtail Page class, to add the svg sprite string.

```python
from django.db import models
from wagtail.admin.panels import FieldPanel
from wagtail.models import Page

from wagtailiconchooser.models import CustomIconPage
from wagtailiconchooser.widgets import IconChooserWidget


class MyPage(CustomIconPage, Page):
    icon = models.CharField(max_length=100, null=True, blank=True)

    content_panels = Page.content_panels + [
        FieldPanel("icon", widget=IconChooserWidget)
    ]
```

Your template will now have a svg sprite `context` object, with the key `icons_svg_sprite`

You can add the svg sprite anywhere in the template, and use the `icon` tag

```html
{% load wagtailadmin_tags %}

....

{% block content %}

{% if icons_svg_sprite %}
{{ icons_svg_sprite|safe }}
{% endif %}

<div>
    {% icon name=page.icon %}
</div>

{% endblock content %}


.....
```

You can also directly render your icon without using the `icon` from `wagtailadmin_tags` template tag,
since`wagtailadmin_tags` is clearly meant to be used on the admin side of things.

Just replace `{% icon name=page.icon %}` with

```html

{{ icons_svg_sprite|safe }}

<svg class="icon">
    <use href="#icon-{{ page.icon }}"></use>
</svg>
```

`NOTE` This approach will load all the icons added to Wagtail (using the `register_icons` hook) to your template. If you
have registered many SVG icons, this might increase your page's loading bandwidth and might not be efficient since you
might not use all the icons.

If you have a list of icons that are known, you can create a svg sprite containing only those icons, by using the
function `get_svg_sprite_for_icons`. This can be used in a view. For example:

```python
from django.shortcuts import render
from wagtailiconchooser.utils import get_svg_sprite_for_icons


def my_view(request):
    icons = ["some-icon", "some-other-icon", ...]
    svg_sprite = get_svg_sprite_for_icons(icons)

    context = {
        "svg_sprite": svg_sprite
    }

    return render(request, "template.html", context=context)
```

In your `template.html` you will have access to the `svg_sprite` context, and you can render and use as below:

```html

<div>
    {{ svg_sprite|safe }}
</div>

<svg class="icon">
    <use href="#icon-some-icon"></use>
</svg>

<svg class="icon">
    <use href="#icon-some-other-icon"></use>
</svg>

```
