0
# JavaScript Navigation API
1

2
Interactive navigation controller providing responsive behavior, mobile menu support, sticky navigation, and smooth scrolling with hash-based navigation state management.
3

4
## Global API Access
5

6
The ThemeNav functionality is available globally in browsers:
7

8
```javascript { .api }
9
// Global browser objects
10
window.SphinxRtdTheme = {
11
    Navigation: ThemeNav,  // Main navigation controller
12
    StickyNav: ThemeNav    // Legacy alias for backwards compatibility
13
}
14
```
15

16
## ThemeNav Class
17

18
Core navigation controller that manages responsive navigation behavior, mobile menu interactions, and scroll-based navigation updates.
19

20
### Constructor and Initialization
21

22
```javascript { .api }
23
function ThemeNav(): NavigationController
24
```
25

26
Creates a new navigation controller instance with internal state management for scroll position, window dimensions, and navigation elements.
27

28
**Internal State:**
29
- `navBar`: Navigation sidebar element
30
- `win`: Window object reference  
31
- `winPosition`: Current scroll position
32
- `winHeight`: Window height in pixels
33
- `docHeight`: Document height in pixels
34
- `isRunning`: Initialization state flag
35

36
### Core Methods
37

38
#### enable
39

40
```javascript { .api }
41
enable(withStickyNav?: boolean): void
42
```
43

44
Enables theme navigation functionality with optional sticky navigation behavior.
45

46
**Parameters:**
47
- `withStickyNav` (boolean, optional): Enable sticky navigation scrolling (default: true)
48

49
**Actions:**
50
- Initializes DOM event handlers via `init()`
51
- Sets up window scroll monitoring for sticky navigation
52
- Configures window resize handling
53
- Establishes hash change navigation reset
54
- Prevents multiple initialization calls
55

56
**Usage Example:**
57

58
```javascript
59
// Enable with sticky navigation (default)
60
SphinxRtdTheme.Navigation.enable();
61

62
// Enable without sticky navigation  
63
SphinxRtdTheme.Navigation.enable(false);
64
```
65

66
#### enableSticky
67

68
```javascript { .api }
69
enableSticky(): void
70
```
71

72
Legacy method that enables navigation with sticky behavior. Maintained for backwards compatibility with theme version 0.3.0.
73

74
**Usage Example:**
75

76
```javascript
77
// Legacy sticky navigation enablement
78
SphinxRtdTheme.StickyNav.enableSticky();
79
```
80

81
#### init
82

83
```javascript { .api }
84
init($: jQuery): void
85
```
86

87
Initializes navigation with jQuery DOM manipulation and event handlers.
88

89
**Parameters:**
90
- `$` (jQuery): jQuery instance for DOM operations
91

92
**Setup Actions:**
93
- Identifies navigation sidebar (`div.wy-side-scroll:first`)
94
- Configures mobile menu toggle handlers
95
- Sets up navigation link click handlers  
96
- Implements responsive table wrapping
97
- Adds expand/collapse buttons to nested navigation
98
- Manages current page highlighting and navigation state
99

100
#### reset
101

102
```javascript { .api }
103
reset(): void
104
```
105

106
Resets navigation state based on current URL hash, expanding navigation to show the current page.
107

108
**Behavior:**
109
- Extracts anchor from `window.location.hash`
110
- Finds corresponding navigation link in sidebar
111
- Expands navigation hierarchy to reveal current page
112
- Handles fallback navigation for missing anchors
113
- Scrolls current navigation item into view
114
- Manages ARIA accessibility attributes
115

116
### Scroll and Resize Handling
117

118
#### onScroll
119

120
```javascript { .api }
121
onScroll(): void
122
```
123

124
Handles window scroll events to maintain sticky navigation behavior. Updates navigation scroll position to keep current content visible.
125

126
**Functionality:**
127
- Calculates new navigation position based on window scroll
128
- Prevents navigation scrolling beyond document bounds
129
- Synchronizes navigation scroll with window scroll position
130
- Uses requestAnimationFrame for smooth performance
131

132
#### onResize
133

134
```javascript { .api }
135
onResize(): void
136
```
137

138
Handles window resize events to recalculate dimensions for responsive navigation behavior.
139

140
**Updates:**
141
- Window height (`winHeight`)
142
- Document height (`docHeight`)
143
- Navigation positioning calculations
144

145
### Navigation State Management
146

147
#### hashChange
148

149
```javascript { .api }
150
hashChange(): void
151
```
152

153
Manages navigation state during hash-based navigation (anchor links). Prevents scroll interference during programmatic navigation.
154

