murph-doc/docs/crud/configuration.md

# Configuration

A generated crud controller contains a method named `getConfiguration`. This methods returns a instance of `App\Core\Crud\CrudConfiguration`.

## setPageTitle

`setPageTitle(string $page, string $title)`

Set the title of the given page.

Example of usage in a CRUD template: `<title>{{ configuration.pageTitle('index') }}</title>`.

## setPageRoute

`setPageRoute(string $page, string $route)`

Set the route of the given page. By default, pages are: `index`, `edit`, `new`, `show`. You can create a custom page for a custom controller.

Example of usage in a CRUD template: `<a href="{{ path(configuration.pageRoute('new')) }}">...</a>`.

## setForm

`setForm(string $context, string $form, `array` $options = [])`

Set the form used in the given context.

## setFormOptions

`setFormOptions(string $context, `array` $options = [])`

Defines options given to a form.

## setAction

`setAction(string $page, string $action, bool|callable $enabled)`

Set if an action is enabled or not in the given page. Take a look at `core/Resources/views/admin/crud/*.html.twig` for more information. Depending the context, the callable could receive the entity in parameter. Example:

```
->setAction('index', 'edit', function(EntityInterface $entity) {
    return $entity->getUser()->getId() === $this->getUser()->getId();
})
```

Usage in a CRUD template: `{% if configuration.action('index', 'new')%}...{% endif %}`.

## setActionTitle

`setActionTitle(string $page, string $action, string $title)`

Set the title of an action in the given page.

Example of usage in a CRUD template: `{{ configuration.actionTitle(context, 'new', 'New')|trans }}`

## setView

`setView(string $context, string $view)`

Override a view.

| Controller (context)   | View                                | Description                   |
| ----------             | ----                                | -----------                   |
| `index`                | `@Core/admin/crud/index.html.twig`  | Template of the page `index`  |
| `edit`                 | `@Core/admin/crud/edit.html.twig`   | Template of the page `edit`   |
| `new`                  | `@Core/admin/crud/new.html.twig`    | Template of the page `new`    |
| `show`                 | `@Core/admin/crud/show.html.twig`   | Template of the page `show`   |
| `filter`               | `@Core/admin/crud/filter.html.twig` | Template of the page `filter` |

| Form (context)      | View                                            | Description                                |
| ----                | ----                                            | -----------                                |
| `form`              | `@Core/admin/crud/_form.html.twig`              | Template to render a form                  |
| `form_widget`       | `@Core/admin/crud/_form_widget.html.twig`       | Template to render a form widget           |
| `form_translations` | `@Core/admin/crud/_form_translations.html.twig` | Template to render a the translation field |

| Entity (context) | View                               | Description                   |
| ------           | ----                               | -----------                   |
| `show_entity`    | `@Core/admin/crud/_show.html.twig` | Template to render the entity |

## setViewDatas

`setViewDatas(string $context, `array` $datas)` and `addViewData(string $context, string $name, $value)`

Add datas given to a view. Useful in a custom controller.

## setField

`setField(string $context, string $label, string $field, `array` $options)`

Add a field displayed in the given context. Used in the index.

```
use App\Core\Crud\Field;

$configuration->setField('index', 'Title', Field\TextField::class, [
    // options
])
```

All fields have these options:

| Option              | Type       | Default                                 | Description                                                |
| ------              | ----       | -------                                 | -----------                                                |
| `property`          | `string`   | `null`                                  | Entity's property to display                               |
| `property__builder` | `callable` | `null`                                  | A callable data and used to generate the content displayed |
| `view`              | `string`   | `@Core/admin/crud/field/text.html.twig` | The templated rendered                                     |
| `default_value`     | `string`   | `null`                                  | Default value to display when the property is `null`       |
| `action`            | `string`   | `null`                                  | An action to perform on click (`null`, `edit`, `view`)     |
| `raw`               | `boolean`  | `false`                                 | Render as HTML                                             |
| `sort`              | `array     | callable`                               | `null`                                                     | Defines how to sort                     |
| `href`              | `string    | callable`                               | `null`                                                     | Data to generate a link                 |
| `href_attr`         | `array     | callable`                               | `null`                                                     | Attributes of the link                  |
| `inline_form`       | `null      | callable`                               | `null`                                                     | A method to define a form to edit datas |
| `inline_form_validation`       | `null      | callable`                               | `null`                                                     | A method to define a custom form validation callback |


```php-inline title="Example #0"
$configuration->setField('index', 'My field', TextField::class, [
    'property' => 'myProperty',
    // OR
    'property_builder' => function($entity, array $options) {
        return $entity->getMyProperty();
    },
])
```

```php-inline title="Example #1"
$configuration->setField('index', 'My field', TextField::class, [
    'raw' => true,
    'property_builder' => function($entity, array $options) {
        return sprintf('<span class="foo">%s</span>', $entity->getBar());
    },
])
```

```php-inline title="Example #2"
// https://127.0.0.7:8000/admin/my_entity?_sort=property&_sort_direction=asc
$configuration->setField('index', 'My field', TextField::class, [
    'property' => 'myProperty'
    'sort' => ['property', '.myProperty'],
    // OR
    'sort' => ['property', function(MyEntityRepositoryQuery $query, $direction) {
        $query->orderBy('.myProperty', $direction);
    }],
])
```

```php-inline title="Example #3"
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Validator\Constraints\NotBlank;

$configuration->setField('index', 'My field', TextField::class, [
    'property' => 'myProperty',
    'inline_form' => function(FormBuilderInterface $builder, EntityInterface $entity) {
        $builder->add('myProperty', TextType::class, [
            'required' => true,
            'constraints' => [new NotBlank()],
        ]);
    }
])
```

