• v2.0
    • Versions
    • master
    • v3.2
    • v3.1
    • v3.0
    • v2.3
    • v2.2
    • v2.1
    • v2.0
    • v1.7
    • v1.6
    • v1.5
    • v1.4
    • v1.3
    • v1.2
    • v1.1
    • v1.0
Caution! You are browsing the documentation for Akeneo in version 2.0, which is not maintained anymore.
Consider upgrading to the latest version.

 

  • Install Akeneo PIM
    • Install Akeneo PIM with Docker
    • Install Akeneo PIM manually
      • System Requirements
      • System installation on Debian 9 (Stretch)
      • System installation on Ubuntu 16.04 (Xenial Xerus)
      • Installing Akeneo PIM Community Edition (CE) with the Archive
      • Installing Akeneo PIM Enterprise Edition (EE) with the Archive
      • Setting up the job queue daemon
    • How to customize the Dataset
    • How to Add Translation Packs
  • Migrate Akeneo PIM projects
  • Import and Export data
    • How import works
    • Understanding the Product Import
    • Understanding the Product Export
    • Formats
      • Localized labels
      • Scopable labels
      • Association types data structure
      • Attribute data structure
      • Category data structure
      • Family data structure
      • Family variant data structure
      • Group data structure
      • Options data structure
      • Product data structure
      • Product model data structure
    • Akeneo Connectors
    • How to Customize Import / Export
      • How to create a new Connector
      • How to import Products from a XML file
      • How to clean a CSV file during a Product import
      • How to automate imports/exports
  • Manipulate the Akeneo PIM data
    • How to Customize Mass Edit Operations
      • How to register a new bulk action
      • How to Register a New Mass Edit Action on Products
      • How to Avoid Rules Execution on Mass Edit Actions
    • How to Manipulate Products
      • How to Query Products
      • How to Create Products
      • How to Update Products
      • How to Validate Products
      • How to Save Products
      • How to Remove Products
    • How to Manipulate Non-Product Objects
      • How to Query Non-Product Objects
      • How to Create Non-Product Objects
      • How to Update Non-Product Objects
      • How to Validate Non-Product Objects
      • How to Save Non-Product Objects
      • How to Remove Non-Product Objects
    • How to add a custom action rule
      • General information about rule format
      • How to add a custom action in the rule engine
    • How to Define Access Control List
    • How to Customize the Catalog Structure
      • How to Create a Reference Data
      • How to add a custom unit of measure
      • How to Add New Properties to a Category
    • How to Customize Product Assets
      • How to Add a New Transformation
      • How to Add a Default Thumbnail For Unknown File Types
      • How to connect to an external server for storage
      • How to change the validation rule to match a reference file to an asset
      • How to Mass Import Assets
    • How To Customize Teamwork Assistant (Enterprise Edition)
      • Customize notifications
      • Add a calculation step
      • How to log calculation step
      • Remove projects impacted by a custom catalog update
  • Design the user interfaces
    • How to customize any frontend part of the application
    • How to add an action button or meta data to the product edit form
    • How to add a tab to a form
    • How to add a new tab in System / Configuration
    • How to add custom information to a field
    • How to add a new field type
    • Create a custom product export builder filter
    • How to create the UI to manage a Reference Data
    • How to add a new page
    • How to customize the main menu
    • Styleguide
  • Maintain Akeneo PIM projects
    • First aid kit
    • Bug qualification
    • Common issues
    • Scalability Guide
      • Audit with 3 Representative Catalogs
      • More than 10k attributes?
      • More than 10k families?
      • More than 10k categories?
      • More than 500 attributes usable in the product grids?
      • More than 100k products to export?
      • More than 1GB of product media to export?
    • How to purge history
      • How to Purge jobs executions
      • How to adapt the version purger to your needs
  • Contribute to Akeneo PIM
    • How to report an issue?
    • How to translate the user interface?
    • How to enhance the documentation?
    • How to contribute to a Connector?
    • How to submit a patch to the PIM?
    • How behavior tests are architectured in the PIM?
      • Establishing Decorator Pattern
      • Using Spin In Behat
  • Technical overview
    • Product Information
    • Teamwork Assistant (Enterprise Edition)
      • Project creation
      • Project completeness
      • Project Completeness widget
      • Catalog update impact
      • Scalability guide
      • Users permission summary for Behat tests
    • Collaborative workflow
      • Simple workflow
      • Partial workflow
  • Technical architecture
    • Best Practices
      • Create a project
      • Create a reusable bundle
      • Setup Behat
      • Code Conventions
      • Coding Standards
    • Bundles
    • Components
    • How to implement your business logic using the event system
    • Events
      • Storage events
      • Workflow events (Enterprise Edition only)
    • How to Localize your data
      • How to change the PIM locale
      • How to Use Localizers
      • How to use Presenters
    • How to Add a Notification
    • Performances Guide
      • Memory usage of rules execution (Enterprise Edition)
      • Memory leak fix in Rules Engine (ORM)
      • More than 100 WYSIWYG editors in a page
      • PHP7 and HHVM Compatibility?
    • How to Use the Web REST API
    • Standard format
      • Products
      • Other entities
      • Usage
    • Application Technical Information
      • Application Technical Dependencies
      • Server side set up for hosting
      • System Requirements
      • Recommended configuration
      • Client side configuration and compatibilities
      • Operation processes
      • Flow Matrix
  • Akeneo Cloud Edition
    • Flexibility Mode
      • Overview
      • Partners Starterkit
      • Environments Access
      • Composer settings
      • Periodic tasks / Crontab settings
      • PIM Application
      • PIM Updates and Migrations
      • Data File Transfer
      • Backups management
      • Partners
      • Queue management
      • System Components
      • Disk Usage
    • Serenity Mode
      • Overview
      • PIM Updates and Migrations

