Metadata-Version: 2.4
Name: wagtail-external-links-report
Version: 0.1.0
Summary: This package adds a report to your wagtail app that lists all external urls you have used on your pages.
Project-URL: Repository, https://github.com/PBahner/wagtail-external-links-report
Author-email: Timo Klinge <kl.timo@outlook.de>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4~=4.12.3
Requires-Dist: wagtail~=7.1
Description-Content-Type: text/markdown

# Wagtail external links report

This package adds a report to your wagtail app that lists all external urls you have used on your page.
This is useful for moderators to keep track of other websites you are referring to.

![img.png](img.png)

## Features

- **Report View**: Adds a report in your wagtail admin that lists all external urls you have used on your page.
- **Customizable**: You can include or exclude specific page fields and block values with custom handlers.


## Installation

You can install the library with the following command:

```bash
pip install wagtail-external-links-report
```

Add the app in your settings/base.py. Optionally define your custom report-view class:

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

...

EXTERNAL_LINKS_REPORT_CLASS = "home.views.CustomExternalLinksReportView"

```

By default, this app extracts all external urls (by a-tag) that are used in the `body` field of a page.
It doesn't matter which type the `body` field is of (can be plain-text, RichText or a StreamField).
When your field is a StreamField, the app will automatically look up all subblocks and subfields for a-tags with external urls.

You can add additional fields for look up. Moreover, you can add your own handlers for extracting urls from custom blocks.

To do this, you need to create a custom class that extends `ExternalLinksReportView`
and refer to this class in your settings/base.py with `EXTERNAL_LINKS_REPORT_CLASS`.

```python
# home/views.py
from wagtail_external_links_report.utils import LinkExtractor
from wagtail_external_links_report.views import ExternalLinksReportView
from home.blocks import Button

class CustomExternalLinksReportView(ExternalLinksReportView):
    page_title = "used URLS"  # you can customize the view name in you wagtail admin too

    def get_extractor(self):
        return LinkExtractor(
            allowed_fields=["title", "body", "footer"],  # use your custom fields
            custom_handlers={
                Button: self.extract_from_button
            }
        )

    def extract_from_button(self, value):
        """Example handler for a custom Button block."""
        if value["button_page"] is None and value["button_url"]:
            return [{
                "text": value["button_text"],
                "url": value["button_url"],
            }]
        return []
```

In the above example, a custom handler is registered for a custom Block type `Button`.
This example Button-block can either point to an internal page or to an external page.
With the custom handler you can lookup block-values without searching for a-tags and also exclude specific block-fields.

```python
class Button(blocks.StructBlock):
    """ A simple button which can either be an internal page or an external url """
    button_text = blocks.CharBlock(required=True, default="more", max_length=40, label="Text")
    button_page = blocks.PageChooserBlock(required=False, label="internal page")
    button_url = blocks.URLBlock(required=False, label="external URL")

    class Meta:
        template = "layouts/button.html"
        icon = "link"
        label = "Button"
```
