Ezplatform Content Forms Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ezsystems/ezplatform-content-forms
   

   Ensure you have Ibexa DXP installed as a dependency.

2. Enable the Bundle: Add to config/bundles.php:

   Ibexa\ContentForms\EzPlatformContentFormsBundle\EzPlatformContentFormsBundle::class => ['all' => true],
   

3. First Use Case: Create a custom form type for a content type. Example:

   // src/Form/Type/MyContentTypeFormType.php
   namespace App\Form\Type;
   
   use Ibexa\ContentForms\EzPlatformContentFormsBundle\Form\Type\ContentTypeFormType;
   use Symfony\Component\Form\AbstractType;
   
   class MyContentTypeFormType extends AbstractType
   {
       public function getParent()
       {
           return ContentTypeFormType::class;
       }
   
       public function configureOptions(\Symfony\Component\OptionsResolver\OptionsResolver $resolver)
       {
           $resolver->setDefaults([
               'content_type' => 'my_content_type_identifier',
           ]);
       }
   }
   

4. Routing: Use the built-in routes for content editing (e.g., /content/edit/{contentId}). Configure in config/routes.yaml:

   ezplatform_content_forms:
       resource: "@EzPlatformContentFormsBundle/Resources/config/routing.yml"
   

5. Twig Integration: Extend templates in templates/bundles/EzPlatformContentForms/ to customize rendering.

Implementation Patterns

Core Workflows

1. Content Creation/Editing

• Form Type Inheritance: Extend ContentTypeFormType or UserTypeFormType to customize fields:

  class CustomArticleFormType extends ContentTypeFormType
  {
      public function buildForm(\Symfony\Component\Form\FormBuilderInterface $builder, array $options)
      {
          $builder->add('custom_field', TextType::class);
      }
  }
  

• Field Mapping: Use field_map option to override default field handling:

  $resolver->setDefaults([
      'field_map' => [
          'title' => 'custom_title_field',
      ],
  ]);
  

2. Validation and Submission

• Custom Validation: Add constraints to form fields:

  $builder->add('price', MoneyType::class, [
      'constraints' => [
          new NotBlank(),
          new Positive(),
      ],
  ]);
  

• Submit Handling: Override submit() in your form type to add logic:

  public function submit(\Symfony\Component\Form\FormInterface $form, \Ibexa\Contracts\Core\Repository\Values\Content\Content $content)
  {
      $data = $form->getData();
      // Custom logic (e.g., pre-save transformations)
      parent::submit($form, $content);
  }
  

3. Multi-Language Support

• Translatable Fields: Use TranslatableFieldType for multi-language fields:

  $builder->add('description', TranslatableFieldType::class, [
      'field_definition_identifier' => 'description',
  ]);
  

• Language Switching: Leverage the built-in language selector in templates or via JavaScript.

4. User Management Forms

• User Creation/Editing: Extend UserTypeFormType:

  class CustomUserFormType extends UserTypeFormType
  {
      public function buildForm(\Symfony\Component\Form\FormBuilderInterface $builder, array $options)
      {
          $builder->add('department', EntityType::class, [
              'class' => Department::class,
          ]);
      }
  }
  

5. Field-Specific Customizations

• Image Uploads: Customize ImageFieldType:

  $builder->add('image', ImageFieldType::class, [
      'required' => true,
      'config' => [
          'upload_dir' => '%kernel.project_dir%/public/uploads',
      ],
  ]);
  

• Date/Time Fields: Use DateFieldType or DateTimeFieldType with timezone support:

  $builder->add('event_date', DateTimeFieldType::class, [
      'widget' => 'single_text',
      'input' => 'datetime',
      'with_timezone' => true,
  ]);
  

6. Integration with Ibexa Services

• Content Service: Inject ContentService to fetch/save content:

  public function __construct(
      private ContentService $contentService
  ) {}
  
  public function saveContent(Content $content)
  {
      $this->contentService->saveContent($content);
  }
  

• Location Service: Handle content placement:

  $location = $this->locationService->createLocation($content, $parentLocation);
  

7. Custom Templates

• Override Twig templates in templates/bundles/EzPlatformContentForms/:
  • content/edit.html.twig
  • user/edit.html.twig
• Extend blocks like ez_content_form_row for field-specific styling.

8. API-Driven Forms

• Use FormFactory to dynamically generate forms:

  $form = $this->formFactory->createNamedBuilder(
      'dynamic_form',
      ContentTypeFormType::class,
      $content,
      [
          'content_type' => $contentTypeIdentifier,
          'field_map' => $customFieldMap,
      ]
  );
  

Integration Tips

Symfony Integration

• Dependency Injection: Use ezplatform_content_forms.form.factory service to create forms programmatically.
• Event Listeners: Attach listeners to ezplatform_content_forms.form.pre_submit or ezplatform_content_forms.form.post_submit events.

Ibexa-Specific Tips

• Content Type Dependencies: Ensure your form type’s content_type option matches an existing Ibexa content type identifier.
• Field Definition Identifiers: Use the correct field_definition_identifier for each field (check Ibexa’s FieldDefinition repository).
• Permissions: Validate user permissions before form submission (e.g., ContentService::hasAccess()).

Performance

• Lazy Loading: Load content/fields lazily in form builders to avoid N+1 queries.
• Caching: Cache form definitions if used frequently (e.g., in admin panels).

Gotchas and Tips

Pitfalls

1. Field Mapping Mismatches

• Issue: Form fields not saving due to incorrect field_definition_identifier.
• Fix: Verify identifiers in Ibexa’s FieldDefinition repository:

  $fieldDef = $this->fieldDefinitionService->loadFieldDefinition($identifier);
  

• Debug Tip: Enable ezplatform_content_forms.debug in config to log field mapping issues.

2. Translatable Field Handling

• Issue: Non-translatable fields appearing in language-specific tabs or vice versa.
• Fix: Explicitly set translatable option in field_map:

  'field_map' => [
      'title' => [
          'field_definition_identifier' => 'title',
          'translatable' => false,
      ],
  ],
  

• Bug Reference: IBX-6495 (v1.3.16).

3. Content ID/Version Casting

• Issue: contentId or versionNo not casting to integers, causing errors.
• Fix: Ensure types are cast in form submissions (fixed in v1.3.17).

4. Autosave Conflicts

• Issue: Autosave interfering with manual submissions in nodraft mode.
• Fix: Disable autosave for specific routes or use ezplatform_content_forms.autosave.enabled = false in config.

5. Multiple Locations

• Issue: Forms failing for content with multiple locations.
• Fix: Ensure LocationService is used to handle location-specific logic (fixed in v1.3.12).

6. Date/Time Zone Offsets

• Issue: Incorrect timezone handling in ezdate fields.
• Fix: Set with_timezone: true and ensure server timezone matches expectations (fixed in v1.3.13).

7. **Empty