Assets

Include frontend assets to customize your plugin's appearance and behavior.

Declaring Assets

In plugin.json:

{
    "assets": {
        "css": [
            "css/styles.css",
            "css/admin.css"
        ],
        "js": [
            "js/script.js",
            "js/admin.js"
        ],
        "img": [
            "images/logo.svg",
            "images/icon.png"
        ]
    }
}

Asset Directory Structure

plugins/my-plugin/
└── assets/
    ├── css/
    │   ├── styles.css
    │   └── admin.css
    ├── js/
    │   ├── script.js
    │   └── admin.js
    └── images/
        ├── logo.svg
        └── icon.png

Publishing Assets

Assets are automatically published when plugin is enabled:

php bin/console pteroca:plugin:enable my-plugin

Manual republish:

php bin/console pteroca:plugin:assets:publish my-plugin

Force republish (overwrites existing):

php bin/console pteroca:plugin:assets:publish my-plugin --force

Using Assets in Templates

{# CSS #}
<link rel="stylesheet" href="{{ plugin_asset('my-plugin', 'css/styles.css') }}">

{# JavaScript #}
<script src="{{ plugin_asset('my-plugin', 'js/script.js') }}"></script>

{# Images #}
<img src="{{ plugin_asset('my-plugin', 'images/logo.svg') }}" alt="Logo">

Example CSS

/* assets/css/styles.css */
.my-plugin-container {
    padding: 20px;
    background: #f8f9fa;
    border-radius: 8px;
}

.my-plugin-widget {
    border: 1px solid #dee2e6;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.my-plugin-button {
    background: #007bff;
    color: white;
    padding: 10px 20px;
    border: none;
    border-radius: 4px;
    cursor: pointer;
}

.my-plugin-button:hover {
    background: #0056b3;
}

Example JavaScript

// assets/js/script.js
(function() {
    'use strict';

    // Wait for DOM ready
    document.addEventListener('DOMContentLoaded', function() {
        console.log('My Plugin JS loaded');

        // Initialize plugin functionality
        initMyPlugin();
    });

    function initMyPlugin() {
        const buttons = document.querySelectorAll('.my-plugin-button');

        buttons.forEach(function(button) {
            button.addEventListener('click', function(e) {
                e.preventDefault();
                handleButtonClick(this);
            });
        });
    }

    function handleButtonClick(button) {
        const action = button.dataset.action;

        fetch(`/plugins/my-plugin/api/${action}`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
        })
        .then(response => response.json())
        .then(data => {
            console.log('Success:', data);
            showNotification('Action completed successfully', 'success');
        })
        .catch(error => {
            console.error('Error:', error);
            showNotification('Action failed', 'error');
        });
    }

    function showNotification(message, type) {
        // Display notification to user
        alert(message);
    }
})();

Modern JavaScript (ES6+)

// assets/js/modern.js
class MyPluginWidget {
    constructor(element) {
        this.element = element;
        this.apiUrl = '/plugins/my-plugin/api';
        this.init();
    }

    init() {
        this.bindEvents();
        this.loadData();
    }

    bindEvents() {
        this.element.addEventListener('click', (e) => {
            if (e.target.matches('.action-button')) {
                this.handleAction(e.target.dataset.action);
            }
        });
    }

    async loadData() {
        try {
            const response = await fetch(`${this.apiUrl}/data`);
            const data = await response.json();
            this.renderData(data);
        } catch (error) {
            console.error('Failed to load data:', error);
        }
    }

    async handleAction(action) {
        try {
            const response = await fetch(`${this.apiUrl}/${action}`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
            });

            const result = await response.json();
            this.showSuccess(result.message);
        } catch (error) {
            this.showError('Action failed');
        }
    }

    renderData(data) {
        // Render data to DOM
        this.element.innerHTML = data.items
            .map(item => `<div class="item">${item.name}</div>`)
            .join('');
    }

    showSuccess(message) {
        // Show success notification
    }

    showError(message) {
        // Show error notification
    }
}

// Initialize all widgets
document.addEventListener('DOMContentLoaded', () => {
    document.querySelectorAll('.my-plugin-widget').forEach(widget => {
        new MyPluginWidget(widget);
    });
});

CSS Best Practices

1. Prefix your classes with plugin name:

.my-plugin-container { }
.my-plugin-button { }
.my-plugin-widget { }

1. Don't modify global styles:

/* BAD - affects entire site */
.card { border: 2px solid red; }

/* GOOD - scoped to plugin */
.my-plugin-card { border: 2px solid red; }

1. Use consistent spacing:

.my-plugin-container {
    padding: 20px;
    margin: 10px 0;
}

1. Responsive design:

.my-plugin-widget {
    width: 100%;
}

@media (min-width: 768px) {
    .my-plugin-widget {
        width: 50%;
    }
}

JavaScript Best Practices

1. Use IIFE to avoid global pollution:

(function() {
    'use strict';
    // Your code here
})();

1. Wait for DOM ready:

document.addEventListener('DOMContentLoaded', function() {
    // Initialize code
});

1. Handle async operations:

async function loadData() {
    try {
        const response = await fetch('/api/data');
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Failed:', error);
        return null;
    }
}

1. Event delegation:

// Good - single listener
document.addEventListener('click', (e) => {
    if (e.target.matches('.my-button')) {
        handleClick(e.target);
    }
});

// Bad - multiple listeners
document.querySelectorAll('.my-button').forEach(button => {
    button.addEventListener('click', handleClick);
});

Asset Optimization

For production:

1. Minify CSS and JavaScript

2. Optimize images (compress, use appropriate formats)

3. Use CDNs for common libraries

4. Bundle assets if using multiple files

5. Cache busting with versioned filenames

Loading External Libraries

If you need external libraries (jQuery, etc.):

Option 1: CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>

Option 2: Composer dependency Add to plugin's composer.json and include in your asset bundle.

Option 3: Bundle with plugin Include library file in assets/js/vendor/ and declare in plugin.json.

Asset Path in Plugin

Published assets location:

Source: plugins/my-plugin/assets/css/styles.css
Published: public/assets/plugins/my-plugin/css/styles.css
URL: /assets/plugins/my-plugin/css/styles.css

Related Guides

• Plugin Manifest - Declare assets

• UI Components - Style widgets and tabs

• Translations - Multi-language JavaScript