Fields configuration

Configure Fields by Attributes
Configure Fields by overriding controllers
Configure Fields by using Listeners

?> Fields are the metadata that represents how an entity is rendered. One field represents an entity's properties, such as name for example.

Configure Fields by Attributes

You can add attributes directly to an entity to configure how it's going to be parsed. This is the quickest way to customize a Crud, but has some limitations.

Let's take a look at an example, here's a simple Category entity:

use Arkounay\Bundle\QuickAdminGeneratorBundle\Attribute as QAG;
use Doctrine\ORM\Mapping as ORM;

 #[ORM\Entity]
class Category
{

     #[ORM\Id]
     #[ORM\GeneratedValue]
     #[ORM\Column(type: 'integer')]
    private $id;


    #[ORM\Column(type: 'string', length: 255)]
    #[QAG\Field(label: 'Title')]
    #[QAG\Sort(direction: 'asc')]
    private $name;

    #[ORM\OneToMany(targetEntity: News::class, mappedBy: 'category', cascade: ['persist', 'remove'])]
    #[QAG\HideInList]
    private $news;

    // constructor, getters, setters, etc
}

In this example:

The $name field will have a "Title" label instead of the autogenerated Name, through the #[QAG\Field(label: 'Title')] attribute.
It will be also sorted by name, alphabetically. That is specified by the #[QAG\Sort(direction: 'asc')] attribute.
The list will not show the number of news, as #[QAG\HideInList] removes the properties from the list.

You can import the QAG attributes with

use Arkounay\Bundle\QuickAdminGeneratorBundle\Attribute as QAG;

There are 13 attributes available:

QAG\Field
QAG\HideInForm
QAG\HideInList
QAG\HideInExport
QAG\HideInView
QAG\Ignore
QAG\Sort
QAG\Crud
QAG\Show (only in manual fetch mode)
QAG\ShowInList (only in manual fetch mode)
QAG\ShowInForm (only in manual fetch mode)
QAG\ShowInView (only in manual fetch mode)
QAG\ShowInExport (only in manual fetch mode)

QAG\Field

Allows you to configure a field. Has 10 properties.

label changes the label. Uses the variable's name by default.
twigName changes the twig called to render the field in the listing. The twig filed needs to be located at templates/bundles/ArkounayQuickAdminGeneratorBundle/crud/fields/_[twigName].html.twig. Keep the underscore character _ before the file's name. Inside a twig, you can use the variables value to get the field's value and entity to get the full entity. There is also the detail variable that is true when the twig is included in the "view" action, otherwise it's false when display in list. For instance, this can be used to have a specific date format for an entity.
sortable defines whether or not the field can be sorted when clicking on it. By default, all fields are sortable except virtual fields and relations.
formType is the Form Type that will be used when rendering the form. For example, if you have an email field, you can use Symfony\Component\Form\Extension\Core\Type\EmailType to quickly set the type to Email. Note that it should be used only for simple Types as you can't pass options. For anything more advanced, consider overriding the form through PHP.
formClass is an additional class that will be added to the form's field, when creating and editing. To add multiple classes, just add a space.
required defines if the form's field is required when editing or creating. If not specified, will automatically try to guess it with doctrine's metadata.
help and placeholder will change the corresponding form attribute when creating / editing.
options allow to override all the forms options. It has priority for form building over label, help, placeholder and formClass
position defines in which order the fields appear, both in form and list.
payload is a custom payload of mixed type, that can be used for custom event subscribers for example. (see Configure Fields by using Listeners)

This also works on getters to create Virtual Fields. For example:

#[QAG\Field(label: 'Title')]
public function getFirstImage(): string
{
    return $this->images[0];
}

will create a virtual field 'getFirstImage' that will be displayed in lists.

QAG\HideInForm

Allows you to hide a field in both creation and edition.

QAG\HideInList

Allows you to hide a field in listing.

QAG\HideInView

Allows you to hide a field in detail view.

QAG\HideInExport

Allows you to hide a field in the exported file.

QAG\Ignore

Allows you to completely ignore a field. It will not be parsed, and thus hidden from listing, creation, and edition.

QAG\Sort

Allows you to sort by a specific field in listing by default. Has 1 attribute, direction. 'asc' or 'desc', specifies the sorting order. Only one field in an entity should have this attribute.

QAG\Crud

This field must be at the class level.

 #[ORM\Entity(repositoryClass: CategoryRepository::class)]
 #[QAG\Crud(fetchMode: QAG\Crud::FETCH_MANUAL)]
class Category 
{
    // ...
}

It has 1 attribute, fetchMode.

By default, any property added in a doctrine class will be converted into a Field. You can change that by specifying a manual Fetch Mode. In manual mode, you'll have to add #[QAG\Show], #[QAG\ShowInList] and #[QAG\ShowInForm] to make them appear, otherwise fields will be ignored.

QAG\Show (only in manual fetch mode)

Will show the field

QAG\ShowInForm (only in manual fetch mode)

Will show the field both in creation and edition

QAG\ShowInList (only in manual fetch mode)

Will show the field in listing

QAG\ShowInView (only in manual fetch mode)

Will show the field in detail view

QAG\ShowInExport (only in manual fetch mode)

Will show the field in the exported file

Configure Fields by overriding controllers

Another way to configure a field is by overriding the entity's crud controller that refers to this field. This gives more control than attributes. For example, in a Category crud controller, you can do this:

namespace App\Controller\Admin;


use App\Entity\Category;
use Arkounay\Bundle\QuickAdminGeneratorBundle\Controller\Crud;
use Arkounay\Bundle\QuickAdminGeneratorBundle\Model\Fields;

class CategoryController extends Crud
{

    public function getEntity(): string
    {
        return Category::class;
    }

    protected function getListingFields(): Fields
    {
        $fields = parent::getListingFields();
        $fields['id']->setSortable(false);

        return $fields
            ->remove('name')
            ->add('slug'); // adds a virtual field (if there is a getSlug() method)
    }

    protected function getFormFields(): Fields
    {
        $fields = parent::getFormFields();
        $fields['name']->setLabel("Please specify the name");

        return $fields;
    }

}

In this example:

In listing mode, a new field called 'slug' will be created. This is a virtual field (Category has a getSlug() method). The 'name' field will be removed.
In creation and edition, the field 'name' will have a special label.

Configure Fields by using Listeners

It's also possible to configure fields using listener. This is useful if you wish to add special rules for fields that can be applied globally. To do that, you need to listen to the qag.events.field_generation event. The event's subject is the field itself.

Here's an example:

namespace App\Listener\AdminForm;


use Arkounay\Bundle\QuickAdminGeneratorBundle\Model\Field;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\EventDispatcher\GenericEvent;

class FormPositionListener implements EventSubscriberInterface
{

    public static function getSubscribedEvents()
    {
        return [
            'qag.events.field_generation' => 'fieldGenerationEvent'
        ];
    }

    public function fieldGenerationEvent(GenericEvent $event): void
    {
        /** @var Field $field */
        $field = $event->getSubject();

        if (self::IsPosition($field)) {
            $field->setTwig('@ArkounayQuickAdminGenerator/crud/fields/_position.html.twig');
            $field->setSortable(true);
        }
    }

    private static function IsPosition(Field $field): bool
    {
        return $field->getIndex() === 'position' && $field->getType() === 'integer' ;
    }

}

Here, whenever an entity has a property named position with the type integer, it will automatically use a special Twig template without requiring any extra configuration per controllers or entities.

FilesExpand file tree

Fields.md

Latest commit

History