How to Add New Properties to a Category¶

The Akeneo PIM allows the classification of products inside a customizable category tree.

Note

To implement this task you have to be comfortable with Symfony bundle overriding and Symfony services. This cookbook can be used to override other entities such as an attribute.

Add Non Translatable Properties to your own Category¶

Extend the category entity¶

The first step is to create a class that extends PIM Category class.

For example, we can add a description property with a text field.

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

namespace Acme\Bundle\CatalogBundle\Entity;

use Pim\Bundle\CatalogBundle\Entity\Category as BaseCategory;

class Category extends BaseCategory
{
    protected $description;

    public function getDescription()
    {
        return $this->description;
    }

    public function setDescription($description)
    {
        $this->description = $description;

        return $this;
    }
}

Configure the mapping override¶

Then, define the mapping for your own field only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# /src/Acme/Bundle/CatalogBundle/Resources/config/doctrine/Category.orm.yml
Acme\Bundle\CatalogBundle\Entity\Category:
    type: entity
    table: pim_catalog_category
    changeTrackingPolicy: DEFERRED_EXPLICIT
    repositoryClass: Akeneo\Bundle\ClassificationBundle\Doctrine\ORM\Repository\CategoryRepository
    uniqueConstraints:
        pim_category_code_uc:
            columns:
                - code
    gedmo:
        tree:
            type: nested
    fields:
        description:
            type: string
            length: 255
            nullable: true

You also need to configure the mapping override in your application configuration (to avoid to copy/paste the whole parent class mapping):

# app/config/config.yml
akeneo_storage_utils:
    mapping_overrides:
        -
            original: Pim\Bundle\CatalogBundle\Entity\Category
            override: Acme\Bundle\CatalogBundle\Entity\Category

Define the Category Class¶

You need to update your category entity parameter used in entities.yml file:

1
2
3
# /src/Acme/Bundle/CatalogBundle/Resources/config/entities.yml
parameters:
    pim_catalog.entity.category.class: Acme\Bundle\CatalogBundle\Entity\Category

Important

If you are creating a new bundle, double check that this file is inside the extension

# /src/Acme/Bundle/CatalogBundle/DependencyInjection/AcmeAppExtension.php
public function load(array $configs, ContainerBuilder $container)
{
    /** ... **/
    $loader->load('entities.yml');
}

Note

You don’t have to add a lot of code to the Doctrine configuration to resolve target entities. We already have a resolver which injects the new category class name.

Now, you can run the following commands to update your database:

