Get Started

Easy Includes 2.0 adds custom CSS and JavaScript to your Joomla site without editing the template.

You can:

• Load CSS or JavaScript files from your site or a CDN
• Paste trusted inline CSS or JavaScript
• Choose Normal, Defer, or Async loading for scripts
• Add ES module, nomodule, crossorigin, and SRI options
• Skip selected user groups, components, or URL paths
• Turn any row on or off without deleting it

It works on Joomla 4, 5, and 6.

Honest note: inline JavaScript is trusted administrator input. Only people you trust should manage this plugin.

What you need

• Joomla 4, 5, or 6
• PHP 8.1 or newer (recommended)

Install the package

1. Download plg_system_easyincludes_2.0.zip.
2. In Joomla admin, open System > Install > Extensions.
3. Click Upload Package File.
4. Choose the ZIP file. Do not unzip it first.
5. Click Upload & Install.
6. Open System > Manage > Plugins.
7. Search for System - Easy Includes.
8. Configure the tabs, set Status to Enabled, and Save.
9. Open System > Clear Cache and clear all cache.
10. Test the public site in a private/incognito window.

Upgrading from 1.5

Your existing file and inline rows are kept. Open the plugin once, review Script Loading and Advanced options, then Save. Old Body load-position values map to Defer automatically.

Open the Files tab. Click Add for each CSS or JavaScript file.

• Enabled (default: Yes): turn this row on or off without deleting it.
• File Type (default: CSS): CSS or JavaScript.
• File Path or URL (required): a site-relative path such as templates/cassiopeia/css/custom.css, or a full https:// CDN URL. Protocol-relative //cdn... URLs are allowed. Paths with .., null bytes, or schemes like javascript: / data: are rejected.
• Script Loading (JavaScript only, default: Normal):
  • Normal: register the script with no defer/async
  • Defer: run after HTML parsing finishes (best when order matters)
  • Async: download in parallel and run when ready (order may change)
• ES Module (type=module) (JavaScript only, default: No): sets type="module".
• Nomodule Fallback (JavaScript only, default: No): adds the nomodule attribute for older browsers.
• Crossorigin (JavaScript only, default: None): None, anonymous, or use-credentials. Often used with SRI on CDN scripts.
• Integrity (SRI) (JavaScript only): optional hash such as sha384-.... Invalid hashes are ignored.
• CSS Media (CSS only, default: All): All, Screen, Print, or Custom query.
• Custom Media Query (when Media is Custom): example (max-width: 768px).
• Load Priority (default: 0): higher numbers are registered first.

Tip: start with one local CSS file and Cache Busting set to Auto, then add scripts after the styles work.

Open the Inline Code tab for small trusted snippets. Click Add for each block.

• Enabled (default: Yes): on/off without deleting the row.
• Code Type (default: CSS): CSS or JavaScript.
• Code (required): paste the snippet. JavaScript is trusted admin input and is not HTML-filtered.
• CSS Media (CSS only, default: All): All, Screen, Print, or Custom query.
• Custom Media Query (when Media is Custom): example (min-width: 992px).
• Load Priority (default: 0): higher numbers first.

Inline CSS safety

Inline CSS is skipped when it contains closing </style tags, CSS expressions, behavior bindings, or dangerous @import patterns. Fix the CSS and save again.

Use inline JavaScript only for short trusted fixes. Prefer file or CDN scripts for libraries.

Open the Advanced tab for global behaviour.

• Cache Busting (default: Off):
  • Off: no version query string
  • Auto (file change time): uses the local file modification time when the file exists; otherwise uses Web Asset Manager auto versioning. Best for production after you edit local files.
  • Aggressive (every request): adds a new timestamp on every page load. Use only while testing.
• Enable in Administrator (default: No): also load these assets in the Joomla admin area. Leave No for front-end only.
• Debug Logging (default: No): write skipped exclusions and failed rows to the Joomla log while troubleshooting.

Legacy 1.5 Yes/No cache busting upgrades cleanly: old Yes becomes Auto.

Open the Exclusions tab. If any exclusion matches the current request, Easy Includes loads nothing on that page.

• Exclude User Groups: selected groups do not receive the files or inline code. Guest/Public handling follows Joomla guest group mapping.
• Exclude Components: one component option per line, for example com_users or com_content.
• Exclude URL Paths: one path fragment per line. If the live URL path or query contains the fragment, assets are skipped. Example: /checkout or task=edit.

Lines that start with # are treated as comments and ignored.

Example: exclude Super Users and add /checkout so checkout pages stay free of custom scripts.

Complete parameter map for Easy Includes 2.0:

Files (repeatable row)

