Navigation – Component Concept

1
Controller Discovery
2
        ↓
3
navItem() declarations collected     ← opt-in, directly in the controller
4
        ↓
5
controller:navigation:collected      ← Event: app code can filter/extend
6
        ↓
7
controller:navigation:ready          ← Event: finished navigation, read-only
8
        ↓
9
template:render:before               ← _nav injected into template data
10
        ↓
11
Template renders <nav>

1
// src/controllers/info.js
2
export default class InfoController extends Controller {
3
 
4
    define() {
5
        this.navItem('index', { label: 'Info',  position: 10 });
6
        this.navItem('team',  { label: 'Team',  position: 20 });
7
        // guide() stays silent – reachable, but no nav entry
8
    }
9
 
10
    index()  { ... }   // → GET /info
11
    team()   { ... }   // → GET /info/team
12
    guide()  { ... }   // → GET /info/guide  (no navItem → no nav link)
13
}

1
// src/controllers/index.js
2
export default class IndexController extends Controller {
3
 
4
    define() {
5
        this.navItem('index', { label: 'Home', position: 0 });
6
    }
7
 
8
    index() { ... }    // → GET /
9
}

1
// src/controllers/contact.js
2
export default class ContactController extends Controller {
3
 
4
    define() {
5
        this.navItem('index', { label: 'Contact', position: 30 });
6
        // submit() is POST – no navItem, makes no sense
7
    }
8
 
9
    index()  { ... }   // → GET  /contact
10
    submit() { ... }   // → POST /contact
11
}

1
this.navItem(method, options)

1
{controllerSlug}_{methodName}

1
src/controllers/index.js        →  controllerSlug: index
2
src/controllers/info.js         →  controllerSlug: info
3
src/controllers/tool/chat.js    →  controllerSlug: tool_chat
4
src/controllers/admin/user.js   →  controllerSlug: admin_user

1
index.js    → index()    →  key: index_index
2
info.js     → index()    →  key: info_index
3
info.js     → team()     →  key: info_team
4
info.js     → guide()    →  key: info_guide
5
tool/chat.js → index()   →  key: tool_chat_index
6
tool/chat.js → guide()   →  key: tool_chat_guide
7
admin/user.js → index()  →  key: admin_user_index
8
admin/user.js → edit()   →  key: admin_user_edit

1
src/controllers/{path}/{file}.js → {path}_{file}_{method}
2
Underscores instead of slashes, no .js

1
[controller] navItem registered: info_team  →  GET /info/team  "Team"
2
[controller] navItem registered: info_index →  GET /info       "Info"

1
// src/controllers/tool/chat.js
2
define() {
3
    this.navItem('index', { key: 'chat', label: 'Chat', position: 10 });
4
}

1
// Another controller references the custom key as parent:
2
this.navItem('index', { label: 'Chat Guide', parent: 'chat' });

1
{
2
    key:        'info_team',        // unique key: controllerKey_methodName
3
    label:      'Team',
4
    href:       '/info/team',       // resolved by the router
5
    position:   20,
6
    parent:     'info_index',       // '' if no parent
7
    icon:       '',
8
    target:     '_self',
9
    active:     false,              // true when current route matches
10
    children:   [],                 // navItems with matching parent key
11
}

1
// Payload
2
{ items: NavItem[] }

1
// Example: filtering
2
event.on('controller:navigation:collected', ({ items }) => {
3
    // Show admin link only when logged in
4
    const filtered = items.filter(item => {
5
        if (item.key === 'admin_index') return isAuthenticated();
6
        return true;
7
    });
8
    items.splice(0, items.length, ...filtered);
9
});

1
// Example: adding an external link
2
event.on('controller:navigation:collected', ({ items }) => {
3
    items.push({
4
        key:      'extern_github',
5
        label:    'GitHub',
6
        href:     'https://github.com/xpulse1',
7
        position: 99,
8
        parent:   '',
9
        icon:     '',
10
        target:   '_blank',
11
        active:   false,
12
        children: [],
13
    });
14
});

1
// Example: reordering
2
event.on('controller:navigation:collected', ({ items }) => {
3
    items.sort((a, b) => a.position - b.position);
4
});

1
// Payload
2
{ items: NavItem[] }   // already hierarchical – items with children[]

1
// Declaration
2
this.navItem('index', { label: 'Products', position: 10 });
3
this.navItem('chat',  { label: 'Chat',     position: 0, parent: 'products_index' });
4
this.navItem('web',   { label: 'Web',      position: 1, parent: 'products_index' });

1
// Resulting structure
2
{
3
    key:      'products_index',
4
    label:    'Products',
5
    href:     '/products',
6
    children: [
7
        { key: 'products_chat', label: 'Chat', href: '/products/chat', children: [] },
8
        { key: 'products_web',  label: 'Web',  href: '/products/web',  children: [] },
9
    ]
10
}

1
// Internally in @xpulse/controller
2
event.on('template:render:before', ({ data }) => {
3
    data._nav = navigationRegistry.getItems();  // finished, hierarchical navItems
4
});

1
<nav>
2
  {% for item in _nav %}
3
    <a href="{{ item.href }}"
4
       class="{{ item.active ? 'active' : '' }}"
5
       target="{{ item.target }}">
6
      {{ item.label }}
7
    </a>
8
 
9
    {% if item.children.length %}
10
      <ul>
11
        {% for child in item.children %}
12
          <li>
13
            <a href="{{ child.href }}"
14
               class="{{ child.active ? 'active' : '' }}">
15
              {{ child.label }}
16
            </a>
17
          </li>
18
        {% endfor %}
19
      </ul>
20
    {% endif %}
21
  {% endfor %}
22
</nav>

1
[controller] navItem DUPLICATE key "chat" ignored
2
             → src/controllers/support/chat.js @ index()
3
             already registered by: src/controllers/tool/chat.js @ index()
4
             Fix: use key option to set an explicit unique key

1
[controller] navItem UNKNOWN method "details" in InfoController
2
             → src/controllers/info.js
3
             Available methods: index, team, guide

1
[controller] navItem parent "products_index" not found for key "info_team"
2
             → src/controllers/info.js @ team()
3
             Item will be rendered as top-level nav entry

1
[controller] navItem registered: info_index  →  GET /info       "Info"   position=10
2
[controller] navItem registered: info_team   →  GET /info/team  "Team"   position=20
3
[controller] navigation collected: 5 items
4
[controller] navigation ready: 5 items (2 top-level, 3 children)

1
[controller] Navigation ready – 5 items registered

1
controller:discovered            ← all controllers found, routes registered
2
controller:navigation:collected  ← navItems collected, pipeline open
3
controller:navigation:ready      ← navigation finalised