php bin/console doctrine:schema:update --dump-sql
php bin/console doctrine:schema:update --force

Define the Category Form¶

Firstly, you have to create your custom type by inheriting the CategoryType class and then add your custom fields:

 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
# /src/Acme/Bundle/EnrichBundle/Form/Type/CategoryType.php
<?php

namespace Acme\Bundle\EnrichBundle\Form\Type;

use Symfony\Component\Form\FormBuilderInterface;

use Pim\Bundle\EnrichBundle\Form\Type\CategoryType as BaseCategoryType;

/**
 * Type for category properties
 */
class CategoryType extends BaseCategoryType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        parent::buildForm($builder, $options);

        $builder->add('description', 'text',
            [
                'required' => true
            ]
        );
    }
}

Then, you have to override the service definition of your form:

1
2
3
# /src/Acme/Bundle/EnrichBundle/Resources/config/form_types.yml
parameters:
    pim_enrich.form.type.category.class: Acme\Bundle\EnrichBundle\Form\Type\CategoryType

Then, add this new file to your dependency injection extension:

# /src/Acme/Bundle/EnrichBundle/DependencyInjection/AcmeAppExtension.php
public function load(array $configs, ContainerBuilder $container)
{
    /** ... **/
    $loader->load('form_types.yml');
}

Then, don’t forget to add your new field to the twig template:

# /src/Acme/Bundle/EnrichBundle/Resources/views/CategoryTree/Tab/property.html.twig
<!-- ... -->
{% set generalProperties %}
    {{ form_row(form.code) }}
    {{ form_row(form.description) }}
{% endset %}
<!-- ... -->

Make sure you’ve registered the template properly inside form_types.yml:

1
2
3
4
# /src/Acme/Bundle/EnrichBundle/Resources/config/form_types.yml
parameters:
    pim_enrich.form.type.category.class: Acme\Bundle\EnrichBundle\Form\Type\CategoryType
    pim_enrich.view_element.category.tab.property.template: 'AcmeEnrichBundle:CategoryTree:Tab/property.html.twig'

For the form validation you will have to add a new validation file:

# /src/Acme/Bundle/AppBundle/Resources/config/validation/category.yml
Acme\Bundle\AppBundle\Entity\Category:
    properties:
        description:
            - NotBlank: ~

Add Translatable Properties to your own Category¶

Extend the category entity and its translation entity¶

The first step is to create a class that extends PIM CategoryTranslation class.

For example, we can add an optional description property with a text field.

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

namespace Acme\Bundle\CatalogBundle\Entity;

use Pim\Bundle\CatalogBundle\Entity\CategoryTranslation as BaseCategoryTranslation;

class CategoryTranslation extends BaseCategoryTranslation
{
    protected $description;

    public function getDescription()
    {
        return $this->description;
    }

    public function setDescription($description)
    {
        $this->description = $description;

        return $this;
    }
}

Then we need to link this description to the Category class.

 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
# /src/Acme/Bundle/CatalogBundle/Entity/Category.php
<?php

namespace Acme\Bundle\CatalogBundle\Entity;

use Pim\Bundle\CatalogBundle\Entity\Category as BaseCategory;

class Category extends BaseCategory
{
    public function getDescription()
    {
        $translated = ($this->getTranslation()) ? $this->getTranslation()->getDescription() : null;

        return ($translated !== '' && $translated !== null) ? $translated : '['.$this->getCode().']';
    }

    public function setDescription($description)
    {
        $this->getTranslation()->setDescription($description);

        return $this;
    }

    public function getTranslationFQCN()
    {
        return CategoryTranslation::class;
    }
}

Configure the mapping override¶

Then, define the mapping for your own field only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# /src/Acme/Bundle/CatalogBundle/Resources/config/doctrine/CategoryTranslation.orm.yml
Acme\Bundle\CatalogBundle\Entity\CategoryTranslation:
    type: entity
    table: pim_catalog_category_translation
    changeTrackingPolicy: DEFERRED_EXPLICIT
    uniqueConstraints:
        locale_foreign_key_idx:
            columns:
                - locale
                - foreign_key
    fields:
        description:
            type: text
            nullable: true

