JavaScript

Add interactivity and enhanced functionality with JavaScript.

Including JavaScript Files

In your template:

{% block body_javascript %}
    {{ parent() }}  {# Include default scripts #}

    {# Your theme scripts #}
    <script src="{{ asset('assets/theme/my-theme/js/main.js') }}"></script>
    <script src="{{ asset('assets/theme/my-theme/js/components/charts.js') }}"></script>
{% endblock %}

JavaScript Structure

// public/assets/theme/my-theme/js/main.js

(function() {
    'use strict';

    // Initialize when DOM is ready
    document.addEventListener('DOMContentLoaded', function() {
        console.log('Theme JavaScript loaded');

        initTheme();
        initComponents();
        initEventListeners();
    });

    function initTheme() {
        // Theme initialization logic
        loadUserPreferences();
        applyThemeSettings();
    }

    function initComponents() {
        // Initialize custom components
        initTooltips();
        initPopovers();
        initCharts();
    }

    function initEventListeners() {
        // Set up event listeners
        setupNavigationHandlers();
        setupFormValidation();
        setupAjaxHandlers();
    }

    // Export functions to global scope if needed
    window.MyTheme = {
        refresh: initTheme,
        notify: showNotification
    };
})();

Common JavaScript Patterns

AJAX Requests

function fetchServerStatus(serverId) {
    fetch(`/api/servers/${serverId}/status`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
        },
    })
    .then(response => response.json())
    .then(data => {
        updateServerCard(serverId, data);
    })
    .catch(error => {
        console.error('Error:', error);
        showErrorNotification('Failed to fetch server status');
    });
}

Event Delegation

// Instead of attaching to every button
document.addEventListener('click', function(e) {
    // Check if clicked element is a server action button
    if (e.target.matches('.server-action-btn')) {
        e.preventDefault();
        handleServerAction(e.target);
    }

    // Check for delete buttons
    if (e.target.matches('.delete-btn')) {
        e.preventDefault();
        confirmDelete(e.target);
    }
});

Form Validation

function validateForm(form) {
    const requiredFields = form.querySelectorAll('[required]');
    let isValid = true;

    requiredFields.forEach(field => {
        if (!field.value.trim()) {
            showFieldError(field, 'This field is required');
            isValid = false;
        } else {
            clearFieldError(field);
        }
    });

    return isValid;
}

form.addEventListener('submit', function(e) {
    if (!validateForm(this)) {
        e.preventDefault();
    }
});

Notifications

function showNotification(message, type = 'info') {
    const notification = document.createElement('div');
    notification.className = `alert alert-${type} alert-dismissible fade show`;
    notification.innerHTML = `
        ${message}
        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
    `;

    document.querySelector('.notification-container').appendChild(notification);

    // Auto-dismiss after 5 seconds
    setTimeout(() => {
        notification.remove();
    }, 5000);
}

Working with Bootstrap JavaScript

PteroCA includes Bootstrap. Use Bootstrap components:

// Tooltips
const tooltips = document.querySelectorAll('[data-bs-toggle="tooltip"]');
tooltips.forEach(el => new bootstrap.Tooltip(el));

// Popovers
const popovers = document.querySelectorAll('[data-bs-toggle="popover"]');
popovers.forEach(el => new bootstrap.Popover(el));

// Modals
const myModal = new bootstrap.Modal(document.getElementById('myModal'));
myModal.show();

// Toasts
const toast = new bootstrap.Toast(document.getElementById('myToast'));
toast.show();

Useful Patterns

Debouncing

Prevent excessive function calls:

function debounce(func, wait) {
    let timeout;
    return function executedFunction(...args) {
        const later = () => {
            clearTimeout(timeout);
            func(...args);
        };
        clearTimeout(timeout);
        timeout = setTimeout(later, wait);
    };
}

// Usage: search as user types, but not on every keystroke
const searchInput = document.getElementById('search');
searchInput.addEventListener('input', debounce(function(e) {
    performSearch(e.target.value);
}, 300));

Throttling

