Referencia de Navegación

Introducción

Laravel RoutingKit permite crear navegaciones de forma estructurada mediante diferentes tipos de objetos de navegación. Todos comparten el mismo objeto base pero ofrecen funcionalidades específicas según el caso de uso.

use Rk\RoutingKit\Entities\RkNavigation;

Tipos de Navegación

RkNavigation::makeGroup()

Crea un grupo de navegación que agrupa múltiples elementos. El paquete resuelve automáticamente el enlace del grupo basándose en el primer item disponible después de aplicar los filtros de permisos.

Características:

• Resuelve dinámicamente el enlace basado en permisos del usuario
• Incluye contador de badges y acumulado de badges de sus items
• Útil para módulos con notificaciones agrupadas

RkNavigation::makeGroup('admin-panel')
    ->setLabel('Panel Administrativo')
    ->setItems([
        RkNavigation::make('users'),
        RkNavigation::makeSimple('reports', 'admin.reports'),
        RkNavigation::makeLink('external-api')
    ])
    ->setEndblock('admin-panel')

RkNavigation::make()

Objeto vinculado directamente con RkRoute. Recibe dos parámetros: el ID local y el ID del RkRoute de referencia.

RkNavigation::make('id_local', 'id_RkRoute')
    ->setItems([])
    ->setEndblock('id_local')

Comportamiento simplificado: Cuando el ID local coincide con el ID de RkRoute, puede omitir el segundo parámetro:

// Estas dos declaraciones son equivalentes
RkNavigation::make('dashboard', 'dashboard')
RkNavigation::make('dashboard')

Funcionalidades automáticas:

• Copia urlName del RkRoute referenciado
• Hereda accessPermission del RkRoute
• Establece automáticamente la URL desde la ruta Laravel
• Genera un label por defecto (personalizable)

RkNavigation::makeSimple()

Para casos donde desea usar rutas Laravel tradicionales sin RkRoute.

RkNavigation::makeSimple('id_local', 'nombre_ruta')
    ->setItems([])
    ->setEndblock('id_local')

Consideraciones:

• No hereda permisos automáticamente (debe establecerlos manualmente)
• nombre_ruta debe corresponder a una ruta definida en routes/web.php
• Aplica la misma regla de simplificación cuando los nombres coinciden

// Si el ID local coincide con el nombre de ruta
RkNavigation::makeSimple('profile') // Equivale a ('profile', 'profile')

RkNavigation::makeLink()

Para URLs completamente personalizadas, dominios externos o rutas sin nombre.

RkNavigation::makeLink('external-api')
    ->setUrl('https://api.external.com/dashboard')
    ->setLabel('API Externa')
    ->setAccessPermission('view-external-api')
    ->setEndblock('external-api')

Atributos Disponibles

Atributo	Tipo	Descripción
id	string	Identificador único del elemento de navegación
makerMethod	?string	Método constructor utilizado (‘make’, ‘makeGroup’, etc.)
instanceRouteId	?string	ID del RkRoute al que hace referencia
parentId	?string	ID del elemento padre en navegaciones jerárquicas
urlName	?string	Nombre de la ruta Laravel
url	?string	URL completa del enlace
description	?string	Descripción del elemento de navegación
accessPermission	?string	Permiso requerido para mostrar el elemento
label	?string	Texto mostrado en la navegación
bageInt	?int	Contador numérico para badges
acuntBageInt	?int	Acumulado de badges (útil en grupos)
finalBage	?string	Badge final procesado para mostrar
bageString	?string	Badge de texto personalizado
heroIcon	?string	Icono usando HeroIcons
icon	?string	Icono personalizado
isFpRoute	bool	Indica si es una ruta de primera parte
isGroup	bool	Indica si el elemento es un grupo
isHidden	bool	Controla la visibilidad del elemento
isActive	bool	Estado activo del elemento de navegación

Métodos de Configuración

Todos los atributos pueden configurarse utilizando métodos con la convención set{AtributoName}():

Métodos Básicos

->setLabel(string $label)                    // Establece el texto del enlace
->setDescription(string $desc)               // Descripción del elemento
->setUrl(string $url)                       // URL personalizada
->setAccessPermission(string $perm)         // Permiso requerido
->setUrlName(string $urlName)               // Nombre de ruta Laravel

Iconos y Badges

->setIcon(string $icon)                     // Icono personalizado
->setHeroIcon(string $heroIcon)            // Icono de HeroIcons
->setBageInt(int $count)                   // Badge numérico
->setBageString(string $text)              // Badge de texto
->setFinalBage(string $badge)              // Badge procesado final

Estados y Comportamiento

->setIsHidden(bool $hidden)                // Ocultar elemento
->setIsActive(bool $active)                // Marcar como activo
->setIsFpRoute(bool $isFpRoute)           // Marcar como ruta de primera parte
->setItems(array $items)                   // Items hijos (para grupos)
->setParentId(string $parentId)            // ID del elemento padre

Soporte para Closures

La mayoría de los métodos de configuración aceptan closures para evaluación dinámica: para esto recuerde establecer su variable only_string_support = false

RkNavigation::make('notifications')
    ->setLabel(function() {
        return __('Notificaciones');
    })
    ->setBageInt(function() {
        return auth()->user()->unreadNotifications()->count();
    })
    ->setIsHidden(function() {
        return !auth()->user()->can('view-notifications');
    });

Atributos Personalizados

Puede agregar atributos personalizados utilizando la convención set{NuevoAtributoName}():

RkNavigation::make('dashboard')
    ->setCustomColor('blue')
    ->setTooltip('Panel principal del usuario')
    ->setDisplayOrder(1);

Los atributos personalizados quedan disponibles como propiedades del objeto y pueden ser utilizados en sus vistas Blade.

Extensibilidad Futura

En versiones posteriores será posible heredar la clase RkNavigation para establecer otros atributos personalizados de forma más estructurada:

// Funcionalidad planificada
class CustomNavigation extends RkNavigation
{
    public ?string $customAttribute = null;

    public function setCustomAttribute(string $value): self
    {
        $this->customAttribute = $value;
        return $this;
    }
}

Consideraciones Importantes

IDs Únicos

Los IDs deben ser únicos en todo el sistema, incluso entre diferentes archivos de configuración, ya que el paquete los carga en un solo contexto (excepto en carga perezosa).

Filtros de Permisos

El paquete aplica automáticamente filtros basados en:

• Permisos del usuario autenticado
• Estado de autenticación
• Configuración de accessPermission

Jerarquías y Badges

Los elementos pueden anidarse usando setItems() para crear navegaciones multinivel. Los grupos calculan automáticamente el acumulado de badges de sus elementos hijos, lo que es especialmente útil para mostrar contadores de notificaciones agrupadas.

Resolución Dinámica

Los grupos resuelven su enlace principal después de aplicar todos los filtros de permisos, garantizando que siempre apunten a un elemento accesible para el usuario actual.