JavaScript API¶

In this section we talk about the JavaScript API and how to repackage these files for your project

Division of Files¶

In order to reduce the size of your web page, this project has been divided into a modular architecture. Each fediverse implementation has its own plugin to parse data, and the top level “glue script” serves partly as a redirect and partly as a common renderer.

Glue Script¶

View source code here on GitHub!

Note

This requires DOMPurify to be loaded on your site

fedi_script.setConfig(newValues)¶

Setter for internal configuration properties

Warning

Call this function before any other with the value 'boostLink' as a key, or your boost icon may not work in subdirectories

Available properties to set:

boostLink - The URL corresponding to the boost SVG
allowCustomEmoji - Allow custom emoji to be included in comment contents (privacy)
allowSensitiveEmoji - Allow sensitive emoji to be included in comment contents
allowMediaAttachments - Allow media attachments to be included in comment contents (privacy)
allowAvatars - Force avatars to not be loaded (privacy)
delayCommentLoad - Defers loading of comments section until user brings it into view
defaultReactionEmoji - The reaction to use when it is not supported or undefined
retryDelay - The amount of time to wait upon rate-limit error (in ms)
parser - In testing, allows you to replace the DOMParser

Arguments:

newValues (Object)

fedi_script.fetchComments(fediFlavor, fediInstance, postId, maxDepth)¶

This function kicks off the whole comment fetching process

Calls:

fetchMeta()
fetchSubcomments()
renderCommentsBatch()

Arguments:

fediFlavor (fedi_script.FediverseFlavor)
fediInstance (String)
postId (String)
maxDepth (Number)

fedi_script.fetchMeta(fediFlavor, fediInstance, postId)¶

A redirect function that will call the relevant plugin’s implementation. This will update the global comment stats.

Calls:

fedi_script_mastodon.fetchMetaMastodon()
fedi_script_misskey.fetchMetaMisskey()

Callers:

fetchComments()

Arguments:

fediFlavor (fedi_script.FediverseFlavor)
fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

fedi_script.fetchSubcomments(fediFlavor, fediInstance, postId)¶

A redirect function that will call the relevant plugin’s implementation. This will return comment objects following the common comment return spec.

Calls:

fedi_script_mastodon.fetchSubcommentsMastodon()
fedi_script_misskey.fetchSubcommentsMisskey()

Callers:

fetchComments()

Arguments:

fediFlavor (fedi_script.FediverseFlavor)
fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

Returns:

Array.<Comment> – The resulting subComment()s

fedi_script.replaceEmoji(string, emojis)¶

Takes in an HTML string with embedded custom emoji, and returns a sanitized, parsed DOM fragment incuding the images those emoji shortcodes reference.

Calls:

DOMPurify.sanitize()

Callers:

renderComment()

Arguments:

string (String) – The HTML string to parse
emojis (fedi_script.EmojiDescriber) – The shortcodes you expect to see

Returns:

DOMFragment – The sanitized, parsed document fragment

fedi_script.renderComment(comment)¶

Calls:

replaceEmoji()

Callers:

renderCommentsBatch()

Arguments:

comment (fedi_script.Comment)

Returns:

DOMFragment – The rendered version of the comment

fedi_script.renderCommentsBatch(comments)¶

Renders a batch of comments, in chronological order including nesting

Calls:

renderComment()

Callers:

fetchComments()

Arguments:

comments (Array.<Comment>) – An array of Comment()s

class fedi_script.FediverseFlavor()¶: A string matching one of the supported fediverse implementations: ‘mastodon’ or ‘misskey’

class fedi_script.Comment()¶

The common comment return type

Arguments:

id (String) – The comment ID
replyId (String) – The parent comment ID
url (String) – The link to the comment (either on your instance or remote host)
date (String) – The original post date (not accounting for edits)
cw (String|null) – Either text containing a content warning, or null
reactionCount (Number) – The number of reactions on the comment
boostCount (Number) – The number of times the comment was boosted or quoted
content (String) – The unsanitized HTML content of the comment (may change to DOM fragment)
reactions (Object) – A mapping of emoji (unicode or custom) to the number of reactions on a comment
emoji (fedi_script.EmojiDescriber) – Emoji used in the post
reactionEmoji (fedi_script.EmojiDescriber) – Emoji used in reactions (mix of unicode emoji & custom names)
user (fedi_script.User) – Information about the posting user
media (Array.<MediaAttachment>) – An array of MediaAttachment()s

class fedi_script.EmojiDescriber()¶: A mapping of names to URLs. All properties involved are strings.

class fedi_script.MediaAttachment()¶

Arguments:

url (String) – The link to the full size image
sensitive (boolean) – A marker of image sensitivity (Misskey can set this individually)
description (String) – The alt text of the image

class fedi_script.User()¶

Arguments:

url (String) – The link to the user’s profile
host (String) – The user’s instance domain
handle (String) – The user’s fediverse handle
name (String) – The user’s name (often with embedded emoji)
avatar (String) – The user’s profile picture
emoji (fedi_script.EmojiDescriber) – Emoji used in the user’s name/description

Mastodon Plugin¶

View source code here on GitHub!

fedi_script_mastodon.extractCommentMastodon(fediInstance, comment)¶

This will transform the information returned by the Mastodon API into the common comment structure.

Callers:

fetchSubcommentsMastodon()

Arguments:

fediInstance (String) – The domain name of your fedi instance
comment (String) – The ID of the comment you are fetching metadata for

