Design Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require austral/design-bundle
   

   Ensure your config/bundles.php includes:

   Austral\DesignBundle\AustralDesignBundle::class => ['all' => true],
   

2. Publish Assets

   php bin/console assets:install
   npm run dev  # or `npm run build` for production
   

3. First Use Case: Basic Admin Layout Extend the base template in resources/views/layouts/admin.html.twig:

   {% extends 'AustralDesignBundle::base.html.twig' %}
   {% block title %}{{ parent() }} - My App{% endblock %}
   

4. Key Directories

   • Templates: vendor/austral/design-bundle/resources/views/
   • SCSS: vendor/austral/design-bundle/resources/assets/scss/
   • JavaScript: vendor/austral/design-bundle/resources/assets/js/

Implementation Patterns

1. Component Integration

Pattern: Use Twig components for reusable UI elements.

{# Button Component #}
<austral-button label="Save" icon="save" type="primary" />

Workflow:

1. Check available components in vendor/austral/design-bundle/resources/views/components/.
2. Override defaults by extending in your project’s templates/components/ directory.

2. Dynamic Theming

Pattern: Customize colors/fonts via SCSS variables.

// Override in resources/assets/scss/austral/_variables.scss
$primary-color: #2a5c8a;
$font-family: 'Inter', sans-serif;

Workflow:

1. Publish SCSS files:

   php bin/console assets:install --symlink
   

2. Extend _variables.scss before @import 'AustralDesignBundle/scss/austral';.

3. Form Integration

Pattern: Use Austral’s form components with Symfony forms.

{% form_theme form 'AustralDesignBundle:Form:theme.html.twig' %}

Key Features:

• VanillaJS form validation (no jQuery dependency).
• Custom templates for choice, textarea, and file fields.

4. Layout Extensions

Pattern: Modify admin layouts without forking.

{# resources/views/layouts/admin.html.twig #}
{% extends 'AustralDesignBundle::base.html.twig' %}

{% block sidebar %}
    {{ parent() }}
    <austral-collapse title="Custom Section">
        <div>Your content here</div>
    </austral-collapse>
{% endblock %}

5. JavaScript Integration

Pattern: Leverage Austral’s JS utilities.

// Example: Initialize a modal
document.querySelector('[data-austral-modal]').australModal();

Workflow:

1. Include Austral’s JS in your base template:

   {{ encore_entry_link_tags('app') }}  {# Ensure Encore processes Austral's JS #}
   

2. Use data attributes for components (e.g., data-austral-tooltip).

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Missing CSS/JS after composer require.
   • Fix: Run php bin/console assets:install and rebuild assets.
   • Tip: Use --symlink for development to avoid copying vendor files.

2. Twig Component Overrides

   • Issue: Custom components not loading.
   • Fix: Ensure your template paths take precedence. Check twig.config.path in config/packages/twig.php.

3. VanillaJS Dependencies

   • Issue: Uncaught ReferenceError for Austral JS methods.
   • Fix: Verify encore.js is loaded after Austral’s JS (check build order).

4. SCSS Conflicts

   • Issue: Styles overridden by Austral’s defaults.
   • Fix: Use !important sparingly; target specific classes (e.g., .your-class .austral-button).

5. Form Theme Conflicts

   • Issue: Symfony form themes not applying.
   • Fix: Explicitly set the theme in your controller:

     $form->setTheme([new \Twig_Theme('AustralDesignBundle:Form:theme.html.twig')]);
     

Debugging Tips

• Twig Debug: Enable in .env:

  APP_DEBUG=true
  

  Use {{ dump(_context) }} to inspect component data.

• Browser DevTools:

  • Check the "Elements" tab for overridden styles.
  • Audit the "Network" tab for missing assets (404s).

• Console Logs: Austral’s JS components log errors to console.error. Filter for austral: messages.

Extension Points

1. Custom Components

   • Create a new Twig component in templates/components/your_component.html.twig.
   • Register it in resources/views/base.html.twig:

     {% block austral_components %}
         {{ parent() }}
         {% include 'components/your_component.html.twig' %}
     {% endblock %}
     

2. SCSS Extensions

   • Add mixins/functions to resources/assets/scss/austral/_extensions.scss:

     @mixin your-mixin() {
         // ...
     }
     

   • Import after Austral’s variables:

     @import 'AustralDesignBundle/scss/austral';
     @import '~your-path/extensions';
     

3. JavaScript Plugins

   • Extend Austral’s JS by attaching to the austral namespace:

     austral.plugins = austral.plugins || {};
     austral.plugins.YourPlugin = function(element) {
         // Initialize logic
     };
     

   • Register in resources/js/app.js:

     import './austral-extensions';
     

4. Template Overrides

   • Override specific templates (e.g., collapse.html.twig) in templates/AustralDesignBundle/components/.

Performance Quirks

• Critical CSS: Austral’s SCSS is modular. Split into chunks for lazy loading:

  // encore.js
  Encore
      .addEntry('admin', './assets/js/admin.js')
      .splitEntry('admin', ['collapse', 'tabs']);
  

• PurgeCSS: Configure in postcss.config.js to remove unused Austral classes:

  module.exports = {
      plugins: [
          require('purgecss')({
              content: ['**/*.twig'],
              defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
          }),
      ],
  };
  

Version-Specific Notes

• v3.1.0+: Collapse/Tab components require data-austral-collapse attributes.

  <austral-collapse title="Section" data-austral-collapse>
      <!-- Content -->
  </austral-collapse>
  

• VanillaJS Migration: Replace jQuery calls with Austral’s document.querySelector methods. Example:

  // Before (jQuery)
  $('.austral-tooltip').tooltip();
  
  // After (VanillaJS)
  document.querySelectorAll('[data-austral-tooltip]').forEach(el => {
      new austral.Tooltip(el);
  });