Metadata-Version: 2.4
Name: collective.searchblocks
Version: 0.1.0.dev1
Summary: Additional control-panel that allow users to search which contents using a specific block
Project-URL: Homepage, https://github.com/collective/collective-searchblocks
Project-URL: PyPI, https://pypi.org/project/collective.searchblocks
Project-URL: Source, https://github.com/collective/collective-searchblocks
Project-URL: Tracker, https://github.com/collective/collective-searchblocks/issues
Author-email: RedTurtle Technology <sviluppo@redturtle.it>
License: GPL-2.0-only
License-File: LICENSE.GPL
License-File: LICENSE.md
Keywords: CMS,Plone,Python
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.0
Classifier: Framework :: Plone :: 6.1
Classifier: Framework :: Plone :: Addon
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: plone-api
Requires-Dist: plone-restapi
Requires-Dist: plone-volto
Requires-Dist: products-cmfplone>=6.0.0
Provides-Extra: test
Requires-Dist: horse-with-no-namespace; extra == 'test'
Requires-Dist: plone-app-testing; extra == 'test'
Requires-Dist: plone-restapi[test]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-plone>=0.5.0; extra == 'test'
Description-Content-Type: text/markdown

# collective.searchblocks

A comprehensive Plone add-on that provides search functionality for content using specific blocks.

## Features ✨

- **Block Search Endpoint**: RESTful API endpoint (`/@search-blocks`) for searching content by block types
- **Security**: Permission-based access control for the search API
- **Catalog Integration**: Uses Plone's catalog for efficient searching
- **Metadata Support**: Returns rich metadata including title, type, review state, creation and modification dates
- **Pagination**: Support for batched results with configurable page sizes
- **Sorting**: Results sorted by title for consistent ordering

## Installation

Install collective.searchblocks with uv.

```shell
uv add collective.searchblocks
```

Create the Plone site.

```shell
make create-site
```

## REST API

### @search-blocks

Search for content using specific blocks.

**GET /@search-blocks**

Returns a list of all available block types in the catalog.

Response:
```json
{
  "block_types": ["slider", "hero", "text"]
}
```

**GET /@search-blocks?block_types=slider**

Returns content items that have the specified block type, formatted using the standard summary serializer.

Response:
```json
{
  "block_types": ["slider", "hero", "text"],
  "items": [
    {
      "@id": "http://localhost:8080/Plone/doc-1",
      "@type": "Document",
      "title": "Doc 1",
      "description": "...",
      "review_state": "published"
    }
  ],
  "items_total": 1
}
```

Parameters:
- `block_types` (string): The block type to search for.
- `b_size` (int): Batch size (pagination).
- `b_start` (int): Batch start index (pagination).
- `sort_on` (string, automatic): Sorts results by `sortable_title` (automatically added).
- `metadata_fields` (list, automatic): Includes `modified` and `created` metadata fields (automatically added).

## Contribute

- [Issue tracker](https://github.com/collective/collective-searchblocks/issues)
- [Source code](https://github.com/collective/collective-searchblocks/)

### Prerequisites ✅

-   An [operating system](https://6.docs.plone.org/install/create-project-cookieplone.html#prerequisites-for-installation) that runs all the requirements mentioned.
-   [uv](https://6.docs.plone.org/install/create-project-cookieplone.html#uv)
-   [Make](https://6.docs.plone.org/install/create-project-cookieplone.html#make)
-   [Git](https://6.docs.plone.org/install/create-project-cookieplone.html#git)
-   [Docker](https://docs.docker.com/get-started/get-docker/) (optional)

### Installation 🔧

1.  Clone this repository.

    ```shell
    git clone git@github.com:collective/collective-searchblocks.git
    cd collective-searchblocks/backend
    ```

2.  Install this code base.

    ```shell
    make install
    ```


### Add features using `plonecli` or `bobtemplates.plone`

This package provides markers as strings (`<!-- extra stuff goes here -->`) that are compatible with [`plonecli`](https://github.com/plone/plonecli) and [`bobtemplates.plone`](https://github.com/plone/bobtemplates.plone).
These markers act as hooks to add all kinds of features through subtemplates, including behaviors, control panels, upgrade steps, or other subtemplates from `bobtemplates.plone`.
`plonecli` is a command line client for `bobtemplates.plone`, adding autocompletion and other features.

To add a feature as a subtemplate to your package, use the following command pattern.

```shell
make add <template_name>
```

For example, you can add a content type to your package with the following command.

```shell
make add content_type
```

You can add a behavior with the following command.

```shell
make add behavior
```

```{seealso}
You can check the list of available subtemplates in the [`bobtemplates.plone` `README.md` file](https://github.com/plone/bobtemplates.plone/?tab=readme-ov-file#provided-subtemplates).
See also the documentation of [Mockup and Patternslib](https://6.docs.plone.org/classic-ui/mockup.html) for how to build the UI toolkit for Classic UI.
```

## License

The project is licensed under GPLv2.

## Credits and acknowledgements 🙏

Generated from the [`cookieplone-templates`  template](https://github.com/plone/cookieplone-templates/tree/main/) on 2026-01-14 14:29:54.. A special thanks to all contributors and supporters!