155
**Behavior:**
156
- Sets `linkScroll` flag during hash changes
157
- Temporarily disables scroll handlers
158
- Restores scroll handling after navigation completes
159

160
#### toggleCurrent
161

162
```javascript { .api }
163
toggleCurrent(elem: jQuery): void
164
```
165

166
Toggles the current navigation item state and manages navigation hierarchy expansion/collapse.
167

168
**Parameters:**
169
- `elem` (jQuery): Navigation element to toggle
170

171
**Actions:**
172
- Removes 'current' class from sibling navigation items
173
- Toggles current item's expanded/collapsed state
174
- Updates ARIA accessibility attributes (`aria-expanded`)
175
- Manages nested navigation visibility
176
- Preserves terminal navigation elements (items without children)
177

178
## DOM Event Handlers
179

180
The navigation system automatically sets up the following event handlers:
181

182
### Mobile Menu Toggle
183

184
```javascript { .api }
185
// Mobile navigation menu toggle
186
$("[data-toggle='wy-nav-top']").click() 
187
// Toggles: $("[data-toggle='wy-nav-shift']").toggleClass("shift")
188
```
189

190
### Navigation Link Clicks
191

192
```javascript { .api }
193
// Navigation menu item clicks
194
$(".wy-menu-vertical .current ul li a").click()
195
// Actions: Close mobile menu, toggle current item, handle hash change
196
```
197

198
### Version Selector Toggle
199

200
```javascript { .api }
201
// Version/language selector toggle
202
$("[data-toggle='rst-current-version']").click()
203
// Toggles: $("[data-toggle='rst-versions']").toggleClass("shift-up")
204
```
205

206
### Responsive Table Enhancement
207

208
```javascript { .api }
209
// Automatic responsive table wrapping
210
$("table.docutils:not(.field-list,.footnote,.citation)")
211
    .wrap("<div class='wy-table-responsive'></div>");
212

213
// Special handling for footnote and citation tables
214
$("table.docutils.footnote")
215
    .wrap("<div class='wy-table-responsive footnote'></div>");
216
$("table.docutils.citation")
217
    .wrap("<div class='wy-table-responsive citation'></div>");
218
```
219

220
## Cross-Browser Compatibility
221

222
### RequestAnimationFrame Polyfill
223

224
The navigation includes a complete polyfill for smooth animation across all browsers:
225

226
```javascript { .api }
227
// Polyfills for older browsers
228
window.requestAnimationFrame = function(callback, element): number
229
window.cancelAnimationFrame = function(id: number): void
230
```
231

232
Supports vendor prefixes: `ms`, `moz`, `webkit`, `o` with fallback to setTimeout-based implementation.
233

234
## Usage Examples
235

236
### Basic Navigation Setup
237

238
```javascript
239
// Standard theme navigation initialization
240
$(document).ready(function() {
241
    SphinxRtdTheme.Navigation.enable();
242
});
243
```
244

245
### Custom Navigation Configuration
246

247
```javascript
248
// Navigation with custom scroll behavior
249
$(document).ready(function() {
250
    var nav = SphinxRtdTheme.Navigation;
251
    
252
    // Enable without sticky behavior for custom control
253
    nav.enable(false);
254
    
255
    // Custom scroll handler
256
    $(window).on('scroll', function() {
257
        // Custom scroll logic
258
        nav.onScroll();
259
    });
260
});
261
```
262

263
### Mobile-First Navigation
264

265
```javascript
266
// Responsive navigation with mobile detection
267
$(document).ready(function() {
268
    var isMobile = $(window).width() <= 768;
269
    
270
    // Enable sticky navigation only on desktop
271
    SphinxRtdTheme.Navigation.enable(!isMobile);
272
    
273
    // Additional mobile-specific handlers
274
    if (isMobile) {
275
        // Custom mobile navigation behavior
276
    }
277
});
278
```
279

280
### Integration with Custom Scroll Events
281

282
```javascript
283
// Integration with custom scrolling libraries
284
$(document).ready(function() {
285
    SphinxRtdTheme.Navigation.enable();
286
    
287
    // Trigger navigation reset after custom scroll events
288
    $('.custom-scroll-trigger').on('click', function() {
289
        // Perform custom scrolling
290
        $('html, body').animate({scrollTop: target}, 500, function() {
291
            // Reset navigation state after scroll
292
            SphinxRtdTheme.Navigation.reset();
293
        });
294
    });
295
});
296
```
297

298
## Module Exports
299

300
For Node.js/CommonJS environments:
301

302
```javascript { .api }
303
module.exports.ThemeNav = ThemeNav();
304
```
305

306
The exported ThemeNav is a pre-instantiated navigation controller ready for use.