Navbar Configuration

Overview

The Butler provides navigation hooks that allow your Butler to control the shell's top bar and tab bar per context. Butlers can request titles, back behavior, and primary actions so the navigation feels native to each screen.

Top Bar Configuration

Configure the top navigation bar (header) for your Butler screens.

Set Navigation Title

// Set navigation title for current screen
await window.lifeButler.setNavigationTitle({
  title: 'Expense Details',
  subtitle: 'January 15, 2024' // Optional
});

// Update title when navigating
window.lifeButler.onScreenChange((screen) => {
  if (screen === 'expense-detail') {
    window.lifeButler.setNavigationTitle({
      title: 'Expense Details'
    });
  } else if (screen === 'expense-list') {
    window.lifeButler.setNavigationTitle({
      title: 'Expenses'
    });
  }
});

Configure Back Button

// Configure back button behavior
await window.lifeButler.setBackButton({
  visible: true,
  label: 'Back', // Optional custom label
  action: async () => {
    // Custom back action
    if (hasUnsavedChanges()) {
      const confirm = await showConfirmDialog('Discard changes?');
      if (confirm) {
        navigateBack();
      }
    } else {
      navigateBack();
    }
  }
});

// Hide back button (e.g., on home screen)
await window.lifeButler.setBackButton({
  visible: false
});

Add Primary Actions

// Add primary action buttons to top bar
await window.lifeButler.setPrimaryActions([
  {
    id: 'save',
    label: 'Save',
    icon: 'checkmark',
    action: async () => {
      await saveExpense();
      showSuccessMessage('Expense saved');
    }
  },
  {
    id: 'more',
    label: 'More',
    icon: 'ellipsis',
    menu: [
      { id: 'edit', label: 'Edit' },
      { id: 'delete', label: 'Delete' },
      { id: 'share', label: 'Share' }
    ]
  }
]);

// Clear primary actions
await window.lifeButler.setPrimaryActions([]);

Tab Bar Configuration

Configure the bottom tab bar for your Butler screens. The tab bar is shared across all Butlers and shows core navigation tabs.

Show/Hide Tab Bar

// Hide tab bar for full-screen experience
await window.lifeButler.setTabBarVisible(false);

// Show tab bar
await window.lifeButler.setTabBarVisible(true);

// Tab bar visibility is automatically managed based on screen context
// Hide for modals, full-screen forms, etc.

Tab Bar Badges

Note: Tab bar badges are managed by The Butler and core Butlers. Custom Butlers cannot directly modify tab bar badges, but can request badge updates through The Butler's API.

Screen Context

Update navigation configuration when screen context changes.

// Update navigation when screen changes
function navigateToScreen(screen, params) {
  // Update navigation configuration
  if (screen === 'expense-detail') {
    window.lifeButler.setNavigationTitle({
      title: 'Expense Details'
    });
    window.lifeButler.setBackButton({ visible: true });
    window.lifeButler.setPrimaryActions([
      { id: 'save', label: 'Save', icon: 'checkmark' }
    ]);
  } else if (screen === 'expense-list') {
    window.lifeButler.setNavigationTitle({
      title: 'Expenses'
    });
    window.lifeButler.setBackButton({ visible: false });
    window.lifeButler.setPrimaryActions([
      { id: 'add', label: 'Add', icon: 'plus' }
    ]);
  }
  
  // Navigate to screen
  showScreen(screen, params);
}

// Clean up on unmount
window.addEventListener('beforeunload', () => {
  window.lifeButler.setNavigationTitle({ title: '' });
  window.lifeButler.setPrimaryActions([]);
});

Requirements

• Set titles: Set appropriate navigation titles for each screen in your Butler.
• Configure back button: Configure back button visibility and behavior appropriately for each screen.
• Add primary actions: Add primary action buttons to the top bar when relevant (save, add, etc.).
• Update on navigation: Update navigation configuration when screen context changes.
• Clean up: Reset navigation configuration when your Butler unmounts or navigates away.