← Back to Awards Plugin

5.2.17 Awards Plugin Services

Last Updated: December 4, 2025
Status: Complete
Plugin: Awards

This section documents the service classes that support the Awards plugin’s integration with the main KMP application.

Overview

The Awards plugin provides several service classes that handle:

• Navigation Integration: Dynamic navigation items for award workflows
• View Cell Integration: Component rendering for member and award displays
• Workflow Support: Supporting services for recommendation processing

AwardsNavigationProvider

Provides comprehensive navigation integration for the Awards plugin with dynamic badge support and permission-based visibility.

Purpose

The AwardsNavigationProvider generates navigation items for:

• Award recommendation workflows
• Administrative configuration tools
• Reporting capabilities
• Status-based filtering

Navigation Architecture

The navigation provider implements structured navigation generation:

Feature	Description
Workflow Integration	Creates navigation items for recommendation workflows and approval processes
Dynamic Content	Generates navigation with real-time status information and queue counts
Plugin State Management	Checks plugin availability and generates appropriate navigation structure
Hierarchical Organization	Creates parent-child navigation relationships with merge path support

Navigation Categories

The provider generates navigation for multiple functional areas:

Recommendation Workflows

• Navigation for recommendation submission, approval, and management
• Status-based filtering for recommendation queues

Administrative Tools

• Access to configuration management
• Domain/level administration
• Awards setup

Configuration Management

• Award domains configuration
• Award levels configuration
• Awards configuration
• Event management

Generated Navigation Items

The provider creates the following navigation structure:

Label	Merge Path	Icon	Description
Award Recs.	(parent)	bi-patch-exclamation-fill	Parent navigation header
Recommendations	Award Recs.	bi-megaphone	Main recommendations list
Award Domains	Config	bi-compass	Domain configuration
Award Levels	Config	bi-ladder	Level configuration
Awards	Config	bi-award	Award configuration
Submit Award Rec.	Members	bi-megaphone-fill	Recommendation submission button

Additionally, dynamic navigation items are generated for each recommendation status (e.g., “Submitted”, “In Consideration”, “Need to Schedule”).

Method Reference

getNavigationItems()

Builds the Awards plugin navigation tree with static sections and per-status recommendation links.

public static function getNavigationItems(Member $user, array $params = []): array

Parameters:

Parameter	Type	Description
$user	Member	The current authenticated user
$params	array	Optional request parameters for contextual navigation

Returns: Array of navigation item arrays organized hierarchically, including static items and status-filtered recommendation links.

Navigation Item Structure

Each navigation item contains:

[
    "type" => "link",           // "link" or "parent"
    "mergePath" => [...],       // Hierarchical placement
    "label" => "...",           // Display text
    "order" => 30,              // Sort order
    "url" => [...],             // CakePHP URL array
    "icon" => "bi-*",           // Bootstrap Icon class
    "activePaths" => [...],     // Paths for active state detection
]

Plugin Availability

The navigation provider checks plugin availability before generating items:

if (StaticHelpers::pluginEnabled('Awards') == false) {
    return [];
}

This ensures navigation items only appear when the Awards plugin is properly enabled.

Integration Points

Service	Purpose
StaticHelpers	Plugin availability checking and configuration
Recommendation	Status definitions for dynamic navigation
Bootstrap Icons	Consistent icon usage
CakePHP URL Arrays	Route generation and active path detection

Related Documentation

• Awards Plugin Overview
• Extending KMP - Navigation
• Recommendation Policy
• Plugin Architecture

AwardsViewCellProvider

Provides view cell integration for the Awards plugin with route-based visibility and permission checking.

Purpose

The AwardsViewCellProvider manages view cell registration for:

• Member profile integration (submitted and received recommendations)
• Gathering activity integration (activity awards)
• Gathering views (gathering-level recommendations)

View Cell Architecture

The provider implements structured view cell registration:

Feature	Description
Context-Aware Registration	Registers view cells based on request context and user permissions
Route-Based Visibility	Configures view cells with specific route requirements
Permission Checking	Validates user permissions before registering cells
Plugin Integration	Coordinates with ViewCellRegistry for centralized management

Registered View Cells

Member Submitted Recs

Displays award recommendations submitted by a member.

Property	Value
Type	Tab
Label	“Submitted Award Recs.”
ID	member-submitted-recs
Cell	Awards.MemberSubmittedRecs
Order	3

Visibility Conditions:

• User is viewing their own profile, OR
• User is viewing their own member view page, OR
• User has ViewSubmittedByMember permission on Awards.Recommendations

Recs For Member

Displays award recommendations received by a member.

Property	Value
Type	Tab
Label	“Received Award Recs.”
ID	recs-for-member
Cell	Awards.RecsForMember
Order	4

Visibility Conditions:

• User is NOT viewing their own profile
• User is viewing another member’s view page
• User has ViewSubmittedForMember permission on Awards.Recommendations

Activity Awards

Displays awards that can be given during a gathering activity.

Property	Value
Type	Tab
Label	“Awards”
ID	activity-awards
Cell	Awards.ActivityAwards
Order	10

