claude-plugins/perfex-dev/skills/perfex-menus/SKILL.md

name, description, author, version, quality_score, user_invocable, desk_task

name	description	author	version	quality_score	user_invocable	desk_task
perfex-menus	Perfex CRM menu creation. Sidebar menus, client menus, add_sidebar_menu_item(), positions, icons. Based on official documentation only. Use when user mentions "perfex menu", "sidebar perfex", "menu item", "navigation perfex".	Descomplicar® Crescimento Digital	1.0.0	70	true	null

/perfex-menus - Menus Perfex CRM

Criação de menus para módulos. Zero assumptions, zero hallucinations - apenas documentação oficial.

---

Documentação Base

• Create Menu Items

---

Menu Admin (Sidebar)

Adicionar Item Simples

// No init file do módulo
hooks()->add_action('admin_init', 'meu_modulo_init_menu');

function meu_modulo_init_menu()
{
    $CI = &get_instance();

    $CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
        'name'     => _l('meu_modulo_title'),
        'href'     => admin_url('meu_modulo'),
        'position' => 25,
        'icon'     => 'fa fa-cube',
    ]);
}

Parâmetros

Parâmetro	Tipo	Descrição
name	string	Texto do menu (usar _l() para tradução)
href	string	URL destino
position	int	Posição no menu (menor = mais acima)
icon	string	Classe Font Awesome
collapse	bool	Se tem sub-items (default: false)
badge	array	Badge com contagem

---

Menu com Sub-Items (Collapsible)

hooks()->add_action('admin_init', 'meu_modulo_init_menu');

function meu_modulo_init_menu()
{
    $CI = &get_instance();

    // Menu pai (collapsible)
    $CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
        'name'     => _l('meu_modulo_title'),
        'collapse' => true,
        'position' => 25,
        'icon'     => 'fa fa-cube',
    ]);

    // Sub-item 1
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-lista',
        'name'     => _l('list'),
        'href'     => admin_url('meu_modulo'),
        'position' => 1,
        'icon'     => 'fa fa-list',
    ]);

    // Sub-item 2
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-criar',
        'name'     => _l('create'),
        'href'     => admin_url('meu_modulo/create'),
        'position' => 2,
        'icon'     => 'fa fa-plus',
    ]);

    // Sub-item 3
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-settings',
        'name'     => _l('settings'),
        'href'     => admin_url('meu_modulo/settings'),
        'position' => 3,
        'icon'     => 'fa fa-cog',
    ]);
}

---

Posições Padrão Admin

Posição	Menu Item
1	Dashboard
5	Customers
10	Sales
15	Subscriptions
20	Expenses
25	Contracts
30	Projects
35	Tasks
40	Tickets
45	Leads
50	Knowledge Base
55	Utilities
60	Reports

Dica: Usar posições intermédias (ex: 27, 32) para inserir entre items existentes.

---

Badge (Contador)

$CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
    'name'     => _l('meu_modulo_title'),
    'href'     => admin_url('meu_modulo'),
    'position' => 25,
    'icon'     => 'fa fa-cube',
    'badge'    => [
        'value'      => meu_modulo_count_pending(),
        'type'       => 'danger',    // primary, success, warning, danger, info
        'show_on_sidebar' => true,
    ],
]);

// Função de contagem
function meu_modulo_count_pending()
{
    $CI = &get_instance();
    $CI->db->where('status', 'pending');
    return $CI->db->count_all_results(db_prefix() . 'meu_modulo');
}

---

Menu Condicional (Permissões)

function meu_modulo_init_menu()
{
    // Só mostrar se staff tem permissão
    if (!staff_can('view', 'meu_modulo')) {
        return;
    }

    $CI = &get_instance();

    $CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
        'name'     => _l('meu_modulo_title'),
        'href'     => admin_url('meu_modulo'),
        'position' => 25,
        'icon'     => 'fa fa-cube',
    ]);
}

---

Menu Cliente (Área Cliente)

Adicionar Item

hooks()->add_action('clients_init', 'meu_modulo_client_menu');

function meu_modulo_client_menu()
{
    // Só mostrar se cliente logado
    if (!is_client_logged_in()) {
        return;
    }

    add_theme_menu_item('meu-modulo', [
        'name'     => _l('meu_modulo_title'),
        'href'     => site_url('meu_modulo'),
        'position' => 35,
        'icon'     => 'fa fa-cube',
    ]);
}

Posições Padrão Cliente

Posição	Menu Item
5	Knowledge Base
10	Projects
15	Invoices
20	Contracts
25	Estimates
30	Proposals
40	Subscriptions
45	Support
99	Registration
100	Login

---

Menu no Setup (Administração)

Para adicionar configurações ao menu Setup:

hooks()->add_action('admin_init', 'meu_modulo_setup_menu');

