How to Create a Custom Entity and the Screens to Manage it

Note

The code inside this cookbook entry is visible in src directory, you can clone pim-dev then do a symlink and install

Note

The code inside this cookbook entry requires you to install the akeneo/custom-entity-bundle package.

Creating the Entity

As Akeneo relies heavily on standard tools like Doctrine, creating the entity is quite straightforward for any developer with Doctrine experience.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# /src/Acme/Bundle/CatalogBundle/Entity/Color.php
<?php

namespace Acme\Bundle\CatalogBundle\Entity;

use Pim\Bundle\CustomEntityBundle\Entity\AbstractTranslatableCustomOption;

/**
 * Custom color entity
 */
class Color extends AbstractTranslatableCustomOption
{
    /**
     * {@inheritdoc}
     */
    public function getTranslationFQCN()
    {
        return 'Acme\Bundle\CatalogBundle\Entity\ColorTranslation';
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# /src/Acme/Bundle/CatalogBundle/Resources/config/doctrine/Color.orm.yml
Acme\Bundle\CatalogBundle\Entity\Color:
    type: entity
    table: acme_catalog_color
    repositoryClass: Pim\Bundle\CustomEntityBundle\Entity\Repository\TranslatableCustomOptionRepository
    fields:
        id:
            type: integer
            id: true
            generator:
                strategy: AUTO
        code:
            type: string
            length: 100
            unique: true
        created:
            type: datetime
            gedmo:
                timestampable:
                    on: create
        updated:
            type: datetime
            gedmo:
                timestampable:
                    on: update
    oneToMany:
        translations:
            targetEntity: Acme\Bundle\CatalogBundle\Entity\ColorTranslation
            mappedBy: foreignKey
            cascade:
                - persist

Note

To ease the integration of the entity in the PIM, we extended an abstract class from CustomEntityBundle. Several abstract entity and repositories are available in this bundle to help you with different requirements.

Creating the Entity Management Screens

The Grid

To benefit from the grid component (which comes natively with filtering and sorting), you can define the vendor grid as following :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# /src/Acme/Bundle/EnrichBundle/Resources/config/datagrid.yml
datagrid:
    color:
        extends: custom_entity
        options:
            entityHint: color
        columns:
            code:
                label: Code
            label:
                label: Label
            created:
                label: Created
                frontend_type: date
            updated:
                label: Updated
                frontend_type: date
        filters:
            columns:
                code:
                    type:      string
                    label:     Code
                    data_name: o.code
                label:
                    type:      string
                    label:     Label
                    data_name: translation.label
                created:
                    type:             date
                    label:            Created
                    data_name:        o.created
                    filter_by_having: true
                updated:
                    type:             date
                    label:            Updated
                    data_name:        o.udapted
                    filter_by_having: true
        sorters:
            columns:
                code:
                    data_name: o.code
                label:
                    data_name: translation.label
                created:
                    data_name: o.created
                updated:
                    data_name: o.udapted
            default:
                code: '%oro_datagrid.extension.orm_sorter.class%::DIRECTION_ASC'

Creating the Form Type for this Entity

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# /src/Acme/Bundle/EnrichBundle/Form/Type/ColorType.php
<?php

namespace Acme\Bundle\EnrichBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

/**
 * Type for color custom entity
 */
class ColorType extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('code')
            ->add(
                'label',
                'pim_translatable_field',
                array(
                    'field'             => 'label',
                    'translation_class' => 'Acme\Bundle\CatalogBundle\Entity\ColorTranslation',
                    'entity_class'      => $options['data_class'],
                    'property_path'     => 'translations'
                )
            );
    }

    /**
     * {@inheritdoc}
     */
    public function getName()
    {
        return 'acme_enrich_color';
    }
}

Creating the CRUD

A complete CRUD can be easily obtained by adding a custom_entities.yml file in one of your bundles.

1
2
3
4
5
6
7
8
9
# /src/Acme/Bundle/EnrichBundle/Resources/config/custom_entities.yml
custom_entities:
    color:
        entity_class: Acme\Bundle\CatalogBundle\Entity\Color
        actions:
            edit:
                form_type: acme_enrich_color
            create:
                form_type: acme_enrich_color

From this point a working grid screen is visible at /app_dev.php/enrich/color.

If some vendors are manually added to the database, the pagination will be visible as well.

Note

Have a look at the Cookbook recipe “How to add an menu entry” to add your own link in the menu to this grid.