# Joomla Frontend Integration

> Frontend integration (CSS/JS) in Joomla 5/6 with Helix Framework. WebAssetManager, Bootstrap 5, SP Page Builder, responsive design, and Web Components.

- Skill: `nicolasflores9/joomla-frontend-integration` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add nicolasflores9/joomla-frontend-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nicolasflores9/joomla-frontend-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nicolasflores9 (https://skillmd.com/u/nicolasflores9)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nicolasflores9/joomla-frontend-integration

---


# Frontend Integration in Joomla 5/6 with Helix Framework

Comprehensive guide to mastering CSS/JavaScript, WebAssetManager, and responsive design in Joomla 5/6 using Helix Framework and Bootstrap 5.

---

## 1. WebAssetManager: The Modern System

The **WebAssetManager** (`\Joomla\CMS\WebAsset\WebAssetManager`) is the official way to manage assets in Joomla 5/6. It replaces HTMLHelper and Document API (deprecated in 5.3+).

### Lifecycle
1. **Registered**: Asset declared in `joomla.asset.json`
2. **Used**: Activated with `$wa->useScript()` or `$wa->useStyle()`
3. **Rendered**: Inserted into HTML by `<jdoc:include type="head" />`
4. **Loaded**: Downloaded by browser with automatic versioning

### Getting an Instance
```php
$wa = \Joomla\CMS\Factory::getApplication()
      ->getDocument()
      ->getWebAssetManager();

// Load assets
$wa->useScript('jquery');
$wa->useStyle('bootstrap');
```

### Loading Levels in Joomla
```
1. media/vendor/joomla.asset.json
2. media/system/joomla.asset.json
3. media/legacy/joomla.asset.json
4. media/com_active/joomla.asset.json
5. templates/active_template/joomla.asset.json
```

---

## 2. joomla.asset.json Structure

JSON file that declares all assets in a centralized way. It is loaded automatically.

### Basic Structure
```json
{
  "$schema": "https://json.schemastore.org/joomla-manifest-schema.json",
  "name": "myext",
  "version": "1.0.0",
  "assets": [
    {
      "name": "my-script",
      "type": "script",
      "uri": "js/myfile.js",
      "dependencies": ["jquery"],
      "attributes": {
        "defer": true,
        "async": false
      },
      "version": "auto"
    },
    {
      "name": "my-style",
      "type": "style",
      "uri": "css/myfile.css",
      "dependencies": [],
      "version": "auto"
    }
  ]
}
```

### Locations by Type
- **Module**: `/mod_mymod/joomla.asset.json`
- **Component**: `/com_mycomp/joomla.asset.json`
- **Plugin**: `/plg_group_name/joomla.asset.json`
- **Template**: `/templates/mytemplate/joomla.asset.json`

### Automatic Versioning
```json
"version": "auto"  // Uses last modification date
"version": "1.0.0" // Manual version
```

---

## 3. Loading CSS and JavaScript Correctly

### Method 1: WebAssetManager (RECOMMENDED)
```php
// In helper.php, layout, or component
$wa = \Joomla\CMS\Factory::getApplication()
      ->getDocument()
      ->getWebAssetManager();

// Scripts
$wa->useScript('jquery');
$wa->useScript('bootstrap');
$wa->useScript('my-custom-script');

// Styles
$wa->useStyle('bootstrap');
$wa->useStyle('my-custom-style');
```

### Alternatives (Dynamic, CDN, Legacy)
```php
// Register dynamically
$wa->registerAndUseScript('my-dynamic', 'js/dynamic.js',
    ['dependencies' => ['jquery']], ['defer' => true]);

// From CDN in joomla.asset.json
{"name": "lib", "type": "script",
 "uri": "https://cdn.example.com/lib.min.js"}

// Legacy (avoid)
\Joomla\CMS\HTML\HTMLHelper::script('js/file.js');
```

---

## 4. Bootstrap 5 with Helix Framework

Helix includes **Bootstrap 5.2.3+** automatically. 12-column grid, flexbox, utilities.

### Responsive Grid
```html
<!-- Integrated Bootstrap grid -->
<div class="container">
  <div class="row">
    <div class="col-12 col-md-6 col-lg-4">
      <!-- Content: 100% mobile, 50% tablet, 33% desktop -->
    </div>
  </div>
</div>
```

### Bootstrap Breakpoints
```css
/* xs: 0px (mobile first) */
/* sm: 576px (landscape phones) */
/* md: 768px (tablets) */
/* lg: 992px (desktops) */
/* xl: 1200px (large desktops) */
/* xxl: 1400px (very large) */
```

### Media Queries
```css
/* Mobile first: base styles for mobile */
.card {
  padding: 1rem;
  font-size: 14px;
}

/* Enhance for tablets */
@media (min-width: 768px) {
  .card {
    padding: 2rem;
    font-size: 16px;
  }
}

/* Enhance for desktops */
@media (min-width: 992px) {
  .card {
    padding: 3rem;
    font-size: 18px;
  }
}
```

### Do Not Break Bootstrap
```css
/* INCORRECT: overriding Bootstrap classes */
.btn { background: red; }

/* CORRECT: create custom classes */
.btn-custom { background: red; }
.btn-custom:hover { background: darkred; }
```

---

## 5. Custom Modules with Assets

**Structure:**
```
/mod_mymodule/
  ├── joomla.asset.json
  ├── helper.php
  ├── mod_mymodule.php
  ├── tmpl/default.php
  ├── js/module.js
  └── css/module.css
```

**Activate in helper.php or template:**
```php
$wa = \Joomla\CMS\Factory::getApplication()
      ->getDocument()
      ->getWebAssetManager();
$wa->useScript('mod_mymodule.script');
$wa->useStyle('mod_mymodule.style');
```

See complete example in `references/02-modulo-testimonios-completo.php`.

---

## 6. SP Page Builder: Assets in Addons

**Native CSS:** Row/Column > Custom CSS (CodeMirror editor available).

**Custom JS:** Create a sppagebuilder type plugin (native JS not supported).

See complete example in `references/06-sp-page-builder-addon-plugin.php`.

---

## 7. Dependencies Between Assets

Automatic load order resolution system.

### Simple Dependency
```json
{
  "name": "my-plugin",
  "type": "script",
  "uri": "js/plugin.js",
  "dependencies": ["jquery"]
}
```

### Multiple Dependencies
```json
{
  "name": "advanced-plugin",
  "type": "script",
  "uri": "js/advanced.js",
  "dependencies": [
    "jquery",
    "bootstrap.util",
    "popper"
  ]
}
```

### Dependency with Specific Type
```json
{
  "name": "my-component",
  "type": "script",
  "uri": "js/component.js",
  "dependencies": [
    "jquery#script",
    "bootstrap.util#script",
    "theme-dark#style"
  ]
}
```

### Preset (Dependency Group)
```json
{
  "name": "admin-bundle",
  "type": "preset",
  "uri": "",
  "dependencies": [
    "jquery#script",
    "popper#script",
    "bootstrap#script",
    "bootstrap#style"
  ]
}
```

---

## 8. Inline Scripts and Styles

For small or dynamic code.

### Inline Script
```php
$wa = Factory::getApplication()
      ->getDocument()
      ->getWebAssetManager();

$wa->addInlineScript('
  document.addEventListener("DOMContentLoaded", function() {
    console.log("Inline script executed");
  });
');
```

### Inline Style
```php
$wa->addInlineStyle('
  .banner-custom {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    padding: 20px;
  }
');
```

### Named Inline (as a Dependency)
```php
$wa->registerAndUseScript(
    'my-init',
    'document.addEventListener("DOMContentLoaded", function() { /* init */ });'
);

// Use as a dependency
$wa->registerAndUseScript(
    'my-app',
    'js/app.js',
    ['dependencies' => ['my-init']]
);
```

---

## 9. Defer, Async, and Optimization

Critical attributes for performance.

### Defer
Executes AFTER HTML is loaded. **Recommended for most cases.**

```json
{
  "name": "my-script",
  "type": "script",
  "uri": "js/my-script.js",
  "attributes": {
    "defer": true,
    "async": false
  }
}
```

**Use for:**
- jQuery
- Bootstrap
- Custom scripts that depend on jQuery

### Async
Executes WHEN ready. **For independent code.**

```json
{
  "name": "analytics",
  "type": "script",
  "uri": "https://analytics.example.com/track.js",
  "attributes": {
    "defer": false,
    "async": true
  }
}
```

**Use for:**
- Google Analytics
- Tracking scripts
- Chat widgets
- Independent code

### Decision Matrix
```
jQuery / Bootstrap          -> defer: true, async: false
Custom JS that uses jQuery  -> defer: true, async: false
Analytics / Tracking        -> defer: false, async: true
3rd party widget            -> async: true
```

---

## 10. Web Components

Native W3C standard. Joomla includes `joomla-core-loader`.

```javascript
// Create Web Component
class MyComponent extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<div>${this.getAttribute('title')}</div>`;
  }
}
customElements.define('my-component', MyComponent);