### TextField

`App\Core\Crud\Field\TextField`

| Option | Type     | Default                                 | Description            |
| ------ | ----     | -------                                 | -----------            |
| `view` | `string` | `@Core/admin/crud/field/text.html.twig` | The templated rendered |

### DateField

`App\Core\Crud\Field\DateField`

| Option   | Type     | Default                                 | Description            |
| ------   | ----     | -------                                 | -----------            |
| `view`   | `string` | `@Core/admin/crud/field/date.html.twig` | The templated rendered |
| `format` | `string` | `Y-m-d`                                 | The date format        |

### DatetimeField

`App\Core\Crud\Field\DatetimeField`

| Option   | Type     | Default                                 | Description            |
| ------   | ----     | -------                                 | -----------            |
| `view`   | `string` | `@Core/admin/crud/field/date.html.twig` | The templated rendered |
| `format` | `string` | `Y-m-d H:i:s`                           | The date format        |

### ButtonField

`App\Core\Crud\Field\ButtonField`

| Option                | Type        | Default                                   | Description                                         |
| ------                | ----        | -------                                   | -----------                                         |
| `view`                | `string`    | `@Core/admin/crud/field/button.html.twig` | The templated rendered                              |
| `button_attr`         | `array`     | `[]`                                      | Button HTML attributes                              |
| `button_attr_builder` | `callabled` | `null`                                    | A callable data and used to generate `button__attr` |
| `button_tag`          | `string`    | `button`                                  | HTML tag of the button                              |

### ImageField

`App\Core\Crud\Field\ImageField`

| Option       | Type     | Default                                  | Description            |
| ------       | ----     | -------                                  | -----------            |
| `view`       | `string` | `@Core/admin/crud/field/image.html.twig` | The templated rendered |
| `image_attr` | `array`  | `[]`                                     | Image HTML attributes  |

### BooleanField

`App\Core\Crud\Field\BooleanField`

| Option                      | Type     | Default                                    | Description                                                          |
| ------                      | ----     | -------                                    | -----------                                                          |
| `view`                      | `string` | `@Core/admin/crud/field/boolean.html.twig` | The templated rendered                                               |
| `display`                   | `string` | `toggle`                                   | Type of render (`toggle` or `checkbox`)                              |
| `checkbox_class_when_true`  | `string` | `fa-check-square`                          | HTML class added when the value is `true` and display is `checkbox`  |
| `checkbox_class_when_false` | `string` | `fa-square`                                | HTML class added when the value is `false` and display is `checkbox` |
| `toggle_class_when_true`    | `string` | `bg-success`                               | HTML class added when the value is `true` and display is `toggle`    |
| `toggle_class_when_false`   | `string` | `bg-secondary`                             | HTML class added when the value is `false` and display is `toggle`   |

## setMaxPerPage

`setMaxPerPage(string $page, int $max)`

Set how many elements are displayed in a single page.

## setI18n

`setI18n(array $locales, string $defaultLocale)`

Set an array of locales for a translatable entity. The default locale is used in the index page.
Compatible with [https://github.com/KnpLabs/DoctrineBehaviors/blob/master/docs/translatable.md](https://github.com/KnpLabs/DoctrineBehaviors/blob/master/docs/translatable.md).

## setDefaultSort

`setDefaultSort(string $context, string $label, string $direction = 'asc')`

Set the default sort applied in the repository query.

```php-inline
$configuration
    ->setDefaultSort('index', 'title', 'asc')
    ->setField('index', 'Title', Field\TextField::class, [
        'property' => 'title',
        'sort' => ['title', '.title'],
    ]);
```

## setIsSortableCollection

`setIsSortableCollection(string $page, bool $isSortableCollection)`

It enables the drag & drop to sort entities.

```php-inline
class MyEntity implements EntityInterface
{
    // ...

    /**
     * @ORM\Column(type="integer", nullable=true)
     */
    private $sortOrder;

    public function getSortOrder(): ?int
    {
        return $this->sortOrder;
    }

    public function setSortOrder(?int $sortOrder): self
    {
        $this->sortOrder = $sortOrder;

        return $this;
    }

    // ...
}
```

## setSortableCollectionProperty

`setSortableCollectionProperty(string $sortableCollectionProperty)`

In order to sort entities, the default property used is `sortOrder`. You can set something else.

## setBatchAction

`setBatchAction(string $context, string $action, string $label, callable $callack)`

Add a batch action. The callback has 2 arguments:

* An instance of `App\Core\Entity\EntityInterface`
* An instance of `App\Core\Manager\EntityManager`

```php-inline
use App\Core\Entity\EntityInterface;
use App\Core\Manager\EntityManager;

$configuration->setBatchAction(
    'index',
    'delete',
    'Delete',
    function(EntityInterface $entity, EntityManager $manager) {
        $manager->delete($entity);
    }
);
```

## setGlobalBatchAction

`setGlobalBatchAction(string $context, string $action, string $label, callable $callack)`

Add a global batch action. The callback has 3 arguments:

* An instance of `App\Core\Repository\RepositoryQuery`
* An instance of `App\Core\Manager\EntityManager`
* An array of selected entities or a `null` value

Do not use the same action in global and classic batch action.

The callback can return a response. If not, the user will be redirect automatically. See the example below:

```php-inline
use App\Core\Entity\RepositoryQuery;
use App\Core\Manager\EntityManager;
use Symfony\Component\HttpFoundation\JsonResponse;

$configuration->setGlobalBatchAction(
    'index',
    'export_json',
    'Export to JSON',
    function(RepositoryQuery $query, EntityManager $manager, ?array $selection): JsonResponse {
        $items = $selection ?? $query->find();

        return $this->json($items);
    }
);
```