electron · alicelovescake · Jul 1, 2024 · Jul 1, 2024 · Jul 1, 2024 · Jul 1, 2024
@@ -44,6 +44,7 @@ an issue:
   * [Offline/Online Detection](latest/tutorial/online-offline-events.md)
   * [Represented File for macOS BrowserWindows](latest/tutorial/represented-file.md)
   * [Native File Drag & Drop](latest/tutorial/native-file-drag-drop.md)
+  * [Navigation History](latest/tutorial/navigation-history.md)
   * [Offscreen Rendering](latest/tutorial/offscreen-rendering.md)
   * [Dark Mode](latest/tutorial/dark-mode.md)
   * [Web embeds in Electron](latest/tutorial/web-embeds.md)

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Enhanced Browser with Navigation History</title>
+    <link href="styles.css" rel="stylesheet"/>
+</head>
+<body>
+
+      <div id="controls">
+        <button id="backBtn" title="Go back">Back</button>
+        <button id="forwardBtn" title="Go forward">Forward</button>
+        <button id="backHistoryBtn" title="Show back history">Back History</button>
+        <button id="forwardHistoryBtn" title="Show forward history">Forward History</button>
+        <input id="urlInput" type="text" placeholder="Enter URL">
+        <button id="goBtn" title="Navigate to URL">Go</button>
+    </div>
+
+    <div id="description">
+        <h2>Navigation History Demo</h2>
+        <p>This demo showcases Electron's NavigationHistory API functionality.</p>
+        <p><strong>Back/Forward:</strong> Navigate through your browsing history.</p>
+        <p><strong>Back History/Forward History:</strong> View and select from your browsing history.</p>
+        <p><strong>URL Bar:</strong> Enter a URL and click 'Go' or press Enter to navigate.</p>
+    </div>
+    <script src="renderer.js"></script>
+</body>
+</html>
@@ -0,0 +1,61 @@
+// main.js
+const { app, BrowserWindow, BrowserView, ipcMain } = require('electron');
+const path = require('path');
+
+
+function createWindow() {
+  const mainWindow = new BrowserWindow({
+    width: 1000,
+    height: 800,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      nodeIntegration: false,
+      contextIsolation: true
+    }
+  });
+
+  mainWindow.loadFile('index.html');
+
+  const view = new BrowserView();
+  mainWindow.setBrowserView(view);
+  view.setBounds({ x: 0, y: 200, width: 1000, height: 600 });
+  view.setAutoResize({ width: true, height: true });
+
+  const navigationHistory = view.webContents.navigationHistory
+  ipcMain.handle('nav:back', () => 
+     navigationHistory.goBack()
+  );
+
+  ipcMain.handle('nav:forward', () => {
+     navigationHistory.goForward()
+
+  });
+
+  ipcMain.handle('nav:canGoBack', () => navigationHistory.canGoBack());
+  ipcMain.handle('nav:canGoForward', () => navigationHistory.canGoForward());
+  ipcMain.handle('nav:loadURL', (_, url) => 
+    view.webContents.loadURL(url)
+);
+  ipcMain.handle('nav:getCurrentURL', () => view.webContents.getURL());
+  ipcMain.handle('nav:getHistory', () =>{
+    return navigationHistory.getAllEntries()
+  });
+
+  view.webContents.on('did-navigate', () => {
+    mainWindow.webContents.send('nav:updated');
+  });
+
+  view.webContents.on('did-navigate-in-page', () => {
+    mainWindow.webContents.send('nav:updated');
+  });
+}
+
+app.whenReady().then(createWindow);
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) createWindow();
+});
@@ -0,0 +1,12 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('electronAPI', {
+  goBack: () => ipcRenderer.invoke('nav:back'),
+  goForward: () => ipcRenderer.invoke('nav:forward'),
+  canGoBack: () => ipcRenderer.invoke('nav:canGoBack'),
+  canGoForward: () => ipcRenderer.invoke('nav:canGoForward'),
+  loadURL: (url) => ipcRenderer.invoke('nav:loadURL', url),
+  getCurrentURL: () => ipcRenderer.invoke('nav:getCurrentURL'),
+  getHistory: () => ipcRenderer.invoke('nav:getHistory'),
+  onNavigationUpdate: (callback) => ipcRenderer.on('nav:updated', callback)
+});
@@ -0,0 +1,78 @@
+const backBtn = document.getElementById('backBtn');
+const forwardBtn = document.getElementById('forwardBtn');
+const backHistoryBtn = document.getElementById('backHistoryBtn');
+const forwardHistoryBtn = document.getElementById('forwardHistoryBtn');
+const urlInput = document.getElementById('urlInput');
+const goBtn = document.getElementById('goBtn');
+const historyPanel = document.getElementById('historyPanel');
+
+async function updateButtons() {
+  backBtn.disabled = !(await window.electronAPI.canGoBack());
+  forwardBtn.disabled = !(await window.electronAPI.canGoForward());
+}
+
+async function updateURL() {
+  urlInput.value = await window.electronAPI.getCurrentURL();
+}
+
+function transformUrl(url) {
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    return url = 'https://' + url;
+  }
+  return url;
+}
+
+async function navigate(url) {
+    const urlInput = transformUrl(url)
+
+    await window.electronAPI.loadURL(urlInput);
+}
+
+async function showHistory(forward = false) {
+  const history = await window.electronAPI.getHistory();
+  const currentIndex = history.findIndex(entry => entry.url === transformUrl(urlInput.value));
+
+  if (!currentIndex) {
+      return
+  }
+
+  let relevantHistory = forward 
+    ? history.slice(currentIndex + 1) 
+    : history.slice(0, currentIndex).reverse();
+
+  historyPanel.innerHTML = '';
+  relevantHistory.forEach(entry => {
+    const div = document.createElement('div');
+    div.textContent = `Title: ${entry.title}, URL: ${entry.url}`;
+    div.onclick = () => navigate(entry.url);
+    historyPanel.appendChild(div);
+  });
+
+  historyPanel.style.display = 'block';
+}
+
+backBtn.addEventListener('click', () => window.electronAPI.goBack());
+forwardBtn.addEventListener('click', () => window.electronAPI.goForward());
+backHistoryBtn.addEventListener('click', () => showHistory(false));
+forwardHistoryBtn.addEventListener('click', () => showHistory(true));
+goBtn.addEventListener('click', () => navigate(urlInput.value));
+
+urlInput.addEventListener('keypress', (e) => {
+  if (e.key === 'Enter') {
+     navigate(urlInput.value);
+  }
+});
+
+document.addEventListener('click', (e) => {
+  if (e.target !== historyPanel && !historyPanel.contains(e.target) &&
+      e.target !== backHistoryBtn && e.target !== forwardHistoryBtn) {
+    historyPanel.style.display = 'none';
+  }
+});
+
+window.electronAPI.onNavigationUpdate(() => {
+  updateButtons();
+  updateURL();
+});
+
+updateButtons();
@@ -0,0 +1,58 @@
+body {
+    margin: 0;
+    font-family: Arial, sans-serif;
+    background-color: #f0f0f0;
+}
+#controls {
+    display: flex;
+    align-items: center;
+    padding: 10px;
+    background-color: #ffffff;
+    border-bottom: 1px solid #ccc;
+}
+button {
+    margin-right: 10px;
+    padding: 8px 12px;
+    font-size: 14px;
+    background-color: #4CAF50;
+    color: white;
+    border: none;
+    cursor: pointer;
+    transition: background-color 0.3s;
+}
+button:hover {
+    background-color: #45a049;
+}
+button:disabled {
+    background-color: #cccccc;
+    cursor: not-allowed;
+}
+#urlInput {
+    flex-grow: 1;
+    margin: 0 10px;
+    padding: 8px;
+    font-size: 14px;
+}
+
+#historyPanel {
+    display: none;
+    position: absolute;
+    top: 60px;
+    left: 10px;
+    background: white;
+    border: 1px solid #ccc;
+    padding: 10px;
+    max-height: 300px;
+    overflow-y: auto;
+    z-index: 1000;
+}
+  #historyPanel div {
+    cursor: pointer;
+    padding: 5px;
+}
+
+#description {
+    background-color: #f0f0f0;
+    padding: 10px;
+    margin-top: 150px;
+}
@@ -0,0 +1,61 @@
+---
+title: "Navigation history"
-title: "Navigation history"
+title: "Navigation History"
-title: "Navigation history"
+title: "Navigation History"
+description: "The NavigationHistory API allows you to manage and interact with the browsing history of your Electron application."
+slug: navigation-history
+hide_title: false
+---
+
+# Navigation History
+
+## Overview
+The [NavigationHistory](latest/api/navigation-history.md) API allows you to manage and interact with the browsing history of your Electron application. This powerful feature enables you to create intuitive navigation experiences for your users.
+
+### Accessing NavigationHistory
+To use NavigationHistory, access it through the webContents of your BrowserWindow:
-To use NavigationHistory, access it through the webContents of your BrowserWindow:
+To use NavigationHistory, access it through the [webContents](../api/web-contents.md) of your [BrowserWindow](../api/browser-window.md):
-To use NavigationHistory, access it through the webContents of your BrowserWindow:
+To use NavigationHistory, access it through the [webContents](../api/web-contents.md) of your [BrowserWindow](../api/browser-window.md):
+
+```js
+const { BrowserWindow } = require('electron')
+
+let mainWindow = new BrowserWindow({ width: 800, height: 600 })
+let navigationHistory = mainWindow.webContents.navigationHistory
-let mainWindow = new BrowserWindow({ width: 800, height: 600 })
-let navigationHistory = mainWindow.webContents.navigationHistory
+const mainWindow = new BrowserWindow({ width: 800, height: 600 })
+const navigationHistory = mainWindow.webContents.navigationHistory
-let mainWindow = new BrowserWindow({ width: 800, height: 600 })
-let navigationHistory = mainWindow.webContents.navigationHistory
+const mainWindow = new BrowserWindow({ width: 800, height: 600 })
+const navigationHistory = mainWindow.webContents.navigationHistory
+```
+### Key Features
-### Key Features
-### Key Features
+#### Navigating Through History
-#### Navigating Through History
+#### Navigating through history
-#### Navigating Through History
+#### Navigating through history
+Easily implement back and forward navigation:
+
+```js
+// Go back
+if (navigationHistory.canGoBack()) {
+  navigationHistory.goBack()
+}
+
+// Go forward
+if (navigationHistory.canGoForward()) {
+  navigationHistory.goForward()
+}
+```
+
+#### Accessing History Entries
+Retrieve and display the user's browsing history:
-#### Accessing History Entries
-Retrieve and display the user's browsing history:
+#### Accessing History Entries
+
+Retrieve and display the user's browsing history:
-#### Accessing History Entries
-Retrieve and display the user's browsing history:
+#### Accessing History Entries
+
+Retrieve and display the user's browsing history:
+
+```js
+const entries = navigationHistory.getAllEntries()
+entries.forEach(entry => {
+  console.log(`${entry.title}: ${entry.url}`)
+})
+```
+
+#### Navigating to Specific Entries
+Allow users to jump to any point in their browsing history:
+```js
+// Navigate to the 5th entry in the history
+navigationHistory.goToIndex(4) 
+
+// Navigate to the 2nd entry from the current position
+navigationHistory.goToOffset(2)
+```
+
+
+Here's a full example that you can open with Electron Fiddle:
+```fiddle docs/latest/fiddles/features/navigation-history
+```
@@ -63,6 +63,7 @@ module.exports = {
         },
         'latest/tutorial/multithreading',
         'latest/tutorial/native-file-drag-drop',
+        'latest/tutorial/navigation-history',
         'latest/tutorial/notifications',
         'latest/tutorial/offscreen-rendering',
         'latest/tutorial/online-offline-events',