Contao Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require contao-components/contao
   

   Publish the assets (if needed) via:

   php artisan vendor:publish --tag=contao-assets
   

2. First Use Case Include the CSS in your Laravel app by adding the following to your resources/views/layouts/app.blade.php (or equivalent):

   <link href="{{ asset('vendor/contao/css/contao.css') }}" rel="stylesheet">
   

   Start using Contao’s utility classes in your Blade templates:

   <div class="container">
       <button class="btn btn-primary">Click Me</button>
       <p class="text-center">Centered text</p>
   </div>
   

3. Where to Look First

   • Documentation: Check the Contao CSS Framework docs (if available) or inspect the published CSS file at public/vendor/contao/css/contao.css.
   • Source: Explore the package’s resources/css directory (if published) for customization hooks.
   • Laravel Mix: If extending, configure webpack.mix.js to process Contao’s SCSS (if applicable).

Implementation Patterns

1. Utility-First Workflow

• Atomic Classes: Leverage Contao’s utility classes (e.g., margin-top-1, text-bold) for rapid UI development.

  <div class="margin-top-2 margin-bottom-1">
      <h2 class="text-bold text-primary">Heading</h2>
  </div>
  

• Responsive Design: Use responsive modifiers (e.g., hidden-xs, visible-sm-up):

  <div class="hidden-xs">Visible on sm+</div>
  

2. Integration with Laravel Blade

• Dynamic Classes: Use Blade directives to toggle classes:

  <button class="btn @if($isPrimary) btn-primary @else btn-secondary @endif">
      Action
  </button>
  

• Component-Based Layouts: Pair with Laravel’s Blade components for reusable templates:

  <x-card class="bg-light shadow-sm">
      <x-slot name="title">Card Title</x-slot>
      <p>Content here.</p>
  </x-card>
  

3. Customization via SASS

• Extend Variables: If the package includes SASS, override variables in resources/sass/app.scss:

  $primary-color: #3498db; // Override Contao’s default
  @import 'vendor/contao/css/contao';
  

• Compile with Laravel Mix:

  mix.sass('resources/sass/app.scss', 'public/css');
  

4. Form Integration

• Style forms using Contao’s form classes:

  <form>
      <input type="text" class="input input-lg" placeholder="Name">
      <button type="submit" class="btn btn-success">Submit</button>
  </form>
  

• Pair with Laravel’s Form Helper for consistency:

  {!! Form::text('email', null, ['class' => 'input']) !!}
  

5. Dark Mode Support

• Use Contao’s dark-mode classes (if available) with Laravel’s theme switching:

  <div class="dark-mode @if($darkMode) active @endif">
      <!-- Content -->
  </div>
  

Gotchas and Tips

Pitfalls

1. CSS Specificity Conflicts

   • Contao’s utility classes may conflict with Laravel’s default Bootstrap (if used). Use !important sparingly or scope Contao classes:

     .contao-utils .btn { /* Override */ }
     

   • Fix: Load Contao CSS after other frameworks in your layout.

2. Missing Documentation

   • The package lacks official Laravel integration docs. Rely on:
     • Contao’s CSS Framework docs.
     • Inspect the published CSS file for class names.

3. No JavaScript Bundle

   • Contao is CSS-only. If you need JS (e.g., modals), pair it with Alpine.js or Laravel’s built-in JS.

4. Responsive Breakpoints

   • Contao’s breakpoints may differ from Bootstrap’s. Test responsiveness on all devices.

Debugging Tips

• Inspect Elements: Use browser dev tools to verify class application.
• Disable Caching: Clear Laravel’s config/cache during development:

  php artisan config:clear
  php artisan cache:clear
  

• Check Published Assets: Ensure CSS is published to public/vendor/contao/css/.

Extension Points

1. Custom SCSS Variables

   • Extend Contao’s theme variables in resources/sass/app.scss:

     // Override Contao’s colors
     $primary-color: #20c997;
     $secondary-color: #6f42c1;
     @import 'vendor/contao/css/contao';
     

2. Laravel Mix Aliases

   • Add Contao to your Mix config for easier imports:

     mix.webpackConfig({
         resolve: {
             alias: {
                 contao: path.resolve(__dirname, 'vendor/contao-components/contao/resources/css')
             }
         }
     });
     

3. Tailwind-like Directives

   • Create Blade directives for dynamic class generation:

     // app/Providers/BladeServiceProvider.php
     Blade::directive('contao', function ($expression) {
         return "class=\"{$expression}\"";
     });
     

     Usage:

     <div @contao('container margin-top-3')>...</div>
     

4. Contao + Livewire

   • Style Livewire components with Contao classes:

     <x-livewire:component class="card bg-white p-4" />
     

Performance Tips

• Purge Unused CSS: Use Laravel Mix’s PurgeCSS to remove unused Contao classes:

  mix.postCss('resources/css/app.css', 'public/css', [
      require('postcss-import'),
      require('tailwindcss'),
      require('autoprefixer'),
      require('postcss-purgecss')({
          content: ['app/**/*.blade.php', 'resources/**/*.js']
      })
  ]);
  

• Critical CSS: Inline critical Contao classes above-the-fold for faster renders.