starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[PR #4720] [CLOSED] Introducing Tour Guide to the audio book shelf web application #4327

New Issue
Closed
opened 2026-04-25 00:19:17 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:17 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/4720
Author: @Laknima
Created: 10/5/2025
Status: ❌ Closed

Base: master ← Head: lw526_tourGuide

📝 Commits (4)

  • ee3fa2f Install sheperdjs and create tour giude in project.
  • 7fc572a Add tour guide for home page and library page.create enable feature in setting file.
  • 36aa344 Remove reset first visit tour button used for testing.
  • 7592ccf Merge branch 'master' into lw526_tourGuide

📊 Changes

15 files changed (+4521 additions, -4854 deletions)

View changed files

📝 client/assets/defaultStyles.css (+17 -0)
📝 client/components/app/Appbar.vue (+70 -8)
📝 client/components/app/SideRail.vue (+170 -6)
📝 client/nuxt.config.js (+3 -3)
📝 client/package-lock.json (+2461 -3410)
📝 client/package.json (+2 -0)
📝 client/pages/config/index.vue (+17 -0)
📝 client/pages/item/_id/index.vue (+26 -6)
📝 client/pages/library/_library/index.vue (+3 -0)
➕ client/plugins/tour.js (+190 -0)
➕ client/public/images/audioBookShelf.png (+0 -0)
➕ docs/frankenstein_07_shelley_64kb/frankenstein_07_shelley_64kb.mp3 (+0 -0)
➕ docs/nistspecialpublication800-144/nistspecialpublication800-144.pdf (+0 -0)
📝 package-lock.json (+1554 -1420)
📝 server/objects/settings/ServerSettings.js (+8 -1)

📄 Description

Brief summary

Implemented a tour to enhance onboarding and navigation foe web application. The tour is enabled automatically on new users and can subsequently be accessed by a floating action button (FAB) within the bottom right of the screen. The tour now runs on two screens (Home and Library). A slider with images to provide more descriptive directions is included within each step, and the tour will always be closable. A new settings config option to enable or disable the tour-enabled or disabled FAB is now available.

In-depth Description

Frontend Modifications:

Plugins/tour.js (exported startTour) initializes/launches Shepherd tours of the app (appBar) and library (.

The tour auto-starts the first time a user visits (checked via localStorage.tourGuideVisited). After auto-starting the appBar tour, it sets that flag so the tour doesn’t reappear automatically.

Floating Action Button (FAB) is in siderails.vue (bottom-right). A popup menu with choices (Home Tour, Library Tour) is displayed on click. The FAB only reveals itself if the tour feature enabled in settings.

Each Shepherd popup now contains:

A progress bar of the current step.

An image slider (previous/next) by which each step can display several images/examples.

Standard Shepherd navigation (Back / Next / Done) and a Cancel icon to close at any time.

Steps are safely added:
For libraryItem tour the code pauses and waits for DOM elements to exist (polling interval) before adding steps and commencing to prevent missing attach targets.
The assistant verifies that we add a step only if the attach To.element exists (avoids runtime error).

BACKEND

Added enableTourGuide to ServerSettings to store the setting to the server settings json held by Sequelize.

Constructor defaults and construct() logic Verify that:

New installations (no DB field exists) will be defaulted to enabled (true).

If DB already holds a value, that value is not overwritten.

toJSON() includes enableTourGuide so that the frontend gets the value through the current /api/server/settings workflow.

The Frontend Settings page (config/index.vue) has a ui-toggle-switch that listens to newServerSettings.enableTourGuide and updates using the existing updateServerSettings dispatch (so toggle gets persisted to DB).

How have you tested this?

followed black box testing as well along with the unit test.
Tested all the functionalities relevant to the tour guide and did regression testing to ensure the existing functionalities working fproperly.

Screenshots

collapsed FAB Home tour midddle with backand next with progress bar Home tour Open FAB SettingsTour enableand disable tour in library

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/4720 **Author:** [@Laknima](https://github.com/Laknima) **Created:** 10/5/2025 **Status:** ❌ Closed **Base:** `master` ← **Head:** `lw526_tourGuide` --- ### 📝 Commits (4) - [`ee3fa2f`](https://github.com/advplyr/audiobookshelf/commit/ee3fa2f42708928d4b24b497810eaefcb467cec3) Install sheperdjs and create tour giude in project. - [`7fc572a`](https://github.com/advplyr/audiobookshelf/commit/7fc572a3a2404ada1f4263f2ef83eae6c4f25d93) Add tour guide for home page and library page.create enable feature in setting file. - [`36aa344`](https://github.com/advplyr/audiobookshelf/commit/36aa3443add88b3030da792100bfec1968a63770) Remove reset first visit tour button used for testing. - [`7592ccf`](https://github.com/advplyr/audiobookshelf/commit/7592ccf690e64f24704d52e2a1ded26084cfe744) Merge branch 'master' into lw526_tourGuide ### 📊 Changes **15 files changed** (+4521 additions, -4854 deletions) <details> <summary>View changed files</summary> 📝 `client/assets/defaultStyles.css` (+17 -0) 📝 `client/components/app/Appbar.vue` (+70 -8) 📝 `client/components/app/SideRail.vue` (+170 -6) 📝 `client/nuxt.config.js` (+3 -3) 📝 `client/package-lock.json` (+2461 -3410) 📝 `client/package.json` (+2 -0) 📝 `client/pages/config/index.vue` (+17 -0) 📝 `client/pages/item/_id/index.vue` (+26 -6) 📝 `client/pages/library/_library/index.vue` (+3 -0) ➕ `client/plugins/tour.js` (+190 -0) ➕ `client/public/images/audioBookShelf.png` (+0 -0) ➕ `docs/frankenstein_07_shelley_64kb/frankenstein_07_shelley_64kb.mp3` (+0 -0) ➕ `docs/nistspecialpublication800-144/nistspecialpublication800-144.pdf` (+0 -0) 📝 `package-lock.json` (+1554 -1420) 📝 `server/objects/settings/ServerSettings.js` (+8 -1) </details> ### 📄 Description <!-- For Work In Progress Pull Requests, please use the Draft PR feature, see https://github.blog/2019-02-14-introducing-draft-pull-requests/ for further details. If you do not follow this template, the PR may be closed without review. Please ensure all checks pass. If you are a new contributor, the workflows will need to be manually approved before they run. --> ## Brief summary Implemented a tour to enhance onboarding and navigation foe web application. The tour is enabled automatically on new users and can subsequently be accessed by a floating action button (FAB) within the bottom right of the screen. The tour now runs on two screens (Home and Library). A slider with images to provide more descriptive directions is included within each step, and the tour will always be closable. A new settings config option to enable or disable the tour-enabled or disabled FAB is now available. ## In-depth Description Frontend Modifications: # Plugins/tour.js (exported startTour) initializes/launches Shepherd tours of the app (appBar) and library (. The tour auto-starts the first time a user visits (checked via localStorage.tourGuideVisited). After auto-starting the appBar tour, it sets that flag so the tour doesn’t reappear automatically. # Floating Action Button (FAB) is in siderails.vue (bottom-right). A popup menu with choices (Home Tour, Library Tour) is displayed on click. The FAB only reveals itself if the tour feature enabled in settings. # Each Shepherd popup now contains: # A progress bar of the current step. # An image slider (previous/next) by which each step can display several images/examples. # Standard Shepherd navigation (Back / Next / Done) and a Cancel icon to close at any time. Steps are safely added: For libraryItem tour the code pauses and waits for DOM elements to exist (polling interval) before adding steps and commencing to prevent missing attach targets. The assistant verifies that we add a step only if the attach To.element exists (avoids runtime error). BACKEND # Added enableTourGuide to ServerSettings to store the setting to the server settings json held by Sequelize. # Constructor defaults and construct() logic Verify that: New installations (no DB field exists) will be defaulted to enabled (true). If DB already holds a value, that value is not overwritten. toJSON() includes enableTourGuide so that the frontend gets the value through the current /api/server/settings workflow. The Frontend Settings page (config/index.vue) has a ui-toggle-switch that listens to newServerSettings.enableTourGuide and updates using the existing updateServerSettings dispatch (so toggle gets persisted to DB). ## How have you tested this? followed black box testing as well along with the unit test. Tested all the functionalities relevant to the tour guide and did regression testing to ensure the existing functionalities working fproperly. ## Screenshots <img width="1945" height="903" alt="collapsed FAB" src="https://github.com/user-attachments/assets/50b4b517-7d65-45a4-b45d-8be80ab42a49" /> <img width="1918" height="902" alt="Home tour midddle with backand next with progress bar" src="https://github.com/user-attachments/assets/52074a17-34f7-4676-85d8-218131acc7ff" /> <img width="1908" height="932" alt="Home tour" src="https://github.com/user-attachments/assets/32cf93a1-2946-414a-ac6c-fec4fd7c2a80" /> <img width="1945" height="910" alt="Open FAB" src="https://github.com/user-attachments/assets/b5a82642-b672-401c-9f9d-d13e62257f9a" /> <img width="1918" height="920" alt="SettingsTour enableand disable" src="https://github.com/user-attachments/assets/21d156be-bb48-47a4-a75b-8bdab4412d08" /> <img width="1917" height="927" alt="tour in library" src="https://github.com/user-attachments/assets/94409a84-9456-4e1d-9d28-7917fd6795e9" /> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:17 +02:00
adam closed this issue 2026-04-25 00:19:18 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#4327
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?