500 lines
14 KiB
XML
500 lines
14 KiB
XML
import type Shepherd from "shepherd.js";
|
|
import {
|
|
addDatasetCounter,
|
|
encapsulateElements,
|
|
removeAllDatasetCounters,
|
|
renderInContainer,
|
|
} from "../utilities.js";
|
|
|
|
const step01 = renderInContainer(
|
|
<>
|
|
<h1>The Homepage</h1>
|
|
|
|
<p>
|
|
If you plan on staying a while, this is likely the place you'll see the
|
|
most. So let's work our way top to bottom, left to right.
|
|
</p>
|
|
|
|
<p>Starting with...</p>
|
|
</>,
|
|
);
|
|
|
|
const step02 = renderInContainer(
|
|
<>
|
|
<h1>The Main Header</h1>
|
|
|
|
<p>
|
|
On the left there is the Tildes logo and title, which you can click to get
|
|
back to the homepage, or refresh it if you're already there. If you are in
|
|
a group, the group name will also be shown.
|
|
</p>
|
|
|
|
<p>
|
|
On the right is the notifications section and your username. When you have
|
|
unread messages and/or are mentioned, they will show up next to your
|
|
username. If you don't have any notifications right now, you can{" "}
|
|
<a href="#" onClick={toggleMockNotifications}>
|
|
click here
|
|
</a>{" "}
|
|
to show a preview of what they look like.
|
|
</p>
|
|
|
|
<p>
|
|
At the moment mentions only work in comments, so if you get mentioned in a
|
|
topic's text body and don't get a notification,{" "}
|
|
<a target="_blank" href="https://gitlab.com/tildes/tildes/-/issues/195">
|
|
that's why
|
|
</a>
|
|
.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
// 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
|
|
// actual Tildes HTML code.
|
|
// https://gitlab.com/tildes/tildes/-/blob/0dbb031562cd9297968fec0049af4b833ef77301/tildes/tildes/templates/macros/user.jinja2#L9-20
|
|
function toggleMockNotifications(event: Event): void {
|
|
// Prevent the click from going through so the anchor isn't removed.
|
|
event.preventDefault();
|
|
|
|
const root = document.querySelector("#site-header .logged-in-user-info");
|
|
function toggle(existingSelector: string, href: string, text: string): void {
|
|
const existing =
|
|
root?.querySelector<HTMLElement>(existingSelector) ?? undefined;
|
|
if (existing === undefined) {
|
|
// If no notifiaction exists, render our mock.
|
|
const messageNotification = document.createElement("a");
|
|
const count = 1 + Math.ceil(Math.random() * 10);
|
|
messageNotification.classList.add("logged-in-user-alert");
|
|
messageNotification.dataset.tildesShepherdMock = "true";
|
|
messageNotification.href = href;
|
|
messageNotification.textContent = `${count} ${text}`;
|
|
root?.insertAdjacentElement("beforeend", messageNotification);
|
|
} else if (existing.dataset.tildesShepherdMock === "true") {
|
|
// If a notification exists and it has our mock attribute, remove it.
|
|
existing.remove();
|
|
} else {
|
|
// A real message notification already exists, so we do nothing.
|
|
}
|
|
}
|
|
|
|
toggle('[href="/messages/unread"]', "/messages/unread", "new messages");
|
|
toggle(
|
|
'[href="/notifications/unread"]',
|
|
"/notifications/unread",
|
|
"new comments",
|
|
);
|
|
}
|
|
|
|
const step03 = renderInContainer(
|
|
<>
|
|
<h1>The Listing Options</h1>
|
|
|
|
<p>
|
|
Right below the main header are the topic listing options. These determine
|
|
how the topics in the listing are sorted and{" "}
|
|
<em>
|
|
<b>from</b> what period
|
|
</em>{" "}
|
|
topics should be shown.
|
|
</p>
|
|
|
|
<p>
|
|
The non-activity sorts are the easiest to explain, so let's start with
|
|
them:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<b>Votes</b> sorts topics with the most votes first.
|
|
</li>
|
|
<li>
|
|
<b>Comments</b> sorts them with the most comments first.
|
|
</li>
|
|
<li>
|
|
And <b>New</b> sorts them by their date, so newest topics first.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Then the first <b>Activity</b> will sort topics by bumping topics up as
|
|
they receive comments, however this sort makes use of comment labels.
|
|
</p>
|
|
|
|
<p>
|
|
If you don't know what comment labels are yet, don't worry, there is 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
|
|
specific intention. If you'd like to read more, check out{" "}
|
|
<a
|
|
target="_blank"
|
|
href="https://docs.tildes.net/instructions/commenting-on-tildes#labelling-comments"
|
|
>
|
|
the documentation
|
|
</a>
|
|
.
|
|
</p>
|
|
|
|
<p>
|
|
And finally the <b>All activity</b> sorts topics the same as Activity, but
|
|
without taking into account any comment labels.
|
|
</p>
|
|
|
|
<p>
|
|
If you only want to see topics from a certain period, click on the "from"
|
|
dropdown and select your period. Aside from a set of predefined options,
|
|
you can also set a custom one by clicking the "other period" option, after
|
|
which you'll be prompted for it.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
const step04 = renderInContainer(
|
|
<>
|
|
<h1>The Topic Listing</h1>
|
|
|
|
<p>
|
|
Next up, just below the listing options is the topic listing itself. We've
|
|
only highlighted the first topic here, but you can probably see it
|
|
continues all the way down the page.
|
|
</p>
|
|
|
|
<p>Here, we've marked the main elements of the topic:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
The topic title, when the topic is a "text topic" links to the same
|
|
place as the comments link does. Otherwise when it's a "link topic", it
|
|
will link to an external site.
|
|
</li>
|
|
|
|
<li>
|
|
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
|
|
enabled in your user settings, they will be shown after the group name.
|
|
A "topic type" may also be shown to indicate whether the topic is a text
|
|
topic, a video, an "ask" topic for recommendations or a survey, etc.
|
|
</li>
|
|
|
|
<li>
|
|
The amount of comments the topic has received. If any new comments have
|
|
been posted since you last viewed the topic, in orange a "(X new)" will
|
|
be added.
|
|
</li>
|
|
|
|
<li>
|
|
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
|
|
together with that website's icon. For topics posted automatically by
|
|
Tildes itself, it will be "Scheduled topic".
|
|
</li>
|
|
</ol>
|
|
|
|
<p>The list continues on the next page.</p>
|
|
</>,
|
|
);
|
|
|
|
const step05 = renderInContainer(
|
|
<>
|
|
<h1>The Topic Listing continued</h1>
|
|
|
|
<ol start={5}>
|
|
<li>
|
|
The date when the topic was posted. For dates that are pretty recent it
|
|
will show something like "X days ago" while for longer dates it will be
|
|
the exact date, like "April 26th, 2021".
|
|
</li>
|
|
|
|
<li>
|
|
The voting button, clicking it will add your vote to the topic. On
|
|
Tildes, once the topic is older than 30 days you can no longer vote on
|
|
it and the individual voting data for is removed, with only the total
|
|
count kept. You can read more about it in{" "}
|
|
<a target="_blank" href="https://tild.es/jhm">
|
|
this announcement topic
|
|
</a>
|
|
.
|
|
</li>
|
|
|
|
<li>
|
|
And finally the topic actions. Clicking on the "Actions" button will
|
|
show a dropdown including "Bookmark", "Ignore this topic" and if you
|
|
have been granted the permission for it, "Edit title". Ignoring the
|
|
topic will remove it from the topic listing and prevent any future
|
|
notifications from happening. Both your bookmarked and ignored topics
|
|
can be found in their respective sections on your profile.
|
|
</li>
|
|
</ol>
|
|
</>,
|
|
);
|
|
|
|
const step06 = renderInContainer(
|
|
<>
|
|
<h1>The Sidebar</h1>
|
|
|
|
<p>
|
|
Let's take a look at the sidebar, where the first thing we're greeted with
|
|
is the search bar.
|
|
</p>
|
|
|
|
<p>
|
|
A quick note for mobile use, the sidebar can opened via a button that
|
|
appears in the very top-right of the page.
|
|
</p>
|
|
|
|
<p>
|
|
When searching from the homepage, topics will be included from any group.
|
|
However, searching when inside a group will only include topics from that
|
|
group and any sub-groups.
|
|
</p>
|
|
|
|
<p>
|
|
Below the search bar you will also find the title of the page, or name of
|
|
the group, and a small description. The sidebar has more elements when in
|
|
you're in a group page, but those are touched upon in the groups tour.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
const step07 = renderInContainer(
|
|
<>
|
|
<h1>The Sidebar Subscriptions</h1>
|
|
|
|
<p>
|
|
Moving on, you'll find the list of groups you are subscribed to and a
|
|
button below it to go to the groups listing, where you can find all the
|
|
that are available.
|
|
</p>
|
|
|
|
<p>
|
|
To post a topic, subscribe or unsubscribe from any group, go to the group
|
|
in question and in the sidebar there will be buttons to do so.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
const step08 = renderInContainer(
|
|
<>
|
|
<h1>The Sidebar User Settings</h1>
|
|
|
|
<p>
|
|
At the bottom of the sidebar you will find some user settings.
|
|
Specifically the filtered topics tags you have set and a link to the
|
|
settings page.
|
|
</p>
|
|
|
|
<p>
|
|
When you have filtered topics tags set, any topics with any of the tags
|
|
present will be removed from your listing. You can read more about it by
|
|
going to the dedicated page for it by clicking the "Edit filtered tags"
|
|
button.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
const step09 = renderInContainer(
|
|
<>
|
|
<h1>The Footer</h1>
|
|
|
|
<p>
|
|
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
|
|
places, such as the Tildes Documentation, Contact page, the source code,
|
|
etc. We highly recommend reading through the documentation as it explains
|
|
a lot of the how and why Tildes does certain things.
|
|
</p>
|
|
|
|
<p>
|
|
As for the theme selector, you can change your theme with a number of
|
|
options. When you change it here, it will only change for the current
|
|
device, if you'd like to set an account default for all devices, head to
|
|
your account settings.
|
|
</p>
|
|
</>,
|
|
);
|
|
|
|
const step10 = renderInContainer(
|
|
<>
|
|
<h1>This is the end, beautiful friend</h1>
|
|
|
|
<p>And that's the end of the Homepage tour!</p>
|
|
|
|
<p>
|
|
As always, if you find any bugs, have feature requests or simply want to
|
|
ask a question. Please send us a message at{" "}
|
|
<a target="_blank" href="https://tildes.net/user/Community">
|
|
@Community
|
|
</a>
|
|
.
|
|
</p>
|
|
|
|
<p>Happy Tildying!~</p>
|
|
</>,
|
|
);
|
|
|
|
export const steps: Shepherd.Step.StepOptions[] = [
|
|
{
|
|
id: "homepage-01",
|
|
text: step01,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: "#site-header",
|
|
on: "bottom",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-02",
|
|
scrollTo: true,
|
|
text: step02,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: "main > .listing-options",
|
|
on: "bottom",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-03",
|
|
text: step03,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: ".topic-listing > li:first-child",
|
|
on: "bottom",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-04",
|
|
text: step04,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: ".topic-listing > li:first-child",
|
|
on: "bottom",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-05",
|
|
text: step05,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: '#sidebar [data-tildes-shepherd-encapsulated="homepage-06"]',
|
|
on: "left-start",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-06",
|
|
text: step06,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: '#sidebar [data-tildes-shepherd-encapsulated="homepage-07"]',
|
|
on: "left-start",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-07",
|
|
scrollTo: true,
|
|
text: step07,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: "#sidebar .divider + .nav",
|
|
on: "left-start",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-08",
|
|
scrollTo: true,
|
|
text: step08,
|
|
},
|
|
{
|
|
attachTo: {
|
|
element: "#site-footer",
|
|
on: "top",
|
|
},
|
|
canClickTarget: false,
|
|
id: "homepage-09",
|
|
scrollTo: true,
|
|
text: step09,
|
|
},
|
|
{
|
|
canClickTarget: false,
|
|
id: "homepage-10",
|
|
text: step10,
|
|
},
|
|
];
|
|
|
|
export const eventHandlers: TourStepEventHandler[] = [
|
|
[
|
|
"homepage-04",
|
|
[
|
|
"show",
|
|
() => {
|
|
const topic = ".topic-listing > li:first-child";
|
|
const counters = [
|
|
".topic-title",
|
|
".topic-metadata",
|
|
".topic-info-comments",
|
|
".topic-info-source",
|
|
"time",
|
|
".topic-voting",
|
|
".topic-actions",
|
|
];
|
|
|
|
for (const [count, selector] of counters.entries()) {
|
|
addDatasetCounter(`${topic} ${selector}`, count + 1);
|
|
}
|
|
},
|
|
],
|
|
],
|
|
[
|
|
"homepage-05",
|
|
[
|
|
"destroy",
|
|
() => {
|
|
removeAllDatasetCounters();
|
|
},
|
|
],
|
|
],
|
|
[
|
|
"homepage-05",
|
|
[
|
|
"show",
|
|
() => {
|
|
encapsulateElements(
|
|
"homepage-06",
|
|
"#sidebar .sidebar-controls",
|
|
"afterend",
|
|
["#sidebar .form-search", "#sidebar h2", "#sidebar p"],
|
|
);
|
|
},
|
|
],
|
|
],
|
|
[
|
|
"homepage-06",
|
|
[
|
|
"show",
|
|
() => {
|
|
encapsulateElements("homepage-07", "#sidebar .divider", "beforebegin", [
|
|
"#sidebar .nav",
|
|
'#sidebar [href="/groups"',
|
|
]);
|
|
},
|
|
],
|
|
],
|
|
[
|
|
"homepage-08",
|
|
[
|
|
"show",
|
|
() => {
|
|
const filteredTags =
|
|
document.querySelector<HTMLDetailsElement>("#sidebar details") ??
|
|
undefined;
|
|
if (filteredTags === undefined) {
|
|
console.warn("Element is unexpectedly undefined");
|
|
return;
|
|
}
|
|
|
|
filteredTags.open = true;
|
|
},
|
|
],
|
|
],
|
|
];
|