# nav

**Repository Path**: allentj2020/nav

## Basic Information

- **Project Name**: nav
- **Description**: A Frappe app for customizing navigation behavior and workspace management in Frappe version 16.
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: version-16
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 5
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### Nav

A Frappe app for customizing navigation behavior and workspace management in Frappe version 16.
Currently synchronized to frappe 16.9.0 version-16 (e5b04e0)

## Features

### Navigation Override Control
This app provides granular control over Frappe's navigation system through the **Nav Settings** configuration:

- **Enable/Disable Navigation Overrides**: Toggle custom navigation behavior on/off
- **Default Routing**: Redirect home breadcrumb links to a specified link
- **Enhanced Sidebar Menu**: Custom workspace dropdown with improved organization

### Core Functionality

#### 1. Breadcrumb Navigation Enhancement
Overrides `frappe.breadcrumbs.append_breadcrumb_element` to:
- Intercept home route navigation (`/desk`, `/app`, `desk`, `#`)
- Redirect to configured link when enabled
- Maintain normal behavior for other routes

#### 2. Sidebar Header Customization  
Extends `frappe.ui.SidebarHeader` to:
- Dynamically populate workspace dropdown menu
- Include all available workspaces with proper icons
- Handle nested workspace folders
- Support external URL navigation

#### 3. Boot Information Extension
Adds navigation settings to `frappe.boot` data for client-side access.

## Configuration

### Nav Settings
Access configuration through: **Nav Settings**

#### Fields:
- **Enabled** (Check): Enable/disable all navigation overrides
- **Link Type** (Link): Select default link type
- **Link To** (Dynamic Link): Select default link to
- **Blocked** (Check): Users will be locked in the default workspace if checked

### Usage Scenarios

#### Scenario 1: Basic Navigation Override
1. Go to Nav Settings
2. Check "Enabled"
3. Leave Link Type and Link To blank
4. Result: Enhanced sidebar menu with all workspaces listed

#### Scenario 2: Default Workspace Redirection
1. Go to Nav Settings  
2. Check "Enabled"
3. Select Link Type and Link To
4. Result: Clicking home breadcrumbs redirects to the specified link

#### Scenario 3: Disabled Mode
1. Uncheck "Enabled" in Nav Settings
2. Result: Standard Frappe navigation behavior restored

## Technical Implementation

### JavaScript Overrides
- **File**: `nav/public/js/nav.js`
- **Key Functions**:
  - `can_override()`: Checks if navigation overrides are enabled
  - Custom `frappe.breadcrumbs.append_breadcrumb_element`
  - Extended `frappe.ui.SidebarHeader` class
  - Extended `frappe.ui.Sidebar` class

### Backend Integration
- **Boot Info Extension**: `nav/startup/boot.py`
- **Settings Doctype**: `Nav Settings` (Single doctype)
- **Hooks Configuration**: Extends `frappe.boot` with nav settings

### Supported Routes
Home breadcrumb routes that trigger redirection:
- `/desk`
- `/app` 
- `desk`
- `#`

## Installation

You can install this app using the [bench](https://github.com/frappe/bench) CLI:

```bash
cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch version-16
bench install-app nav
```

## Contributing

This app uses `pre-commit` for code formatting and linting. Please [install pre-commit](https://pre-commit.com/#installation) and enable it for this repository:

```bash
cd apps/nav
pre-commit install
```

Pre-commit is configured to use the following tools for checking and formatting your code:

- ruff
- eslint
- prettier
- pyupgrade

## License

MIT