Limit function execution rate:

function throttle(func, limit) {
    let inThrottle;
    return function(...args) {
        if (!inThrottle) {
            func.apply(this, args);
            inThrottle = true;
            setTimeout(() => inThrottle = false, limit);
        }
    };
}

// Usage: handle scroll events efficiently
window.addEventListener('scroll', throttle(function() {
    handleScroll();
}, 100));

Local Storage

Persist user preferences:

// Save preference
function savePreference(key, value) {
    localStorage.setItem(key, JSON.stringify(value));
}

// Load preference
function loadPreference(key, defaultValue) {
    const saved = localStorage.getItem(key);
    return saved ? JSON.parse(saved) : defaultValue;
}

// Example: Save sidebar state
const sidebarCollapsed = loadPreference('sidebar-collapsed', false);
if (sidebarCollapsed) {
    document.body.classList.add('sidebar-collapsed');
}

Confirmation Dialogs

function confirmAction(message, callback) {
    if (confirm(message)) {
        callback();
    }
}

// Usage
deleteButton.addEventListener('click', function() {
    confirmAction('Are you sure you want to delete this item?', function() {
        deleteItem(itemId);
    });
});

Working with Forms

Dynamic Form Fields

// Add more input fields dynamically
function addFormField(container) {
    const newField = document.createElement('div');
    newField.className = 'form-field';
    newField.innerHTML = `
        <input type="text" class="form-control" name="items[]">
        <button type="button" class="btn btn-danger remove-field">Remove</button>
    `;
    container.appendChild(newField);
}

// Remove field
document.addEventListener('click', function(e) {
    if (e.target.matches('.remove-field')) {
        e.target.closest('.form-field').remove();
    }
});

AJAX Form Submission

form.addEventListener('submit', function(e) {
    e.preventDefault();

    const formData = new FormData(this);

    fetch(this.action, {
        method: 'POST',
        body: formData
    })
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            showNotification('Form submitted successfully!', 'success');
        } else {
            showNotification('Error: ' + data.message, 'danger');
        }
    })
    .catch(error => {
        showNotification('An error occurred', 'danger');
    });
});

Performance Optimization

Lazy Loading Images

// Lazy load images as they come into viewport
const images = document.querySelectorAll('img[data-src]');

const imageObserver = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            const img = entry.target;
            img.src = img.dataset.src;
            img.removeAttribute('data-src');
            imageObserver.unobserve(img);
        }
    });
});

images.forEach(img => imageObserver.observe(img));

Minimize DOM Manipulation

// ✗ Bad - multiple reflows
for (let i = 0; i < 100; i++) {
    container.innerHTML += '<div>Item ' + i + '</div>';
}

// ✓ Good - single DOM update
const fragment = document.createDocumentFragment();
for (let i = 0; i < 100; i++) {
    const div = document.createElement('div');
    div.textContent = 'Item ' + i;
    fragment.appendChild(div);
}
container.appendChild(fragment);

Best Practices

1. Use strict mode - 'use strict';

2. Avoid global variables - use IIFEs or modules

3. Handle errors gracefully - use try/catch and .catch()

4. Optimize performance - debounce/throttle event handlers

5. Make accessible - support keyboard navigation

6. Test across browsers - ensure compatibility

7. Minify for production - reduce file size

Debugging

Console methods:

console.log('Normal log');
console.error('Error message');
console.warn('Warning message');
console.table(arrayData);  // Display array as table
console.time('operation');
// ... code ...
console.timeEnd('operation');  // Measure execution time

Breakpoints:

// Add debugger statement to pause execution
debugger;

Browser DevTools:

• Use Console tab for output

• Use Sources tab for debugging

• Use Network tab for AJAX requests

• Use Performance tab for profiling

Related Guides

• Styling - CSS customization

• Twig Guide - Templating

• Testing - Quality assurance

• Theme Structure - File organization

External Resources

• MDN JavaScript Guide

• Bootstrap JavaScript Documentation

• Fetch API Documentation

• You Don't Know JS - In-depth JavaScript