Returns:

fedi_script.Comment –

fedi_script_mastodon.fetchMetaMastodon(fediInstance, postId)¶

The Mastodon implementation of fetchMeta(). This will update the global comment stats.

Callers:

fedi_script.fetchMeta()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

fedi_script_mastodon.fetchSubcommentsMastodon(fediInstance, postId)¶

The Mastodon implementation of fetchSubcomments(). This will return comment objects following the common comment return spec.

Callers:

fedi_script.fetchSubcomments()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

Returns:

Array.<Comment> – The resulting subComment()s

fedi_script_mastodon.queryUserMastodon(fediInstance, handle)¶

This function returns the URL and instance type of a given Fedi user

Warning

This function is under construction and should be considered unstable

Arguments:

fediInstance (String) – The domain name of your fedi instance
handle (String) – The user handle you’re looking for

Returns:

Object –

Misskey Plugin¶

View source code here on GitHub!

Note

This plugin requires marked.js to be loaded on your site

fedi_script_misskey.extractCommentMisskey(fediInstance, comment)¶

This will transform the information returned by the Misskey API into the common comment structure.

Calls:

transformMFM()
marked.parse()

Callers:

fetchSubcommentsMisskey()

Arguments:

fediInstance (String) – The domain name of your fedi instance
comment (String) – The ID of the comment you are fetching metadata for

Returns:

fedi_script.Comment –

fedi_script_misskey.fetchMisskeyEmoji(fediInstance, name)¶

A subcomponenet of extractCommentMisskey(). Because emoji information is not included in the comment information returned by the API, it needs to be fetched separately. This is done in parallel and handles any rate-limit feedback.

Callers:

extractCommentMisskey()

Arguments:

fediInstance (String) – The domain name of your fedi instance
name (String) – The emoji shortcode you are trying to fetch

fedi_script_misskey.fetchMetaMisskey(fediInstance, postId)¶

The Misskey implementation of fetchMeta(). This will update the global comment stats.

Calls:

fetchMeta1Misskey()
fetchMeta2Misskey()

Callers:

fedi_script.fetchMeta()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

fedi_script_misskey.fetchMeta1Misskey(fediInstance, postId)¶

A subcomponenet of fetchMetaMisskey(). This portion handles the global reaction count.

Callers:

fetchMetaMisskey()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

fedi_script_misskey.fetchMeta2Misskey(fediInstance, postId)¶

A subcomponenet of fetchMetaMisskey(). This portion handles the global boost/renote count.

Callers:

fetchMetaMisskey()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

fedi_script_misskey.fetchSubcommentsMisskey(fediInstance, postId)¶

The Misskey implementation of fetchSubcomments(). This will return comment objects following the common comment return spec.

Calls:

extractCommentMisskey()

Arguments:

fediInstance (String) – The domain name of your fedi instance
postId (String) – The ID of the post you are fetching metadata for

Returns:

Array.<Comment> – The resulting subComment()s

fedi_script_misskey.transformMFM(text, fediInstance)¶

Transforms as much of MFM as possible into standard Markdown through regular expressions

Note

This is very much not a full implementation of Misskey Flavored Markdown, but it supports a wide enough subset that it should work for >95% of comments

Calls:

escapeHtml()
parseBorders()

Callers:

extractCommentMisskey()

Arguments:

text (String)
fediInstance (String)

Returns:

String – An unsanitized Markdown string to be parsed later

fedi_script_misskey.escapeHtml(unsafe)¶

A basic HTML escape function for the <plain> element (not intended to sanitize)

Callers:

transformMFM()

Arguments:

unsafe (String)

Returns:

String –

fedi_script_misskey.parseBorders(_, style, text)¶

A helper function to parse the border markup in Misskey Flavored Markdown

Callers:

transformMFM()

Arguments:

_ (String)
style (String)
text (String)

Returns:

String –

fedi_script_misskey.queryUserMisskey(fediInstance, handle)¶

This function returns the URL and instance type of a given Fedi user

Warning

This function is under construction and should be considered unstable

Arguments:

fediInstance (String) – The domain name of your fedi instance
handle (String) – The user handle you’re looking for

Returns:

Object –

Minimal Page Infrastructure¶

These scripts require a small number of elements on your page in order to function. The minimal structure is:

<h{{ section_level }}>
    {{ section_title }}
    <span class="comments-info">
        <img class="fedi-icon" src="{{ html_baseurl }}/_static/boost.svg" alt="Boosts">
        <span id="global-reblogs"></span>,
        <img class="fedi-icon" src="{{ html_baseurl }}/_static/like.svg" alt="Likes">
        <span id="global-likes"></span>
    </span>
</h{{ section_level }}>
<div id="comments-section"></div>
<script>
    document.addEventListener("DOMContentLoaded", function () {
        setFediConfig({
            boostLink: "{{ html_baseurl }}/_static/boost.svg",
        });
        fetchComments(
            '{{ fedi_flavor }}', '{{ fedi_instance }}', '{{ post_id }}', {{ fetch_depth }}
        );
    });
</script>

Note

This structure is mostly stable, but it may be subject to change in later versions if (for example) we want to add support for hosting on multiple instances simultaneously

JavaScript API¶

Division of Files¶

Glue Script¶

Mastodon Plugin¶

Misskey Plugin¶

Minimal Page Infrastructure¶

Table of Contents

Previous topic

Next topic

This Page