// Register in joomla.asset.json
// {"name": "my-comp", "type": "script", "uri": "js/my-comp.js",
//  "attributes": {"type": "module", "defer": true}}
```

See complete example in `references/07-web-component-custom.js`.

---

## 11. Custom Code in Helix

Admin > Templates > [Your Template] > Template Options > Custom Code tab.

**Global CSS:**
```css
.site-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
.custom-button {
  padding: 12px 24px;
  border-radius: 4px;
  transition: all 0.3s ease;
}
```

**Global JS & Google Fonts:** See examples in `references/08-template-helix-custom.css` and `references/10-ejemplos-codigo-rapido.md`.

---

## 12. Best Practices: Do Not Break Helix

### NEVER Edit
```
/template/css/template.css        X
/template/css/bootstrap.css        X
/template/js/template.js           X
```

### ALWAYS Create/Use
```
/template/css/custom.css           OK
/template/scss/custom.scss         OK
/template/js/custom.js             OK
Custom Code section in admin       OK
```

### Safe CSS Cascade
```css
/* template.css loads first */
.btn { padding: 8px 12px; }

/* custom.css loads last - has priority */
.btn { padding: 10px 16px; }
```

### Preserve Bootstrap Classes
```css
/* INCORRECT: modifies Bootstrap class */
.btn { background: purple; }

/* CORRECT: creates custom class */
.btn-primary-custom { background: purple; }

<!-- Use custom class -->
<button class="btn btn-primary-custom">Button</button>
```

---

## 13. Quick Troubleshooting

**Assets not loading:** Check `<jdoc:include type="head" />` in template, path in joomla.asset.json, permissions (755), Joomla cache.

**Incorrect order:** Verify dependencies, check Network tab in DevTools.

**Bootstrap not working:** Confirm `$wa->useStyle('bootstrap')`, do not override variables, use classes correctly.

**Helix breaks:** Do not edit core files, use custom.css, check Custom Code.

More details in `references/09-checklist-desarrollo.md`.

---

## 14. Quick References and Resources

See `references/09-checklist-desarrollo.md` and `references/10-ejemplos-codigo-rapido.md` for detailed guides and additional examples.