# Search blocks (volto-searchblocks)

A Volto add-on that provides a control panel for searching and managing content that uses specific blocks.

[![npm](https://img.shields.io/npm/v/volto-searchblocks)](https://www.npmjs.com/package/volto-searchblocks)
[![](https://img.shields.io/badge/-Storybook-ff4785?logo=Storybook&logoColor=white&style=flat-square)](https://collective.github.io/volto-searchblocks/)
[![CI](https://github.com/collective/collective-searchblocks/actions/workflows/main.yml/badge.svg)](https://github.com/collective/collective-searchblocks/actions/workflows/main.yml)


## Features ✨

- **Search Blocks Control Panel**: Dedicated control panel view for searching content by block types
- **Table Display**: Results displayed in a sortable table with key metadata
- **Pagination**: Navigate through results with configurable page sizes (default, 50, or all)
- **Block Type Selection**: Dropdown selector for choosing which block type to search for
- **Multilingual Support**: Full i18n support with Italian translation included
- **Error Handling**: Comprehensive error displays for API failures
- **Semantic UI Integration**: Uses Volto's standard Semantic UI components for consistent styling

## Installation

To install your project, you must choose the method appropriate to your version of Volto.


### Volto 18 and later

Add `volto-searchblocks` to your `package.json`.

```json
"dependencies": {
    "volto-searchblocks": "*"
}
```

Add `volto-searchblocks` to your `volto.config.js`.

```javascript
const addons = ['volto-searchblocks'];
```

If this package provides a Volto theme, and you want to activate it, then add the following to your `volto.config.js`.

```javascript
const theme = 'volto-searchblocks';
```

### Volto 17 and earlier

Create a new Volto project.
You can skip this step if you already have one.

```
npm install -g yo @plone/generator-volto
yo @plone/volto my-volto-project --addon volto-searchblocks
cd my-volto-project
```

Add `volto-searchblocks` to your `package.json`.

```JSON
"addons": [
    "volto-searchblocks"
],

"dependencies": {
    "volto-searchblocks": "*"
}
```

Download and install the new add-on.

```
yarn install
```

Start Volto.

```
yarn start
```

## Test installation

Visit http://localhost:3000/ in a browser, login, and check the awesome new features.


## Development

The development of this add-on is done in isolation using pnpm workspaces, the latest `mrs-developer`, and other Volto core improvements.
For these reasons, it only works with pnpm and Volto 18.


### Prerequisites ✅

-   An [operating system](https://6.docs.plone.org/install/create-project-cookieplone.html#prerequisites-for-installation) that runs all the requirements mentioned.
-   [nvm](https://6.docs.plone.org/install/create-project-cookieplone.html#nvm)
-   [Node.js and pnpm](https://6.docs.plone.org/install/create-project.html#node-js) 22
-   [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, then change your working directory.

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

2.  Install this code base.

    ```shell
    make install
    ```


### Make convenience commands

Run `make help` to list the available Make commands.


### Set up development environment

Install package requirements.

```shell
make install
```

### Start developing

Start the backend.

```shell
make backend-docker-start
```

In a separate terminal session, start the frontend.

```shell
make start
```

### Lint code

Run ESlint, Prettier, and Stylelint in analyze mode.

```shell
make lint
```

### Format code

Run ESlint, Prettier, and Stylelint in fix mode.

```shell
make format
```

### i18n

Extract the i18n messages to locales.

```shell
make i18n
```

### Unit tests

Run unit tests.

```shell
make test
```

### Run Cypress tests

Run each of these steps in separate terminal sessions.

In the first session, start the frontend in development mode.

```shell
make acceptance-frontend-dev-start
```

In the second session, start the backend acceptance server.

```shell
make acceptance-backend-start
```

In the third session, start the Cypress interactive test runner.

```shell
make acceptance-test
```

## License

The project is licensed under the MIT license.