As we override the Category class, we need to redefine its mapping too, even if we have nothing to add in it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# /src/Acme/Bundle/CatalogBundle/Resources/config/doctrine/Category.orm.yml
Acme\Bundle\CatalogBundle\Entity\Category:
    type: entity
    table: pim_catalog_category
    changeTrackingPolicy: DEFERRED_EXPLICIT
    repositoryClass: Akeneo\Bundle\ClassificationBundle\Doctrine\ORM\Repository\CategoryRepository
    uniqueConstraints:
        pim_category_code_uc:
            columns:
                - code
    gedmo:
        tree:
            type: nested

You also need to configure the mapping override in your application configuration (to avoid to copy/paste the whole parent class mapping):

# app/config/config.yml
akeneo_storage_utils:
    mapping_overrides:
        -
            original: Pim\Bundle\CatalogBundle\Entity\Category
            override: Acme\Bundle\CatalogBundle\Entity\Category
        -
            original: Pim\Bundle\CatalogBundle\Entity\CategoryTranslation
            override: Acme\Bundle\CatalogBundle\Entity\CategoryTranslation

Define the Category Class¶

You need to update your category entity parameter used in entities.yml file:

1
2
3
4
# /src/Acme/Bundle/CatalogBundle/Resources/config/entities.yml
parameters:
    pim_catalog.entity.category.class: Acme\Bundle\CatalogBundle\Entity\Category
    pim_catalog.entity.category_translation.class: Acme\Bundle\CatalogBundle\Entity\CategoryTranslation

Important

If you are creating a new bundle, double check that this file is inside the extension

# /src/Acme/Bundle/CatalogBundle/DependencyInjection/AcmeAppExtension.php
public function load(array $configs, ContainerBuilder $container)
{
    /** ... **/
    $loader->load('entities.yml');
}

Note

You don’t have to add a lot of code to the Doctrine configuration to resolve target entities. We already have a resolver which injects the new category class name.

Now, you can run the following commands to update your database:

php bin/console doctrine:schema:update --dump-sql
php bin/console doctrine:schema:update --force

Define the Category Form¶

Firstly, you have to create your custom type by inheriting the CategoryType class and then add your custom fields:

 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
# /src/Acme/Bundle/EnrichBundle/Form/Type/CategoryType.php
<?php

namespace Acme\Bundle\EnrichBundle\Form\Type;

use Symfony\Component\Form\FormBuilderInterface;

use Pim\Bundle\EnrichBundle\Form\Type\CategoryType as BaseCategoryType;

/**
 * Type for category properties
 */
class CategoryType extends BaseCategoryType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        parent::buildForm($builder, $options);

        $builder->add(
            'description',
            'pim_translatable_field',
            [
                'field'             => 'description',
                'translation_class' => $this->translationDataClass,
                'entity_class'      => $this->dataClass,
                'property_path'     => 'translations',
                'widget'            => 'textarea',
            ]
        );
    }
}

Then, you have to override the service definition of your form:

1
2
3
# /src/Acme/Bundle/EnrichBundle/Resources/config/form_types.yml
parameters:
    pim_enrich.form.type.category.class: Acme\Bundle\EnrichBundle\Form\Type\CategoryType

Then, add this new file to your dependency injection extension:

# /src/Acme/Bundle/EnrichBundle/DependencyInjection/AcmeAppExtension.php
public function load(array $configs, ContainerBuilder $container)
{
    /** ... **/
    $loader->load('form_types.yml');
}

Then, don’t forget to add your new field to the twig template:

# /src/Acme/Bundle/EnrichBundle/Resources/views/CategoryTree/Tab/property.html.twig
<!-- ... -->
{% set nodeValues %}
    {{ form_row(form.label) }}
    {{ form_row(form.description) }}
{% endset %}
<!-- ... -->

Make sure you’ve registered the template properly inside form_types.yml:

1
2
3
4
# /src/Acme/Bundle/EnrichBundle/Resources/config/form_types.yml
parameters:
    pim_enrich.form.type.category.class: Acme\Bundle\EnrichBundle\Form\Type\CategoryType
    pim_enrich.view_element.category.tab.property.template: 'AcmeEnrichBundle:CategoryTree:Tab/property.html.twig'

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!