Hook: on_dashboard_top_boxes

The on_dashboard_top_boxes hook allows plugins to add custom dashboard boxes dynamically in the admin panel's top section. Each box can display statistics, links, or any other relevant data for the user.

Syntax

DynamicHooks::executeHook('on_dashboard_top_boxes', true);
    

Parameters

• Flatten: (bool) Optional. When set to true, results from all hooks are flattened into a single array. Default is true.

Returns

(array) An array of dashboard box data, where each element represents a box with the following attributes:

• id: (string) A unique identifier for the box.
• icon: (string) The icon class (e.g., fas fa-users) for the box.
• icon_background: (string) The background color class for the icon (e.g., bg-primary).
• value: (string) The main statistic or value to display in the box.
• subtitle: (string) A brief description or subtitle for the box.
• link: (string) A URL to redirect when the box is clicked.

Example Implementation

DynamicHooks::addHook('on_dashboard_top_boxes', function () use ($jakdb, $lang) {
    $totalUsers = $jakdb->count('users');
    $totalOrders = $jakdb->count('orders');
    
    return [
        [
            'id' => 'total_users_box',
            'icon' => 'fas fa-users',
            'icon_background' => 'bg-primary',
            'value' => $totalUsers,
            'subtitle' => $lang['total_users'],
            'link' => DynamicRewrite::parseUrl('users'),
        ],
        [
            'id' => 'total_orders_box',
            'icon' => 'fas fa-shopping-cart',
            'icon_background' => 'bg-success',
            'value' => $totalOrders,
            'subtitle' => $lang['total_orders'],
            'link' => DynamicRewrite::parseUrl('orders'),
        ]
    ];
}, 'my_plugin_namespace');
    

Best Practices

• Ensure each box has a unique id to avoid conflicts with other plugins.
• Use meaningful icons and subtitles to clearly convey the purpose of each box.
• Link the boxes to relevant management pages for better user experience.
• Test the hook implementation thoroughly to ensure compatibility with other plugins and the admin panel layout.

Common Issues

• Empty Boxes: Ensure the hook implementation returns valid data. Check for null or incorrect values in the returned array.
• Conflicting IDs: Use unique id values for your boxes to avoid overwriting or breaking other plugin boxes.
• Broken Links: Verify that the link attribute points to a valid and accessible URL.