> For the complete documentation index, see [llms.txt](https://docs.norrnext.com/norrcompetition/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.norrnext.com/norrcompetition/customisation/events.md).

# Events

NorrCompetition 3.0+ is built from the ground up using the modern **Joomla 5 Event Dispatcher** architecture. All component actions dispatch strongly typed event classes derived from `\NorrNext\Component\Competition\Administrator\Event\NcEvent` (for immutable events) or `\NorrNext\Component\Competition\Administrator\Event\NcMutableEvent` (for mutable events).

Third-party extensions and plugins can subscribe to these events to intercept lifecycles, validate actions, modify queries, mutate data, or integrate external systems (e.g., payment gateways, CRM, SMS/OTP channels, AI moderation).

***

## 🏛️ Architecture Overview

### Plugin Group

Custom plugins created specifically for NorrCompetition should use the **`competition`** plugin group (`plugins/competition/myplugin/`), although standard Joomla content plugins (`plugins/content/`) and system plugins (`plugins/system/`) can also subscribe to NorrCompetition events.

### Subscribing to Events (`SubscriberInterface`)

In Joomla 5, plugins implement `\Joomla\Event\SubscriberInterface` and map event names to method callbacks in `getSubscribedEvents()`:

```php
<?php

namespace MyCompany\Plugin\Competition\MyCustomRules\Extension;

\defined('_JEXEC') or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use NorrNext\Component\Competition\Administrator\Event\Participant\AllowedVotesEvent;
use NorrNext\Component\Competition\Administrator\Event\Model\BeforeSaveEvent;

final class MyCustomRules extends CMSPlugin implements SubscriberInterface
{
    /**
     * Maps subscribed event names or classes to handler methods.
     *
     * @return array<string, string>
     */
    public static function getSubscribedEvents(): array
    {
        return [
            'onParticipantAllowedCompetitionVotes' => 'onParticipantAllowedCompetitionVotes',
            'onParticipantBeforeSave'              => 'onParticipantBeforeSave',
        ];
    }

    public function onParticipantAllowedCompetitionVotes(AllowedVotesEvent $event): void
    {
        $context       = $event->getContext();
        $participantId = $event->getParticipantId();
        
        // Grant additional votes for VIP users
        $event->setArgument('allowedVotes', 5);
    }

    public function onParticipantBeforeSave(BeforeSaveEvent $event): bool
    {
        $context = $event->getContext();
        $table   = $event->getItem();
        $isNew   = $event->getIsNew();

        // Returning false cancels the save operation and rolls back the transaction
        return true;
    }
}
```

***

## 🎯 Event Types & Lifecycle

NorrCompetition uses three types of typed events:

1. **Immutable Events (`NcEvent`):** Read-only notification events fired after an action completes (e.g., status changes, notifications, display preparation).
2. **Mutable Events (`NcMutableEvent`):** Events where listeners can update properties (e.g., modifying redirect URLs, updating allowed vote quotas, altering tracking data, setting OTP channels).
3. **Cancellable Events (`ResultAwareInterface`):** Events that gate critical operations (`BeforeSave`, `BeforeDelete`, `BeforeTransactionCommit`). If any listener returns `false`, the operation is aborted and the active database transaction is rolled back.

***

## 📚 Event Categories

Explore the available events by area:

* [Content](/norrcompetition/customisation/events/content.md) — Form preparation and content plugin rendering events on entry views.
* [Contest](/norrcompetition/customisation/events/contest.md) — Contest lifecycle, display, save, delete, state, and automated status change events.
* [Entry](/norrcompetition/customisation/events/entry.md) — Participant entry lifecycle, approval workflows, voting frequency gates, vote limits, and state transitions.
* [Entry Form & Submission](/norrcompetition/customisation/events/entry-form.md) — Entry submission form lifecycle, custom field loading, and redirect handling.
* [Custom Fields](/norrcompetition/customisation/events/field.md) — Field lifecycle, saving, state changes, and deletion events.
* [Voting](/norrcompetition/customisation/events/vote.md) — Vote submission, unvoting, score calculation, browser fingerprinting/analytics, and modal dialog validation.
* [Other & Ecosystem](/norrcompetition/customisation/events/other.md) — Open Graph metadata, ACL overrides, OTP verification channels, image moderation, Flysystem remote storage, and points gating.