PROJECT HANDOVER · GPLR.NET · OCTOBER 2026

NX Content

A reusable, shortcode-driven component system for Joomla 6.

Under construction Working prototype PHP templates SCSS / CSS

Purpose: development reference, recovery notes and continuity between working sessions.

1. Project objective

NX Content is a Joomla content plugin designed to make article authoring easier for clients who should supply content without having to build HTML structures or manage complex layouts.

The author inserts a simple shortcode into an article. NX Content selects the appropriate PHP component template, supplies its attributes as variables, loads the component stylesheet and returns the rendered HTML.

Core principle

Clients manage content. The developer controls structure, design, responsive behaviour, animations and styling.

The plugin is being developed for GPLR.NET, but the intention is to make it reusable on other Joomla websites.

2. Current shortcode syntax

Hero component

{nxcontent hero style="retro"
    img="images/example.jpg"
    alt="Formula Ford"
    title="MARRS"
    tag="FORMULA FORD"
    subtitle="Built for speed"
    subtitle2="Designed to be remembered"
}

The component type is hero. The selected style is retro, which maps to the Retro PHP template.

Card component

{nxcontent card style="featured"
    img="images/example.jpg"
    alt="Race car"
    tag="FORMULA FORD"
    title="MARRS"
    text="Built for speed."
}

The Card component uses its own templates and stylesheets, independently of Hero.

Legacy alias

The original concept also considered supporting {gplr ...} as an alias for {nxcontent ...}. Treat that as a separate compatibility requirement unless it has been implemented and tested in the current plugin version. The canonical syntax is {nxcontent ...}.

3. Component architecture

The current approach uses PHP templates stored inside the plugin. The following shows the intended working organisation; verify the actual server tree before replacing or moving files.

plugins/content/nxcontent/
├── nxcontent.xml
├── services/
│   └── provider.php
└── src/
    ├── Extension/
    │   └── Nxcontent.php
    └── Components/
        ├── Hero/
        │   ├── Blueprint.php
        │   ├── Cinematic.php
        │   ├── Mars.php
        │   ├── Retro.php
        │   ├── Terminal.php
        │   └── css/
        │       ├── blueprint.scss
        │       ├── blueprint.css
        │       ├── cinematic.scss
        │       ├── cinematic.css
        │       ├── mars.scss
        │       ├── mars.css
        │       ├── retro.scss
        │       ├── retro.css
        │       ├── terminal.scss
        │       └── terminal.css
        └── Card/
            ├── Featured.php
            └── css/
                ├── featured.scss
                └── featured.css

Important: this is a reference layout, not a verified file listing. Preserve the existing working directory structure if it differs.

4. PHP template conventions

Templates use ordinary PHP output syntax:

<section class="hero-retro">
    <div class="hero-retro__image">
        <img src="/<?= $img ?>" alt="<?= $alt ?>">
    </div>

    <div class="hero-retro__content">
        <h1><?= $title ?></h1>
        <p><?= $subtitle ?><br><?= $subtitle2 ?></p>
        <span><?= $status ?? 'READY' ?></span>
    </div>
</section>

Dynamic attributes

Attributes supplied in the shortcode are exposed as template variables. For example, subtitle2 becomes $subtitle2, and gravity becomes $gravity.

The renderer was updated to inspect the selected PHP template for variables written in the form <?= $variable ?> and initialise referenced variables to empty strings before including the template. This avoids undefined-variable warnings for omitted attributes.

Do not revert to a scanner that searches for {$variable}; that is not the template syntax used by this project.

Inline defaults

<?= $status ?? 'READY' ?>
<?= $number ?? '01' ?>
<?= $subtitle ?? '' ?>

Templates may supply their own sensible defaults. Keep escaping enabled for shortcode-supplied values. If a template needs intentional HTML rather than plain text, introduce an explicit, carefully controlled mechanism rather than disabling escaping globally.

5. Adding a component type

The Card prototype was added by extending the dispatch logic in src/Extension/Nxcontent.php.

Dispatcher

return match ($type) {
    'hero' => $this->renderHero($attributes),
    'card' => $this->renderCard($attributes),
    default => $this->renderUnknown($type),
};

The prototype uses a dedicated renderCard() method, following the existing Hero rendering approach. A generic component renderer was discussed as a future refactor, but should not be assumed to exist yet.

Card files

Components/Card/Featured.php
Components/Card/css/featured.scss
Components/Card/css/featured.css

The Card template uses the same attribute-variable convention as Hero. Its stylesheet is loaded through the component CSS loader.

6. Component styles and Sass workflow

