Attribute Description Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   • Add the bundle via Composer:

     composer require agencednd/attribute-description-bundle:1.1.*
     

   • Enable the bundle in app/AppKernel.php:

     $bundles[] = new Dnd\Bundle\AttributeDescriptionBundle\DndAttributeDescriptionBundle();
     

   • Override Akeneo’s Attribute and AttributeTranslation entities in app/config/config.yml:

     akeneo_storage_utils:
         mapping_overrides:
             -
                 original: Pim\Bundle\CatalogBundle\Entity\Attribute
                 override: Dnd\Bundle\AttributeDescriptionBundle\Entity\Attribute
             -
                 original: Pim\Bundle\CatalogBundle\Entity\AttributeTranslation
                 override: Dnd\Bundle\AttributeDescriptionBundle\Entity\AttributeTranslation
     

   • Run schema update:

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

2. First Use Case:

   • Navigate to Attributes in the Akeneo PIM UI.
   • Edit an existing attribute or create a new one.
   • A new "Descriptions" tab will appear—add localized descriptions (e.g., description-en_US) for each locale.

Implementation Patterns

Workflows

1. Manual Description Management:

   • Edit attributes via the Akeneo UI to add/edit descriptions per locale.
   • Descriptions render automatically under attribute values on product pages (e.g., for dropdowns, text fields).

2. Bulk Import/Export:

   • Import: Add description-{locale_code} columns (e.g., description-en_US) to your CSV/Excel attribute import file. Example:

     code,type,description-en_US,description-fr_FR
     color,select,Choose your shirt color,Choisissez la couleur de votre chemise
     

   • Export: Descriptions are included in standard Akeneo attribute exports (no extra config needed).

3. Localization Handling:

   • Descriptions are stored in AttributeTranslation entities, inheriting Akeneo’s localization system.
   • Use AttributeTranslationRepository to fetch descriptions programmatically:

     $description = $attributeTranslation->getDescription();
     

4. Frontend Integration:

   • Override Akeneo’s product templates (e.g., twig/product/_attribute.html.twig) to display descriptions:

     {% if attribute.description %}
         <div class="attribute-description">{{ attribute.description }}</div>
     {% endif %}
     

Integration Tips

• Custom Validation: Extend AttributeTranslation to add validation rules for descriptions (e.g., max length):

  use Symfony\Component\Validator\Constraints as Assert;
  
  /**
   * @Assert\Length(max=500)
   */
  private $description;
  

• API Extensions: Use Akeneo’s REST API to fetch descriptions via GET /api/rest/v1/attributes/{code} (descriptions included in response).
• Event Listeners: Hook into AttributeUpdateEvent to log or process description changes:

  public function onAttributeUpdate(AttributeUpdateEvent $event) {
      $attribute = $event->getAttribute();
      // Custom logic for descriptions...
  }
  

Gotchas and Tips

Pitfalls

1. Schema Mismatch:

   • Forgetting to run doctrine:schema:update after installation will cause errors when saving descriptions.
   • Fix: Always run the schema update command post-installation.

2. Locale-Specific Descriptions:

   • Descriptions are locale-bound. Omitting a locale’s description in imports will leave it null in the DB.
   • Tip: Use Akeneo’s default locale fallback or validate imports for missing descriptions.

3. Caching Issues:

   • Descriptions may not appear immediately due to Akeneo’s cache. Clear cache after bulk imports:

     php bin/console cache:clear
     

4. Attribute Type Limitations:

   • Descriptions are displayed under attribute values, not as standalone fields. For complex use cases (e.g., rich text), consider:
     • Using Akeneo’s text attribute type for descriptions.
     • Extending the bundle to support custom templates per attribute type.

Debugging

• Missing Descriptions in UI:
  • Verify the description-{locale_code} column exists in imports.
  • Check the database for attribute_translation.description values:

    SELECT * FROM attribute_translation WHERE locale = 'en_US';
    

• Frontend Rendering:
  • Ensure your Twig template overrides include the description logic. Debug with:

    {{ dump(attribute) }}
    

Extension Points

1. Custom Description Fields:

   • Extend AttributeTranslation to add metadata (e.g., isVisible, priority):

     /**
      * @ORM\Column(type="boolean")
      */
     private $isVisible = true;
     

   • Update the bundle’s AttributeTranslationType to expose these fields in the UI.

2. Dynamic Description Logic:

   • Override the bundle’s AttributeDescriptionRenderer service to conditionally show/hide descriptions:

     # config/services.yml
     services:
         dnd_attribute_description.renderer:
             class: AppBundle\Service\CustomAttributeDescriptionRenderer
             decorates: dnd_attribute_description.renderer
             arguments: ['@dnd_attribute_description.renderer.inner']
     

3. Import/Export Customization:

   • Subclass Dnd\Bundle\AttributeDescriptionBundle\Importer\AttributeImporter to add pre/post-processing for descriptions:

     public function process($currentStepResults, $stepExecution) {
         // Custom logic before/after description import
     }