Metadata-Version: 2.4
Name: wagtail-extended-blocks
Version: 0.2.0
Summary: A collection of reusable custom StreamField blocks for Wagtail.
Project-URL: Homepage, https://git.jfctr.com/jeffcouturier/wagtail-extended-blocks
Project-URL: Documentation, https://git.jfctr.com/jeffcouturier/wagtail-extended-blocks#readme
Project-URL: Repository, https://git.jfctr.com/jeffcouturier/wagtail-extended-blocks
Project-URL: Tracker, https://git.jfctr.com/jeffcouturier/wagtail-extended-blocks/issues
Author: Jeff Couturier
License: BSD-3-Clause
License-File: LICENSE
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 5
Classifier: Framework :: Wagtail :: 6
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: django>=4.2
Requires-Dist: wagtail>=5.2
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Description-Content-Type: text/markdown

# Wagtail Extended Blocks

A collection of reusable custom StreamField blocks that extend Wagtail's default block types to provide greater layout flexibility and versatility.

## Compatibility

| Wagtail Version | Django Version | Python Version |
| --------------- | -------------- | -------------- |
| 5.2 (LTS)       | 4.2, 5.0       | 3.8 - 3.12     |
| 6.0+            | 4.2 - 5.1      | 3.10 - 3.12    |

## Resources

* **Repository**: [GitHub](https://github.com/jeffcouturier/wagtail-extended-blocks)
* **Bug Tracker**: [Issues](https://github.com/jeffcouturier/wagtail-extended-blocks/issues)
* **License**: [3-Clause BSD License](LICENSE)

## Installation

Install the package via pip (for local development):

```bash
pip install -e .
```

Add `wagtail_extended_blocks` to your Django settings `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "wagtail_extended_blocks",
    # ...
]
```

## Usage

Import and use the blocks in your StreamFields:

```python
from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail_extended_blocks.blocks import (
    QuoteBlock,
    AccordionBlock,
    ButtonChooserBlock,
)

class MyPage(Page):
    body = StreamField([
        ('quote', QuoteBlock()),
        ('accordion', AccordionBlock()),
        ('button', ButtonChooserBlock()),
    ], use_json_field=True)
```

## Default Templates

This package includes basic default frontend HTML templates for rendering blocks. You can override any of these by placing templates inside your project's directory structure:
`templates/wagtail_extended_blocks/blocks/` (e.g., `templates/wagtail_extended_blocks/blocks/quote_block.html`).

## Provided Blocks

The package organizes blocks into three categories:

### Base/Utility Blocks
* **`RelativeOrAbsoluteURLBlock`**: A text field validating external URLs, relative links (`/about`), anchors (`#contact`), or mailto links.
* **`ButtonBlock`**: A custom link button.
* **`ButtonChooserBlock`**: A link button allowing selection of EITHER an internal page OR a custom URL.
* **`InternalButtonBlock`**: A button linking only to internal pages.
* **`SectionBreakBlock`**: Inserts adjustable vertical spacing.
* **`ClearfixBlock`**: Clear floated layouts.
* **`CustomCodeBlock`**: Inserts custom styles or scripts.
* **`CustomHtmlBlock`**: Paste raw HTML safely.

### Content Blocks
* **`QuoteBlock`**: Standard blockquote text with author attribution.
* **`QuoteImageBlock`**: A layout combining an image and rich text quote.
* **`FootnoteBlock`**: Styled text specifically for footnotes.
* **`TwoColumnTextBlock`**: Side-by-side rich text columns.
* **`FlexGridBlock`**: A flexible grid of rich text blocks.
* **`CaseStudyBlock`**: Title, body text, image, and CTA link.
* **`CalloutBlock`**: Small styled callout row.
* **`CalloutRowMediumBlock`**: Callout row featuring a CTA button.
* **`CalloutRowBlock`**: Callout with left image, right text, and CTA button.
* **`CalloutRowLightBlock`**: Full-width callout row, light style, with button.
* **`CalltoactionBlock`**: Banner CTA block with customizable classes.
* **`MetacontentBlock`**: Rich text blocks intended for the footer or end of articles.
* **`AccordionBlock`**: Collapsible accordion items list.

### Media Blocks
* **`ImageLinkedBlock`**: Renders an image linking to external or relative URLs.
* **`ImageTextBlock`**: Image aligned side-by-side with rich text.
* **`ImageAlignedBlock`**: Aligns an image left, right, center, or full width.
* **`ImageGridBlock`**: Layout gallery for multiple images at a set width.
* **`ProfileBlock`**: Biography box containing name, title description, photo, and bio text.
* **`ProfileGridBlock`**: A grid layout displaying multiple user profiles.
* **`ImageGalleryBlock`**: List of gallery items with captions.
* **`VideoPromoTileBlock`**: Video card with thumbnail aspect ratio, title description, and internal page link.
* **`NextPreviousBlock`**: Pagination buttons for navigating between pages.
* **`DownloadBlock`**: File download link button.
* **`RelatedContentBlock`**: Grid tiles linking to other articles or external sites.
* **`ProgramBlock`**: Icon or logo block with details.