Decision: preserve the existing SCSS workflow.

  • SCSS lives beside its component, inside its css/ subfolder.
  • The existing Sass generator compiles CSS alongside the SCSS source.
  • NX Content loads the compiled CSS for the selected component style.
  • Do not relocate assets into Joomla's media/ directory merely for convention's sake.

The CSS loader currently uses a public URL under the plugin path, following this general pattern:

plugins/content/nxcontent/src/Components/Hero/css/retro.css

The loader should check the corresponding filesystem path, register the stylesheet with Joomla's Web Asset Manager, and avoid registering the same style repeatedly during a request.

Production consideration: public accessibility of files under src/ varies by hosting configuration. If assets are moved to a public media directory later, update the manifest, filesystem paths and asset URLs together. This is not a reason to change the working Sass setup today.

7. Existing Hero designs

Style Template Design direction
Blueprint Blueprint.php Technical engineering drawing, model specifications and crosshairs.
Cinematic Cinematic.php Atmospheric image, vignette, strong title and editorial presentation.
Mars Mars.php Science-fiction surface telemetry, status indicators and mission details.
Retro Retro.php Vintage motorsport print styling, badge, number and registration.
Terminal Terminal.php Computer-terminal interface, system status and telemetry.

These are existing design concepts supplied during development. The actual appearance and behaviour depend on the current template and compiled CSS files.

8. Joomla integration and known pitfalls

  • Plugin namespace: the extension class has been expected at NX\Plugin\Content\Nxcontent\Extension\Nxcontent.
  • Class loading: the namespace, manifest configuration, service provider and actual class path must agree. Do not guess at a namespace fix on the live site.
  • Client context: the plugin should check the Joomla application context safely before processing site content.
  • Content preparation: the plugin subscribes to onContentPrepare and replaces recognised shortcodes in article text.
  • Attribute parsing: quoted values can contain spaces. Preserve the working parser when making unrelated changes.
  • Unknown styles: the current approach falls back to Retro if a requested Hero template is unavailable.
  • Missing attributes: initialise variables referenced by the PHP template to prevent warnings.
  • CSS loading: ensure the generated URL matches the real deployed file and that Joomla can serve it.
Recovery rule

During earlier development, a namespace/class-loading error caused a Category/Index rendering failure, followed by an application-context error. The site was recovered. Make a backup before modifying the extension, and test changes on staging wherever possible.

9. Current status

Working prototype

  • Hero shortcodes render their selected PHP templates.
  • Shortcode attributes become template variables.
  • Missing template variables are intended to default to empty strings.
  • Component CSS is loaded by style through the existing loader.
  • A Card component has been added using a dedicated template and stylesheet.
  • The site recovered from earlier plugin class-loading errors.

Not yet confirmed

  • Whether every Hero style has been tested with missing and optional attributes.
  • Whether Card and Hero share a fully generic renderer. The recorded prototype still uses dedicated rendering methods.
  • Whether the legacy {gplr ...} alias is implemented.
  • Whether all CSS assets are accessible on every intended hosting configuration.
  • Whether the installation ZIP includes every new component and stylesheet.

10. Recommended next steps

  1. Back up the known-working plugin files and installation ZIP.
  2. Confirm the current production file tree and retain it as the source of truth.
  3. Test Hero and Card shortcodes with missing attributes, quotes and special characters.
  4. Confirm that multiple different component styles load their respective CSS without duplicates.
  5. Test the plugin in Joomla article, category and other relevant rendering contexts.
  6. Decide whether to refactor the duplicated Hero/Card renderer into a generic component dispatcher.
  7. Verify the plugin manifest and package contents so newly created components survive installation and updates.
  8. Keep a changelog of working changes and known issues.

11. Working conventions

  • Keep answers and code changes practical; avoid re-explaining the architecture unless requested.
  • Do not replace whole working files when a small targeted change is sufficient.
  • Distinguish implemented features from suggestions.
  • Preserve the existing SCSS compilation workflow.
  • Use {nxcontent ...} as the canonical shortcode syntax.
  • Do not make assumptions about the live filesystem. Ask for the current file when exact implementation details matter.
  • Keep NX Content separate from other projects, including the NX PhotoSwipe fix.

12. Resume prompt

When reopening this project in a future session, provide this document and use the following instruction:

Resume NX Content development.

Read this handover before proposing changes. NX Content is a Joomla 6 content plugin using shortcodes such as {nxcontent hero style="retro" ...}, PHP component templates, dynamic attribute variables and component-specific CSS compiled from SCSS. Hero and Card prototypes exist. Preserve the current working implementation and existing Sass workflow. Confirm the actual files before making targeted code changes, and do not confuse planned improvements with implemented features. Continue from the current project state rather than rebuilding the architecture.