## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require ibexa/twig-components

Requires Ibexa DXP (or a compatible Twig environment). For Laravel, pair with spatie/laravel-twig.

First Use Case: Render a basic table with CMS content (or Eloquent data):

{% use 'ibexa:table.html.twig' %}
{{ ibexa.table({
    'data': contentList,
    'columns': [
        { 'label': 'Title', 'property': 'title' },
        { 'label': 'Date', 'property': 'publish_date' }
    ]
}) }}

Where to Look First:
- Source: resources/views/components/table.html.twig (for template structure).
- Config: Check config/ibexa.php (if Ibexa DXP is installed) for default settings.
- Extensions: Override defaults via Twig extensions (see Implementation Patterns).

Implementation Patterns

Core Workflows

Data Binding:

CMS Content: Pass Ibexa Content objects or Location collections directly.
```
{{ ibexa.table({ data: locations, columns: [...] }) }}
```

Eloquent Models: Wrap in a Twig extension to normalize data:

// app/Extensions/TableDataExtension.php
public function getTableData($data) {
    return array_map(fn($item) => [
        'title' => $item->name,
        'date' => $item->created_at->format('Y-m-d')
    ], $data);
}

{% set tableData = this.getTableData(posts) %}
{{ ibexa.table({ data: tableData, columns: [...] }) }}

Column Customization:

Dynamic Columns: Use Twig loops to define columns:

{% set columns = [] %}
{% for field in content.fields %}
    {% set columns = columns|merge([{
        'label': field.name,
        'property': 'value.' ~ field.identifier
    }]) %}
{% endfor %}
{{ ibexa.table({ data: contentList, columns: columns }) }}

Custom Renderers: Extend via Twig filters:

{{ column.value|ibexa_table_cell_renderer }}

Pagination/Sorting:
- Integrate with Laravel’s pagination:
```
{{ ibexa.table({
    data: posts->paginate(10),
    columns: [...],
    pagination: true
}) }}
```
- Override sorting logic via Twig extensions.

Styling:

SCSS Overrides: Extend the base stylesheet:

// resources/scss/ibexa/_table.scss
.ibexa-table {
  --table-border-color: #333;
}

Tailwind: Use arbitrary variants:

{{ ibexa.table({ data: [...], class: 'table-auto border-collapse' }) }}

Integration Tips

Laravel Service Provider: Register Twig extensions in AppServiceProvider:

public function boot() {
    $this->loadViewsFrom(__DIR__.'/../vendor/ibexa/twig-components/src/Resources/views', 'ibexa');
    $this->app['twig']->addExtension(new IbexaTableExtension());
}

Blade-Twig Interop: Render Twig components in Blade:

// app/Helpers/TwigHelper.php
public static function renderTwigComponent($view, $data) {
    return \Twig\Environment::create()->render($view, $data);
}

@php echo \App\Helpers\TwigHelper::renderTwigComponent('ibexa:table.html.twig', $tableData) @endphp

API Data: Normalize API responses before passing to the table:

$tableData = array_map(function($item) {
    return [
        'id' => $item['id'],
        'name' => $item['attributes']['name'],
    ];
}, $apiResponse);

Gotchas and Tips

Pitfalls

Twig Dependency:
- Issue: The package assumes Twig is configured. Laravel’s default Blade templating won’t work without a bridge.
- Fix: Use spatie/laravel-twig or render Twig components via PHP helpers (as shown above).

CMS-Specific Assumptions:

Issue: Components like ibexa.Table expect Ibexa Content objects or Location collections. Passing raw arrays may break.

Fix: Normalize data in a Twig extension or Laravel service:

public function normalizeTableData($data) {
    return array_map(function($item) {
        return [
            'title' => $item->getField('title')->value,
            'date' => $item->getField('publish_date')->value,
        ];
    }, $data);
}

Styling Conflicts:
- Issue: Default styles may clash with Tailwind/Bootstrap.
- Fix: Override variables in your SCSS:
```
.ibexa-table {
  --table-bg-color: theme('colors.white');
  --table-header-bg: theme('colors.gray.100');
}
```

Pagination Quirks:

Issue: The pagination option may not work out-of-the-box with Laravel’s paginator.

Fix: Extend the component’s Twig template to handle Illuminate\Pagination\LengthAwarePaginator:

{% if data instanceof Illuminate\Pagination\LengthAwarePaginator %}
    {% set pagination = {
        'total': data->total(),
        'perPage': data->perPage(),
        'currentPage': data->currentPage(),
        'lastPage': data->lastPage()
    } %}
{% endif %}

Missing Bundles Exception Handling:
- Issue: In v5.0.9, the package now throws exceptions if required Ibexa bundles are missing, which may cause unexpected errors during development.
- Fix: Ensure all required Ibexa bundles are installed and properly configured. Check for clear error messages indicating which bundle is missing and install it via Composer:
```
composer require ibexa/core-bundle
```
- Debugging: If you encounter exceptions during development, verify your composer.json includes all necessary Ibexa dependencies and run composer install or composer update.

Debugging Tips

Template Overrides:
- Override the base template in resources/views/components/ibexa/table.html.twig to debug rendering issues.

Data Validation:

Use dump() in Twig to inspect passed data:

{% dump(data) %}
{{ ibexa.table({ data: data, columns: columns }) }}

Extension Debugging:

Check if extensions are registered:

$this->app['twig']->getExtension('ibexa_table')->getFunctions();

Extension Points

Custom Components:
- Extend the package by creating new Twig components in app/Resources/views/components/ibexa/.
- Example: Add a Card component by copying the table structure.

Twig Extensions:

Add custom logic via extensions:

// app/Extensions/CustomTableExtension.php
class CustomTableExtension extends \Twig\Extension\AbstractExtension {
    public function getFunctions() {
        return [
            new \Twig\TwigFunction('custom_table_cell', [$this, 'renderCell']),
        ];
    }

    public function renderCell($value, $type) {
        // Custom rendering logic
        return "<span class='{$type}'>{$value}</span>";
    }
}

{{ column.value|custom_table_cell('highlight') }}

Configuration:
- Override defaults via config/ibexa.php (if Ibexa DXP is installed) or environment variables:
```
'table' => [
    'default_columns' => [
        ['label' => 'ID', 'property' => 'id'],
    ],
],
```

JavaScript Integration:

Attach events via Twig’s attr filter:

<button {{ attr({'class': 'ibexa-table-sort', 'data-sort': column.property}) }}>
    {{ column.label }}
</button>

Listen in your JS:

document.querySelectorAll('.ibexa-table-sort').forEach

Twig Components Laravel Package