Getting Started

Minimal Setup

Install the Package
```
composer require double-star-systems/symfony-material-theme
```
Ensure your composer.json includes the package under require.

Enable the Theme Bundle Add the bundle to your config/bundles.php:

return [
    // ...
    DoubleStarSystems\MaterialThemeBundle\MaterialThemeBundle::class => ['all' => true],
];

Install Assets Run from your project root:
```
php bin/console assets:install public
```
This copies Materialize CSS/JS to public/build/.
Configure Base Template Extend the theme’s base template (material_theme/base.html.twig) in your own template (e.g., templates/base.html.twig):
```
{% extends 'material_theme/base.html.twig' %}
```

First Use Case: Materialize Components Use Materialize components directly in Twig:

<div class="card blue-grey darken-1">
    <div class="card-content white-text">
        <span class="card-title">Hello Material!</span>
    </div>
</div>

Implementation Patterns

Workflows

Twig Integration
- Override partials (e.g., material_theme/partials/navbar.html.twig) in templates/material_theme/partials/.
- Use {% block material_theme_content %} to inject custom content into the theme’s layout.

Menu Integration (KnpMenuBundle) Configure menus in config/packages/knp_menu.yaml:

knp_menu:
    twig:
        template: material_theme/partials/menu.html.twig

Render menus in Twig:

{{ knp_menu('main', {'rootLink': {'route': 'home'} }) }}

Asset Management
- Customize assets by overriding files in public/build/ (e.g., public/build/css/materialize.css).
- Use Webpack Encore to extend/override JS/CSS if needed.

Responsive Design Leverage Materialize’s grid system (e.g., col s12 m6) in Twig:

<div class="row">
    <div class="col s12 m6">Column 1</div>
    <div class="col s12 m6">Column 2</div>
</div>

Dynamic Theming Pass variables to Twig to toggle classes (e.g., dark/light mode):

{% if is_dark_mode %}
    <body class="dark-mode">
{% else %}
    <body>
{% endif %}

Gotchas and Tips

Pitfalls

Asset Paths
- Forgetting to run assets:install after updates will break CSS/JS links.
- Fix: Add a post-update hook in composer.json:
```
"scripts": {
    "post-update-cmd": "php bin/console assets:install public"
}
```
KnpMenuBundle Dependency
- The theme assumes KnpMenuBundle is installed. If missing, menus will fail.
- Fix: Install the bundle first:
```
composer require knplabs/knp-menu-bundle
```
Twig Block Conflicts
- Overriding blocks (e.g., material_theme_content) without extending the parent template will break the layout.
- Fix: Always use {% extends 'material_theme/base.html.twig' %}.
Materialize JS Initialization
- Some Materialize components (e.g., modals, dropdowns) require JS initialization.
- Fix: Use the theme’s materialize_init.js or manually initialize:
```
document.addEventListener('DOMContentLoaded', function() {
    M.Modal.init(document.querySelectorAll('.modal'));
});
```
Caching Issues
- Twig cache may serve stale templates after theme updates.
- Fix: Clear cache:
```
php bin/console cache:clear
```

Tips

Custom SCSS Extend Materialize’s SCSS by overriding public/build/scss/materialize.scss and recompiling with Webpack Encore.
Lazy-Loading Defer non-critical JS (e.g., Materialize’s JS) to improve performance:
```
<script src="build/js/materialize.js" defer></script>
```

Dark Mode Use CSS variables for dynamic theming:

<style>
    :root {
        --primary-color: {{ primary_color|default('#6200ee') }};
    }
</style>

Debugging
- Check browser console for 404s on missing assets.
- Use Symfony’s profiler to inspect Twig template rendering.

Extending Components Create custom Twig components (e.g., templates/components/material_card.html.twig) and reuse them:

{% include 'components/material_card.html.twig' with {
    'title': 'Custom Card',
    'content': 'Dynamic content here'
} %}

Symfony Material Theme Laravel Package