Rich Text
By default, when you create a post, @skyware/bot
parses your post’s text to identify any mentions, hashtags, and URLs. However, in some cases, you may want more control over how a post is displayed. The RichText class provides a convenient interface for constructing a post containing rich text.
Usage
To start, import the RichText
class from @skyware/bot
:
import { class RichText
Used to build a rich text string with facets.RichText } from "@skyware/bot";
You can then build a rich text string as follows:
const const richText: RichText
richText = new new RichText(): RichText
Used to build a rich text string with facets.RichText()
.RichText.text(substr: string): RichText
Append a string.text("Hey, check out this library: ")
.RichText.link(substr: string, uri?: string | undefined): RichText
Append a link.
You can use the uri
parameter to specify a different URI than the substr
.link("https://skyware.js.org")
.RichText.text(substr: string): RichText
Append a string.text("! ")
.RichText.tag(tag: string): RichText
Append a tag.tag("#atdev");
await const bot: Bot
bot.Bot.post(payload: PostPayload, options?: BotPostOptions | undefined): Promise<PostReference>
Create a post.post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.text: const richText: RichText
richText })
You’ll notice that the Bot#post
method can accept either RichText
or a string. Your post will look something like:
Mentions
When you’re manually constructing RichText
, mentioning a user requires you to know the user’s handle and DID. You can then use the mention
method to add a mention to your post:
const const richText: RichText
richText = new new RichText(): RichText
Used to build a rich text string with facets.RichText()
.RichText.text(substr: string): RichText
Append a string.text("Hey, ")
.RichText.mention(handle: string, did: string): RichText
Append a mention.mention("@skyware.js.org", "did:plc:ith6w2xyj2qy3rcvmlsem6fz")
.RichText.text(substr: string): RichText
Append a string.text("!");
await const bot: Bot
bot.Bot.post(payload: PostPayload, options?: BotPostOptions | undefined): Promise<PostReference>
Create a post.post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.text: const richText: RichText
richText })
Note that the DID provided could differ from the mentioned handle — a mention is really just a hyperlink! Use this power for good.
Hyperlinks
Speaking of hyperlinks, mentions aren’t the only way to have text act as a link. The .link
method we previously used can also take two parameters: text and a URL.
const const richText: RichText
richText = new new RichText(): RichText
Used to build a rich text string with facets.RichText()
.RichText.text(substr: string): RichText
Append a string.text("Hey, check out ")
.RichText.link(substr: string, uri?: string | undefined): RichText
Append a link.
You can use the uri
parameter to specify a different URI than the substr
.link("Skyware", "https://skyware.js.org")
.RichText.text(substr: string): RichText
Append a string.text("!");
await const bot: Bot
bot.Bot.post(payload: PostPayload, options?: BotPostOptions | undefined): Promise<PostReference>
Create a post.post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.text: const richText: RichText
richText })
Detecting facets yourself
Alternatively, the RichText
class contains a detectFacets static method that will handle detecting all mentions, links, and tags, and automatically resolve mentions to DIDs.
The post
method and others such as reply
and quote
will automatically detect facets for you if you pass a string. However, if you want to detect facets from an existing string but exclude certain facets, the RichText.detectFacets
method offers greater control.
const const text: "Hey, @skyware.js.org! #atdev"
text = "Hey, @skyware.js.org! #atdev";
const const facets: Main[]
facets = await class RichText
Used to build a rich text string with facets.RichText.RichText.detectFacets(text: string, bot: Bot): Promise<Main[]>
Returns a RichText instance with all facets (mentions, links, tags, etc) resolved.detectFacets(const text: "Hey, @skyware.js.org! #atdev"
text, const bot: Bot
bot);
await const bot: Bot
bot.Bot.post(payload: PostPayload, options?: BotPostOptions | undefined): Promise<PostReference>
Create a post.post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.text, PostPayload.facets?: Main[] | undefined
A facet represents a range within the post's text that has special meaning
(e.g. mentions, links, tags). Prefer to use the
{@link
RichText
}
class to create
posts with facets.facets });
You must pass your bot
instance in to RichText.detectFacets
so that it can resolve mentions. If you pass facets
into post
, only those facets will be used.
Moving on
You may notice that adding a link to a post doesn’t automatically add an embedded preview. Learn more about that in Embeds and Images!