Visibility Conditions:

• User can view the gathering activity entity

Gathering Awards

Displays award recommendations associated with a gathering.

Property	Value
Type	Tab
Label	“Award Recommendations”
ID	gathering-awards
Cell	Awards.GatheringAwards
Order	8

Visibility Conditions:

• User has ViewGatheringRecommendations permission on Awards.Recommendations for the gathering

Method Reference

getViewCells()

Builds view cell configurations for the Awards plugin based on request context and user permissions.

public static function getViewCells(array $urlParams, $user = null): array

Parameters:

Parameter	Type	Description
$urlParams	array	Request URL parameters (controller, action, pass, etc.)
$user	mixed	Current authenticated user for permission checks

Returns: Array of view cell configuration arrays ready for registration with ViewCellRegistry.

View Cell Configuration Structure

Each view cell configuration contains:

[
    'type' => ViewCellRegistry::PLUGIN_TYPE_TAB,
    'label' => 'Tab Label',
    'id' => 'unique-id',
    'order' => 3,
    'tabBtnBadge' => null,
    'cell' => 'Awards.CellName',
    'validRoutes' => [
        ['controller' => 'ControllerName', 'action' => 'actionName', 'plugin' => null],
    ]
]

Integration Points

Service	Purpose
ViewCellRegistry	Centralized view cell management
StaticHelpers	Plugin availability checking
TableRegistry	Entity loading for permission checks

Error Handling

The provider implements graceful error handling:

• Returns empty array if user is not authenticated
• Returns empty array if Awards plugin is disabled
• Catches exceptions when loading entities for permission checks
• Logs errors for debugging without breaking the application

View Cells

The Awards plugin provides several view cells for integration with member profiles and gathering views.

ActivityAwardsCell

Displays awards that can be given during a specific gathering activity.

Purpose

Shows the reverse relationship of the Activities tab on Award views—displaying which awards are associated with a particular gathering activity type (e.g., Armored Combat, Archery).

Template Variables

Variable	Type	Description
gatheringActivity	Entity	The gathering activity entity
awards	ResultSet	Awards associated with this activity
canEdit	bool	Whether user can add/remove associations
availableAwards	array	Awards available to add (if canEdit)

Features

• Associated Awards: List of awards that can be given during this activity
• Award Details: Display of award names, descriptions, and hierarchical information
• Management Actions: Add/remove functionality for authorized users
• Empty State: Clear messaging when no awards are associated

Permission Checks

Permission	Effect
view on GatheringActivity	Required to see the cell content
edit on GatheringActivity	Enables add/remove award functionality

MemberSubmittedRecsCell

Displays award recommendations submitted by a specific member.

Purpose

Provides a dashboard view showing all recommendations a member has submitted, with submission tracking, status visualization, and member profile integration.

Template Variables

Variable	Type	Description
isEmpty	bool	Whether the member has submitted any recommendations
id	int	Member ID for URL construction and filtering

Features

• Submitted Recommendations: Display of award recommendations submitted by the member
• Status Tracking: Visual representation of recommendation workflow status
• Turbo Frame Integration: Lazy loading for performance optimization
• Action Button: Quick access to submit new award recommendations

Member ID Handling

ID Value	Behavior
-1	Resolves to current authenticated user’s ID
> 0	Uses the specified member ID

Permission Logic

Scenario	Access
Viewing own submissions	Always allowed
Viewing another member’s submissions	Requires ViewSubmittedByMember on Awards.Recommendations
Unauthorized access	Returns early with no display

Turbo Frame Integration

The cell uses Turbo Frames for dynamic content loading:

• Lazy Loading: Recommendations loaded asynchronously
• Dynamic Updates: Content updates without full page refresh
• URL Generation: Dynamic URL construction for filtered recommendation display

RecsForMemberCell

Displays award recommendations received by a specific member.

Purpose

Provides a view of recommendations that have been submitted about a member, with privacy protection to prevent members from viewing recommendations received about themselves through normal profile access.

Template Variables

Variable	Type	Description
isEmpty	bool	Whether the member has received any recommendations
id	int	Member ID for URL construction and filtering

Features

• Received Recommendations: Display of award recommendations submitted about the member
• Privacy Protection: Members cannot view recommendations received about themselves
• Administrative Oversight: Authorized users can view any member’s received recommendations
• Turbo Frame Integration: Lazy loading for performance optimization

Privacy and Relationship Logic

Scenario	Access
Viewing own received recommendations	Denied (privacy protection) unless has ViewSubmittedForMember permission
Viewing another member’s received recommendations	Allowed with ViewSubmittedForMember permission
Unauthorized access	Returns with empty state

Member ID Handling

ID Value	Behavior
-1	Resolves to current authenticated user’s ID
> 0	Uses the specified member ID

Security Considerations

• Self-Exclusion: Users cannot view recommendations received about themselves by default
• Permission Checking: Uses checkCan() method for authorization
• Data Scoping: Filters data by member_id to prevent unauthorized data access