Crudit Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require 2lenet/crudit-bundle
   npm install bootstrap@5 sass sass-loader @fortawesome/fontawesome-free easymde --save

2. Configure Webpack Encore:

   • Add {{ encore_entry_link_tags('app') }} to stylesheets block in base.html.twig.
   • Import Crudit SCSS in assets/styles/app.scss before importing Crudit’s own SCSS:

     @import '../../vendor/2lenet/crudit-bundle/assets/sb-admin/css/app.scss';
     

   • Ensure assets/js/app.js imports ../styles/app.scss.

3. Generate a CRUD:

   php bin/console make:crudit
   

   Answer prompts for entity, controller namespace, and filter creation.

4. Add to Menu: Register the CRUD in src/Crudit/CrudMenu/AppMenuProvider.php:

   LinkElement::new('menu.entity', Path::new('app_crudit_entity_index'))
   

First Use Case

• Navigate to /entity (auto-generated route).
• Use the List, Show, and Edit views out-of-the-box.
• Customize via EntityCrudConfig.php (e.g., sorting, fields, actions).

Implementation Patterns

Core Workflow

1. Define CRUD Structure:

   • Config: EntityCrudConfig.php (fields, sorting, actions).
   • Controller: Auto-generated EntityController.php (extend for custom logic).
   • Form: EntityType.php (Symfony form types + Crudit helpers).
   • Filters: EntityFilterSet.php (query constraints).

2. Field Customization:

   • Basic Field:

     Field::new('name', 'text')->setLabel('Full Name');
     

   • Progress Bar:

     Field::new('progress', ProgressBarField::class)
         ->setOptions(['barCssClass' => 'bg-success']);
     

   • Entity Dropdown:

     Field::new('category', EntityType::class, ['class' => Category::class])
         ->setAutocompleteUrl('app_category_autocomplete');
     

3. Actions:

   • List Actions (e.g., export, batch operations):

     ListAction::new('export', $this->getPath('export'), Icon::new('file-export'))
         ->setModal('@LleCrudit/modal/_export.html.twig');
     

   • Item Actions (e.g., edit, delete):

     ItemAction::new('edit', $this->getPath('edit'), Icon::new('edit'))
         ->setDisplayIf(fn(Resource $resource) => $resource->isActive());
     

4. Filters:

   • Extend EntityFilterSet and override applyFilters():

     public function applyFilters(QueryBuilder $qb, array $filters): void
     {
         if (isset($filters['active'])) {
             $qb->andWhere('e.active = :active')->setParameter('active', $filters['active']);
         }
     }
     

5. Sublists:

   • Define in getSublists():

     Sublist::new('orders', Order::class)
         ->setTitle('Related Orders')
         ->setConfig($this->getSublistConfig(Order::class));
     

6. Totals:

   • Add to getTotalFields():

     return [
         'total' => [
             'type' => CrudConfigInterface::SUM,
             'field' => Field::new('amount', 'currency'),
         ],
     ];
     

Integration Tips

• Doctrine ORM: Default datasource, but extendable to other providers.
• Security: Use setRole() on actions/fields:

  Field::new('adminField')->setRole('ROLE_ADMIN');
  

• Layout: Override Twig templates in templates/LleCrudit/ (e.g., _list.html.twig).
• Webpack: Rebuild assets after CSS/JS changes:

  npm run dev
  

Gotchas and Tips

Pitfalls

1. SCSS Order:

   • Critical: Import Crudit’s SCSS last in app.scss to avoid style overrides.
   • Fix: Move @import '../../vendor/2lenet/crudit-bundle/...' to the bottom.

2. Field Label Conflicts:

   • Crudit strips field. or label. prefixes from IDs in fieldsToUpdate().
   • Example: Field labeled field.status → use 'status' in fieldsToUpdate().
   • Fix: Use raw labels (e.g., 'text.status' → 'text.status').

3. Autocomplete Routes:

   • Missing Route: If DoctrineEntityField fails to autocomplete, ensure the route exists and is annotated:

     # config/routes.yaml
     app_entity_autocomplete:
         path: /entity/autocomplete
         controller: App\Controller\EntityAutocompleteController::index
     

4. Batch Actions:

   • CSRF Issues: Batch actions require CSRF tokens. Use Crudit’s modal templates:

     ->setModal('@LleCrudit/modal/_batch_action.html.twig')
     

5. Doctrine Query Builder:

   • Filter Conflicts: Ensure applyFilters() in FilterSet doesn’t break existing queries.
   • Debug: Dump the QueryBuilder:

     $qb->getQuery()->getSQL();
     

6. ProgressBarField:

   • Bootstrap Classes: Use valid Bootstrap classes (e.g., bg-success, bg-danger).
   • Validation: Ensure min/max values are integers.

7. Menu Registration:

   • Forgetting to Add: CRUDs won’t appear in the UI if not registered in AppMenuProvider.
   • Fix: Run make:crudit again or manually add the LinkElement.

8. Striped Tables:

   • SCSS Variable: Use Crudit’s prefix (e.g., --crudit-table-striped-bg).
   • Fix: Override in your app.scss:

     .crudit-list {
         > tbody > tr:nth-of-type(odd) {
             --crudit-table-accent-bg: #f8f9fa;
         }
     }
     

Debugging

1. Log Queries:

   • Enable Doctrine logging in config/packages/dev/doctrine.yaml:

     doctrine:
         dbal:
             logging: true
             logging_format: '%%timestamp%% %%sql%%'
     

2. Twig Debug:

   • Dump variables in templates:

     {{ dump(_context) }}
     

3. JavaScript Errors:

   • Check browser console for missing dependencies (e.g., easymde for Markdown).
   • Fix: Reinstall npm packages:

     rm -rf node_modules && npm install
     

Extension Points

1. Custom Form Types:

   • Extend CruditFormType or use Symfony’s AbstractType.
   • Example: Add a custom Select2Field:

     class Select2Field extends AbstractType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('field', Select2Type::class, $options);
         }
     }
     

2. Override Templates:

   • Copy vendor/2lenet/crudit-bundle/templates/ to templates/LleCrudit/ and modify.
   • Example: Customize the list header:

     {# templates/LleCrudit/_list_header.html.twig #}
     <div class="custom-header">
         {{ parent() }}
     </div>
     

3. Dynamic Actions:

   • Use setDisplayIf() for conditional actions:

     ->setDisplayIf(fn(Resource $resource) => $resource->getStatus() === 'published')
     

4. Custom Datasource:

   • Implement CruditDatasourceInterface for non-Doctrine data (e.g., API, CSV).
   • Example:

     class ApiDatasource implements CruditDatasourceInterface {
         public function getResults(FilterSetInterface $filterSet): array {
             return $this->apiClient->fetch($filterSet->getFilters());
         }
     }
     

5. Workflows:

   • Use CruditWorkflow to manage multi-step processes (e.g., approvals).
   • Example:

     $workflow = new CruditWorkflow();
     $workflow->addStep('review', 'Review', 'ROLE_REVIEWER');
     $workflow->addStep('approve', 'Approve', 'ROLE_ADMIN');
     

Performance Tips

1. Pagination:
   • Use setItemsPerPage() in `Cr