Metadata-Version: 2.3
Name: wagtail_cblocks
Version: 0.4.2
Summary: Collection of StreamField blocks for Wagtail
Project-URL: Repository, https://framagit.org/cliss21/wagtail-cblocks
Project-URL: Issues, https://framagit.org/cliss21/wagtail-cblocks/-/issues
Author-email: Cliss XXI <contact@cliss21.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: blocks,streamfield,wagtail
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Wagtail
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
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
Requires-Python: >=3.8
Requires-Dist: django>=4.2
Requires-Dist: wagtail>=5.2
Provides-Extra: dev
Requires-Dist: pytest-cov~=5.0; extra == 'dev'
Requires-Dist: pytest-django~=4.8; extra == 'dev'
Requires-Dist: pytest~=8.2; extra == 'dev'
Requires-Dist: ruff~=0.4.4; extra == 'dev'
Requires-Dist: wagtail-factories>=4.0.0; extra == 'dev'
Provides-Extra: factories
Requires-Dist: wagtail-factories>=4.0.0; extra == 'factories'
Description-Content-Type: text/markdown

# wagtail-cblocks

A collection of StreamField blocks to use in Wagtail CMS.

**Warning!** This project is still early on in its development lifecycle. It is
possible for breaking changes to occur between versions until reaching a stable
1.0. Feedback and pull requests are welcome.

## Requirements

wagtail-cblocks requires the following:
- **Python 3** (3.8, 3.9, 3.10, 3.11, 3.12)
- **Django** (4.2 LTS, 5.0)
- **Wagtail** (5.2 LTS, 6.0, 6.1)

## Installation

1. Install using ``pip``:
   ```shell
   $ pip install wagtail-cblocks
   ```
2. Add ``wagtail_cblocks`` to your ``INSTALLED_APPS`` setting:
   ```python
   INSTALLED_APPS = [
       # ...
       'wagtail_cblocks',
       # ...
   ]
   ```

## Usage

Each block comes with a template made for Bootstrap 5 which is not shipped by
this plugin. If you plan to use them as is, you must have at least the Bootstrap
stylesheet loaded in your base template - refer as needed to the
[Bootstrap documentation](https://getbootstrap.com/).

In waiting for the documentation, here is a sample usage:

```python
from wagtail.admin.edit_handlers import StreamFieldPanel
from wagtail.blocks import StreamBlock
from wagtail.fields import StreamField
from wagtail.models import Page

from wagtail_cblocks.blocks import (
    ButtonBlock,
    ColumnsBlock,
    HeadingBlock,
    ImageBlock,
    ParagraphBlock,
)


class BaseBlock(StreamBlock):
    title_block = HeadingBlock()
    paragraph_block = ParagraphBlock()
    button_block = ButtonBlock()
    image_block = ImageBlock()


class BodyBlock(BaseBlock):
    columns_block = ColumnsBlock(BaseBlock())


class StandardPage(Page):
    body = StreamField(BodyBlock())

    content_panels = Page.content_panels + [
        StreamFieldPanel('body'),
    ]
```

Factories are also provided for some of the blocks to ease tests - see
[`wagtail_cblocks/factories.py`](wagtail_cblocks/factories.py). To make use of
them, install the extra *factories* requirements:

```shell
$ pip install wagtail-cblocks[factories]
```

## Development
### Quick start

To set up a development environment, ensure that Python 3 is installed on your
system. Then:

1. Clone this repository
2. Create a virtual environment and activate it:
   ```shell
   $ python3 -m venv venv
   $ source venv/bin/activate
   ```
3. Install this package and its requirements:
   ```shell
   (venv)$ pip install --editable ".[dev]" "tox>=4.11"
   ```

To run the test app interactively, use ``tox -e interactive``, visit
[http://127.0.0.1:8020/admin](http://127.0.0.1:8000/admin/) and log in
with `admin` / `changeme`.

### Contributing

The tests are written with [pytest] and code coverage is measured with [coverage].
You can use the following commands while developing:
- ``make test``: run the tests and output a quick report of code coverage
- ``make test-wip``: only run the tests marked as 'wip'
- ``make test-all``: run the tests on all supported versions of Django and
  Wagtail with [nox]

The Python code is formatted and linted thanks to [ruff]. You can check the code
with ``make lint`` and try to fix the reported issues with ``make format``.

When submitting a pull-request, please ensure that the code is well formatted
and covered, and that all the tests pass.

[pytest]: https://docs.pytest.org/
[coverage]: https://coverage.readthedocs.io/
[nox]: https://nox.thea.codes/
[ruff]: https://docs.astral.sh/ruff/

## License

This extension is mainly developed by [Cliss XXI](https://www.cliss21.com) and
licensed under the [AGPLv3+](LICENSE). Any contribution is welcome!
