tildes-community/tildes-shepherd
tildes-community
/
tildes-shepherd
1
Fork 0
Code

Render the steps before the tour starts. 

By defining the steps as consts in the top level they were
being initialized immediately as the page loads. By having
them initialized in a function it will correctly have access
to everything on the page and not render steps of tours
we aren't going to start.
This commit is contained in:
Bauke 2023-07-03 14:11:46 +02:00
parent e4dbe14e59
commit 548984a6df
Signed by: Bauke
GPG Key ID: C1C0F29952BCF558
5 changed files with 529 additions and 509 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
source/content-scripts/setup.ts
View File

@ -131,7 +131,7 @@ function startTour(data: TourData, runMainAgainAfterComplete: boolean): void {
// For every step we have, add it to the tour and subsequently add all the // For every step we have, add it to the tour and subsequently add all the
// event handlers to that step. // event handlers to that step.
for (const [stepNumber, stepOptions] of data.steps.entries()) { for (const [stepNumber, stepOptions] of data.steps().entries()) {
// If the final step doesn't have buttons defined, set the "Continue" button // If the final step doesn't have buttons defined, set the "Continue" button
// text to "Finish". // text to "Finish".
if ( if (

12
source/tours/interface/account-settings.tsx
View File

@ -1,18 +1,22 @@
import {type TourData, TourId} from "../types.js"; import {type TourData, TourId} from "../types.js";
import {renderInContainer} from "../utilities.js"; import {renderInContainer} from "../utilities.js";
const step01 = renderInContainer( function renderSteps(): ReturnType<TourData["steps"]> {
const step01 = renderInContainer(
<> <>
<h1>Your Account Settings</h1> <h1>Your Account Settings</h1>
</>, </>,
); );
const steps: TourData["steps"] = [ return [
{ {
id: "account-settings-01", id: "account-settings-01",
text: step01, text: step01,
}, },
]; ];
}
const steps: TourData["steps"] = renderSteps;
const eventHandlers: TourData["eventHandlers"] = []; const eventHandlers: TourData["eventHandlers"] = [];

169
source/tours/interface/homepage.tsx
View File

@ -7,7 +7,8 @@ import {
renderInContainer, renderInContainer,
} from "../utilities.js"; } from "../utilities.js";
const step01 = renderInContainer( function renderSteps(): ReturnType<TourData["steps"]> {
const step01 = renderInContainer(
<> <>
<LoggedOutWarning /> <LoggedOutWarning />
@ -20,22 +21,22 @@ const step01 = renderInContainer(
<p>Starting with...</p> <p>Starting with...</p>
</>, </>,
); );
const step02 = renderInContainer( const step02 = renderInContainer(
<> <>
<h1>The Main Header</h1> <h1>The Main Header</h1>
<p> <p>
On the left there is the Tildes logo and title, which you can click to get On the left there is the Tildes logo and title, which you can click to
back to the homepage, or refresh it if you're already there. If you are in get back to the homepage, or refresh it if you're already there. If you
a group, the group name will also be shown next to it. are in a group, the group name will also be shown next to it.
</p> </p>
<p> <p>
On the right is the notifications section and your username. When you have On the right is the notifications section and your username. When you
unread messages and/or are mentioned, they will show up next to the left have unread messages and/or are mentioned, they will show up next to the
of it. If you don't have any notifications right now, you can{" "} left of it. If you don't have any notifications right now, you can{" "}
<a href="#" onClick={toggleMockNotifications}> <a href="#" onClick={toggleMockNotifications}>
click here click here
</a>{" "} </a>{" "}
@ -43,28 +44,32 @@ const step02 = renderInContainer(
</p> </p>
<p> <p>
At the moment mentions only work in comments, so if you get mentioned in a At the moment mentions only work in comments, so if you get mentioned in
topic's text body and don't get a notification,{" "} a topic's text body and don't get a notification,{" "}
<a target="_blank" href="https://gitlab.com/tildes/tildes/-/issues/195"> <a target="_blank" href="https://gitlab.com/tildes/tildes/-/issues/195">
that's why that's why
</a> </a>
. .
</p> </p>
</>, </>,
); );
// Toggle mock notifications, based on the code in the following link. // Toggle mock notifications, based on the code in the following link.
// If the logic for this needs to be updated, also update the permalink to the // If the logic for this needs to be updated, also update the permalink to the
// actual Tildes HTML code. // actual Tildes HTML code.
// https://gitlab.com/tildes/tildes/-/blob/0dbb031562cd9297968fec0049af4b833ef77301/tildes/tildes/templates/macros/user.jinja2#L9-20 // https://gitlab.com/tildes/tildes/-/blob/0dbb031562cd9297968fec0049af4b833ef77301/tildes/tildes/templates/macros/user.jinja2#L9-20
function toggleMockNotifications(event: Event): void { function toggleMockNotifications(event: Event): void {
// Prevent the click from going through so the anchor isn't removed. // Prevent the click from going through so the anchor isn't removed.
event.preventDefault(); event.preventDefault();
const root = document.querySelector("#site-header .logged-in-user-info"); const root = document.querySelector("#site-header .logged-in-user-info");
/* Generic function to toggle a mock notification. */ /* Generic function to toggle a mock notification. */
function toggle(existingSelector: string, href: string, text: string): void { function toggle(
existingSelector: string,
href: string,
text: string,
): void {
const existing = const existing =
root?.querySelector<HTMLElement>(existingSelector) ?? undefined; root?.querySelector<HTMLElement>(existingSelector) ?? undefined;
if (existing === undefined) { if (existing === undefined) {
@ -90,16 +95,16 @@ function toggleMockNotifications(event: Event): void {
"/notifications/unread", "/notifications/unread",
"new comments", "new comments",
); );
} }
const step03 = renderInContainer( const step03 = renderInContainer(
<> <>
<h1>The Listing Options</h1> <h1>The Listing Options</h1>
<p> <p>
Right below the main header are the topic listing options. These determine Right below the main header are the topic listing options. These
how the topics in the listing are sorted and from what period topics determine how the topics in the listing are sorted and from what period
should be shown. topics should be shown.
</p> </p>
<p> <p>
@ -121,14 +126,15 @@ const step03 = renderInContainer(
</ul> </ul>
<p> <p>
Then the first <b>Activity</b> sort will sort topics by bumping topics up Then the first <b>Activity</b> sort will sort topics by bumping topics
as they receive comments, however this sort makes use of comment labels. up as they receive comments, however this sort makes use of comment
labels.
</p> </p>
{/* TODO: When the comment labels tour is made, change the prose. */} {/* TODO: When the comment labels tour is made, change the prose. */}
<p> <p>
If you don't know what comment labels are yet, don't worry, there will be If you don't know what comment labels are yet, don't worry, there will
a tour that explains them. But in short they are a community tool to be a tour that explains them. But in short they are a community tool to
emphasize and de-emphasize comments, similar to votes but with more emphasize and de-emphasize comments, similar to votes but with more
specific intention. If you'd like to read more, check out{" "} specific intention. If you'd like to read more, check out{" "}
<a <a
@ -146,21 +152,21 @@ const step03 = renderInContainer(
</p> </p>
<p> <p>
If you only want to see topics from a certain period, click on the "from" If you only want to see topics from a certain period, click on the
dropdown and select the period you want. Aside from a set of predefined "from" dropdown and select the period you want. Aside from a set of
options, you can also set a custom one by clicking the "other period" predefined options, you can also set a custom one by clicking the "other
option, after which you'll be prompted to input it. period" option, after which you'll be prompted to input it.
</p> </p>
</>, </>,
); );
const step04 = renderInContainer( const step04 = renderInContainer(
<> <>
<h1>The Topic Listing</h1> <h1>The Topic Listing</h1>
<p> <p>
Next up, just below the listing options is the topic listing itself. We've Next up, just below the listing options is the topic listing itself.
only highlighted the first topic here, but you can probably see it We've only highlighted the first topic here, but you can probably see it
continues all the way down the page. continues all the way down the page.
</p> </p>
@ -169,45 +175,46 @@ const step04 = renderInContainer(
<ol> <ol>
<li> <li>
The topic title, when the topic is a "text topic" it links to the same The topic title, when the topic is a "text topic" it links to the same
place as the comments link does. Otherwise when it's a "link topic", it place as the comments link does. Otherwise when it's a "link topic",
will link to an external site. it will link to an external site.
</li> </li>
<li> <li>
The topic metadata, which by default includes the group it's in. If a The topic metadata, which by default includes the group it's in. If a
topic has specific notable tags and you have the "show tags" setting topic has specific notable tags and you have the "show tags" setting
enabled in your user settings, they will be shown after the group name. enabled in your user settings, they will be shown after the group
A "topic type" may also be shown to indicate whether the topic is a text name. A "topic type" may also be shown to indicate whether the topic
topic, a video, an "ask" topic for recommendations or a survey, etc. is a text topic, a video, an "ask" topic for recommendations or a
survey, etc.
</li> </li>
<li> <li>
The amount of comments the topic has received. If any new comments have The amount of comments the topic has received. If any new comments
been posted since you last viewed the topic, in orange a "(X new)" will have been posted since you last viewed the topic, in orange a "(X
be added. new)" will be added.
</li> </li>
<li> <li>
The topic source. For text topics this is always the poster of the The topic source. For text topics this is always the poster of the
topic, but for link topics in certain groups it will be the domain name topic, but for link topics in certain groups it will be the domain
together with that website's icon. For topics automatically posted by name together with that website's icon. For topics automatically
Tildes itself, it will say "Scheduled topic". posted by Tildes itself, it will say "Scheduled topic".
</li> </li>
</ol> </ol>
<p>The list continues on the next page.</p> <p>The list continues on the next page.</p>
</>, </>,
); );
const step05 = renderInContainer( const step05 = renderInContainer(
<> <>
<h1>The Topic Listing continued</h1> <h1>The Topic Listing continued</h1>
<ol start={5}> <ol start={5}>
<li> <li>
The date when the topic was posted. For dates that are pretty recent it The date when the topic was posted. For dates that are pretty recent
will show something like "X days ago" while for longer dates it will be it will show something like "X days ago" while for longer dates it
the exact date, like "April 26th, 2021". will be the exact date, like "April 26th, 2021".
</li> </li>
<li> <li>
@ -231,15 +238,15 @@ const step05 = renderInContainer(
</li> </li>
</ol> </ol>
</>, </>,
); );
const step06 = renderInContainer( const step06 = renderInContainer(
<> <>
<h1>The Sidebar</h1> <h1>The Sidebar</h1>
<p> <p>
Let's take a look at the sidebar, where the first thing we're greeted with Let's take a look at the sidebar, where the first thing we're greeted
is the search bar. with is the search bar.
</p> </p>
<p> <p>
@ -248,21 +255,22 @@ const step06 = renderInContainer(
</p> </p>
<p> <p>
When searching from the homepage, topics will be included from any group. When searching from the homepage, topics will be included from any
However, searching when inside a group will only include topics from that group. However, searching when inside a group will only include topics
group and any of its sub-groups. from that group and any of its sub-groups.
</p> </p>
{/* TODO: Update the prose once the groups tour is created. */} {/* TODO: Update the prose once the groups tour is created. */}
<p> <p>
Below the search bar you will also find the title of the page, or name of Below the search bar you will also find the title of the page, or name
the group, and a small description. The sidebar has more elements when in of the group, and a small description. The sidebar has more elements
you're in a group page, but those will be touched upon in the groups tour. when in you're in a group page, but those will be touched upon in the
groups tour.
</p> </p>
</>, </>,
); );
const step07 = renderInContainer( const step07 = renderInContainer(
<> <>
<h1>The Sidebar: Subscriptions</h1> <h1>The Sidebar: Subscriptions</h1>
@ -273,14 +281,14 @@ const step07 = renderInContainer(
</p> </p>
<p> <p>
To post a topic, subscribe or unsubscribe from any group, go to the group To post a topic, subscribe or unsubscribe from any group, go to the
page in question and in its sidebar there will be buttons to do all those group page in question and in its sidebar there will be buttons to do
things. all those things.
</p> </p>
</>, </>,
); );
const step08 = renderInContainer( const step08 = renderInContainer(
<> <>
<h1>The Sidebar: User Settings</h1> <h1>The Sidebar: User Settings</h1>
@ -300,18 +308,18 @@ const step08 = renderInContainer(
button. button.
</p> </p>
</>, </>,
); );
const step09 = renderInContainer( const step09 = renderInContainer(
<> <>
<h1>The Footer</h1> <h1>The Footer</h1>
<p> <p>
And finally, the very last part of the homepage is the footer. Here you And finally, the very last part of the homepage is the footer. Here you
will find a theme selector (more on that in a moment) and various links to will find a theme selector (more on that in a moment) and various links
places, such as the Tildes Documentation, Contact page, the source code, to places, such as the Tildes Documentation, Contact page, the source
etc. We highly recommend reading through the documentation as it explains code, etc. We highly recommend reading through the documentation as it
a lot of the how and why Tildes does certain things. explains a lot of the how and why Tildes does certain things.
</p> </p>
<p> <p>
@ -324,9 +332,9 @@ const step09 = renderInContainer(
. .
</p> </p>
</>, </>,
); );
const step10 = renderInContainer( const step10 = renderInContainer(
<> <>
<h1>This is the end, beautiful friend</h1> <h1>This is the end, beautiful friend</h1>
@ -343,9 +351,9 @@ const step10 = renderInContainer(
<p>Happy Tildying!~</p> <p>Happy Tildying!~</p>
</>, </>,
); );
const steps: TourData["steps"] = [ return [
{ {
id: "homepage-01", id: "homepage-01",
text: step01, text: step01,
@ -431,7 +439,10 @@ const steps: TourData["steps"] = [
id: "homepage-10", id: "homepage-10",
text: step10, text: step10,
}, },
]; ];
}
const steps: TourData["steps"] = renderSteps;
const eventHandlers: TourData["eventHandlers"] = [ const eventHandlers: TourData["eventHandlers"] = [
{ {

43
source/tours/introduction.tsx
View File

@ -2,18 +2,20 @@ import {fromStorage, StorageKey} from "../storage/common.js";
import {TourId, type TourData} from "./types.js"; import {TourId, type TourData} from "./types.js";
import {openOptionsPageFromBackground, renderInContainer} from "./utilities.js"; import {openOptionsPageFromBackground, renderInContainer} from "./utilities.js";
const step01 = renderInContainer( function renderSteps(): ReturnType<TourData["steps"]> {
const step01 = renderInContainer(
<> <>
<h1>Thank you for installing Tildes Shepherd!</h1> <h1>Thank you for installing Tildes Shepherd!</h1>
<p> <p>
Tildes Shepherd is a set of interactive guided tours for Tildes to show Tildes Shepherd is a set of interactive guided tours for Tildes to show
you around and introduce you to the concepts that make this website great. you around and introduce you to the concepts that make this website
great.
</p> </p>
<p> <p>
To see and start the tours that are available, click on the extension icon To see and start the tours that are available, click on the extension
to go to the options page or{" "} icon to go to the options page or{" "}
<a href="#" onClick={openOptionsPageFromBackground}> <a href="#" onClick={openOptionsPageFromBackground}>
click here now click here now
</a> </a>
@ -26,30 +28,30 @@ const step01 = renderInContainer(
forward, backward or exit it. forward, backward or exit it.
</p> </p>
</>, </>,
); );
const step02 = renderInContainer( const step02 = renderInContainer(
<> <>
<h1>Tour Mechanics</h1> <h1>Tour Mechanics</h1>
<p> <p>
During the tours at various points we will want to highlight specific During the tours at various points we will want to highlight specific
areas. When that happens you won't be able to click anything inside them, areas. When that happens you won't be able to click anything inside
mainly to prevent you from accidentally going to a different page and them, mainly to prevent you from accidentally going to a different page
interrupting the tour. But also to prevent you from taking actions you and interrupting the tour. But also to prevent you from taking actions
maybe don't want to take, like voting on something you don't necessarily you maybe don't want to take, like voting on something you don't
want to vote on. necessarily want to vote on.
</p> </p>
<p> <p>
Depending on your selected theme, the highlighted areas will have a yellow Depending on your selected theme, the highlighted areas will have a
or orange border and some extra added whitespace. As you can see in this yellow or orange border and some extra added whitespace. As you can see
example where the main site header has been highlighted. in this example where the main site header has been highlighted.
</p> </p>
</>, </>,
); );
const step03 = renderInContainer( const step03 = renderInContainer(
<> <>
<p> <p>
If you find any bugs, have feature requests or simply want to ask a If you find any bugs, have feature requests or simply want to ask a
@ -80,9 +82,9 @@ const step03 = renderInContainer(
<p>Happy Tildying!~</p> <p>Happy Tildying!~</p>
</>, </>,
); );
const steps: TourData["steps"] = [ return [
{ {
canClickTarget: false, canClickTarget: false,
id: "introduction-01", id: "introduction-01",
@ -123,7 +125,10 @@ const steps: TourData["steps"] = [
id: "introduction-03", id: "introduction-03",
text: step03, text: step03,
}, },
]; ];
}
const steps: TourData["steps"] = renderSteps;
const eventHandlers: TourData["eventHandlers"] = []; const eventHandlers: TourData["eventHandlers"] = [];

4
source/tours/types.ts
View File

@ -50,8 +50,8 @@ export type TourData = {
/** The requirements this tour must match before starting it. */ /** The requirements this tour must match before starting it. */
requirements: TourRequirement; requirements: TourRequirement;
/** All the steps this tour will take. */ /** A function that returns all the steps this tour will take. */
steps: Shepherd.Step.StepOptions[]; steps: () => Shepherd.Step.StepOptions[];
/** The title of the tour for use in the options page. */ /** The title of the tour for use in the options page. */
title: string; title: string;