function meu_modulo_setup_menu()
{
    $CI = &get_instance();

    // Adicionar ao sub-menu de Setup
    $CI->app_menu->add_setup_menu_item('meu-modulo-settings', [
        'name'     => _l('meu_modulo_settings'),
        'href'     => admin_url('meu_modulo/settings'),
        'position' => 50,
        'icon'     => 'fa fa-cog',
    ]);
}

---

Ícones Font Awesome 4

Mais Usados

Ícone	Classe
Lista	fa fa-list
Adicionar	fa fa-plus
Editar	fa fa-edit / fa fa-pencil
Apagar	fa fa-trash
Configurações	fa fa-cog / fa fa-cogs
Utilizador	fa fa-user
Utilizadores	fa fa-users
Ficheiro	fa fa-file / fa fa-file-o
Pasta	fa fa-folder / fa fa-folder-o
Email	fa fa-envelope / fa fa-envelope-o
Calendário	fa fa-calendar
Gráfico	fa fa-bar-chart / fa fa-line-chart
Dinheiro	fa fa-money
Cubo	fa fa-cube
Sino	fa fa-bell
Check	fa fa-check
Warning	fa fa-exclamation-triangle
Info	fa fa-info-circle

Referência Completa

Font Awesome 4.7 Icons

---

Exemplos Completos

Módulo com Menu Completo

// modules/meu_modulo/meu_modulo.php

hooks()->add_action('admin_init', 'meu_modulo_init_menus');
hooks()->add_action('clients_init', 'meu_modulo_client_menu');

/**
 * Menus Admin
 */
function meu_modulo_init_menus()
{
    if (!staff_can('view', 'meu_modulo')) {
        return;
    }

    $CI = &get_instance();

    // Menu principal com sub-items
    $CI->app_menu->add_sidebar_menu_item('meu-modulo', [
        'name'     => _l('meu_modulo'),
        'collapse' => true,
        'position' => 27,
        'icon'     => 'fa fa-cube',
        'badge'    => [
            'value' => meu_modulo_count_pending(),
            'type'  => 'warning',
            'show_on_sidebar' => true,
        ],
    ]);

    // Sub-items
    $CI->app_menu->add_sidebar_children_item('meu-modulo', [
        'slug'     => 'meu-modulo-dashboard',
        'name'     => _l('dashboard'),
        'href'     => admin_url('meu_modulo'),
        'position' => 1,
        'icon'     => 'fa fa-tachometer',
    ]);

    $CI->app_menu->add_sidebar_children_item('meu-modulo', [
        'slug'     => 'meu-modulo-items',
        'name'     => _l('items'),
        'href'     => admin_url('meu_modulo/items'),
        'position' => 2,
        'icon'     => 'fa fa-list',
    ]);

    if (staff_can('create', 'meu_modulo')) {
        $CI->app_menu->add_sidebar_children_item('meu-modulo', [
            'slug'     => 'meu-modulo-create',
            'name'     => _l('create'),
            'href'     => admin_url('meu_modulo/create'),
            'position' => 3,
            'icon'     => 'fa fa-plus',
        ]);
    }

    // Settings no Setup
    if (is_admin()) {
        $CI->app_menu->add_setup_menu_item('meu-modulo-settings', [
            'name'     => _l('meu_modulo_settings'),
            'href'     => admin_url('meu_modulo/settings'),
            'position' => 80,
            'icon'     => 'fa fa-cog',
        ]);
    }
}

/**
 * Menu Cliente
 */
function meu_modulo_client_menu()
{
    if (!is_client_logged_in()) {
        return;
    }

    add_theme_menu_item('meu-modulo', [
        'name'     => _l('meu_modulo'),
        'href'     => site_url('meu_modulo'),
        'position' => 32,
        'icon'     => 'fa fa-cube',
    ]);
}

/**
 * Contador para badge
 */
function meu_modulo_count_pending()
{
    $CI = &get_instance();
    $CI->db->where('status', 'pending');
    return $CI->db->count_all_results(db_prefix() . 'meu_modulo');
}

---

Anti-Patterns (NUNCA FAZER)

Anti-Pattern	Risco	Alternativa
Menu sem verificar permissões	Acesso não autorizado	staff_can()
Posição fixa sem considerar conflitos	Sobreposição	Posições intermédias
Hardcode nome do menu	Não traduzível	Usar _l()
ID duplicado	Menu não aparece	IDs únicos com prefixo
Badge com query pesada	Performance	Cache ou contagem eficiente

---

Checklist Menu

1. [ ] Hook correcto (admin_init / clients_init)
2. [ ] ID único com prefixo do módulo
3. [ ] Permissões verificadas
4. [ ] _l() para nome do menu
5. [ ] Posição apropriada (não conflitar)
6. [ ] Ícone Font Awesome 4 válido
7. [ ] Badge eficiente (se usado)
8. [ ] Sub-items com slugs únicos

---

Versão: 1.0.0 | Autor: Descomplicar® Fonte: help.perfexcrm.com/create-menu-items