• Enabled
• File Type
• File Path or URL
• Script Loading
• ES Module (type=module)
• Nomodule Fallback
• Crossorigin
• Integrity (SRI)
• CSS Media
• Custom Media Query
• Load Priority

Inline Code (repeatable row)

• Enabled
• Code Type
• Code
• CSS Media
• Custom Media Query
• Load Priority

Advanced

• Cache Busting
• Enable in Administrator
• Debug Logging

Exclusions

• Exclude User Groups
• Exclude Components
• Exclude URL Paths

Recipe A: Site custom CSS

1. Files > Add
2. Enabled: Yes
3. File Type: CSS
4. Path: your custom CSS relative path
5. CSS Media: All
6. Advanced > Cache Busting: Auto
7. Enable in Administrator: No
8. Save, clear cache, hard refresh

Recipe B: CDN library with Defer

1. Files > Add
2. File Type: JavaScript
3. Path: full https URL
4. Script Loading: Defer
5. Optional: Crossorigin anonymous + Integrity hash
6. Save and test

Recipe C: Small inline CSS fix

1. Inline Code > Add
2. Code Type: CSS
3. Paste a short CSS rule (no style tags)
4. Media: All or Custom query
5. Save

Recipe D: Skip checkout and Super Users

1. Exclusions > Exclude User Groups: Super Users
2. Exclude URL Paths: /checkout
3. Save and test as guest and as Super User

Recipe E: ES module script

1. Files > Add
2. File Type: JavaScript
3. Path: your module file or CDN URL
4. ES Module: Yes
5. Script Loading: Normal or Defer as needed
6. Save

Basic checks first

1. Clear Joomla cache: System > Clear Cache.
2. Hard refresh the page (Ctrl+F5 or Cmd+Shift+R).
3. Confirm System - Easy Includes is Enabled.
4. Confirm the row Enabled switch is Yes.
5. Turn on Debug Logging and check System logs if needed.
6. Test in a private/incognito window.

• Nothing loads at all

  • Check Exclusions for groups, components, and URL fragments.
  • Confirm you are testing the front end while Enable in Administrator is No.
  • Confirm File Path or Code is not empty.

• 404 for a local file

  • Use a path relative to the site root, without ...
  • Confirm the file exists on disk.
  • Try without a leading slash if your host is picky.

• CDN script does not run

  • Use a full https URL.
  • If Integrity is set, confirm the hash matches the file exactly.
  • Try Crossorigin anonymous when the CDN requires CORS for SRI.

• Script order looks wrong

  • Async can run out of order. Prefer Defer when order matters.
  • Raise Load Priority for libraries that must register first.

• Changes do not appear

  • Set Cache Busting to Auto, clear cache, and hard refresh.
  • Aggressive mode is only for short testing sessions.

• Inline CSS is ignored

  • Remove closing style tags and forbidden CSS patterns, then save again.

• Inline JavaScript feels too open

  • Limit plugin edit permission to trusted admins. Prefer file/CDN scripts for shared libraries.

• Assets appear in the admin by mistake

  • Set Enable in Administrator to No.

• Excluded group still sees assets

  • Confirm you are logged in as a member of that group.
  • For guests, include the Public/Guest group mapping and retest logged out.

• URL exclusion does nothing

  • Use a fragment that appears in the live path or query, such as /checkout.
  • Do not rely on the full domain name alone.

• Component exclusion does nothing

  • Use the option name exactly, for example com_content, one per line.

• Custom media query never applies

  • Set CSS Media to Custom and fill Custom Media Query.
  • Use a valid query such as (max-width: 768px).

• After upgrading from 1.5

  • Open and save the plugin once.
  • Review Script Loading. Old Body values become Defer. Conditional comments are removed.

• Old behaviour remains

  • Clear Joomla, CDN/proxy, and browser caches after updating.

• Which Joomla versions are supported?

  • Joomla 4, 5, and 6. PHP 8.1 or later is recommended.

• Do I need to edit my template?

  • No. Configure System - Easy Includes and clear cache.

• Defer or Async: which should a beginner choose?

  • Start with Defer when the script should wait for the page HTML. Use Async only when order does not matter.

• Which cache mode should I use live?

  • Off or Auto. Keep Aggressive for testing only.

• Can visitors add JavaScript?

  • No. Only Joomla administrators with plugin access can configure it.

• Does it load in the administrator?

  • Not by default. Turn on Enable in Administrator only when you intend that.

• Where do I get help?

  • Visit support.joomlax.com. Send your Joomla version, PHP version, plugin settings, page URL, and any log notes when Debug Logging is on.

Docs: joomlax.com/documentation/easy-includes