Firefish Plugins: Documentation and Sample Code

Firefish is an ActivityPub based social media platform with a growing community and a focus on 👯‍♂️ fun and 🎨 creativity.

Quick References #

• What is AiScript
• AiScript Syntax
• AiScript Common Functions
• Misskey Specific Functions
• Firefish API Documentation
• Creating a Firefish Plugin
• Plugin Development Tips
• Curated Resource Links
• Sample Plugins

Plugins Overview #

• The Difference Between Plugins and Widgets
• How Plugins Work
• Plugin Examples
• How to Install a Plugin
• Building You Own Plugins

One of the many unique features Firefish provides is the ability to apply plugins to the instance's website. A few ways plugins can be used to affect your Firefish experience:

• Alter notes displayed in your feed
• Add a new feature to the post submission dialog
• Add a new feature to the notes action items
• Add a new feature to the profile action items

Plugins are created by the community base and installed by each end user as desired. It would also be technically possible for each instance to load plugins for all users by default, but I've not seen this occur.

Each plugin affects the user's experience on the official Firefish instance's website and the installed progressive web app based on the same site.

Plugins are saved to your browser's local storage. They stick around even after logging out and loggin back in. They are removed when you clear your browser's cache or your delete them within your Settings > Plugins section. They don't automatically follow you to logins on a different browser or a different device.

You CAN save your scripts to a local file and/or to your Firefish instance by backing up your Firefish Preferences, found in Settings > Preferences backups. This preference backup can then be restored or loaded on other devices!

The preferences backup includes more than just your plugins, consisting of your custom css, themes and other preferences you've configured.

The Difference Between Plugins and Widgets #

Widgets offer a deeper integration with Firefish than Plugins. Widgets can alter the layout of the site itself, reach out to external sites to gather and display data (rss feeds, weather, etc.). Because of this, they require review, approval and installation by the instance's admins. Firefish offers a default set, but instances can create their own or remove the defaults from their sets if they so desire.

Widgets are often more fully featured than a specific Plugin. Plugins, however, add a level of customization for the individual user that wouldn't be available through Widgets.

How Plugins Work #

Plugins are written in a language called AiScript. AiScript provides access to a small sub-set of javascript features like variables, constants, strings, arrays, etc. AiScript is configured to only allow changes to the objects that are passed into the handlers, such as note, post or profiles objects. Firefish has a few additional functions that have been made accessible to AiScript for end users:

• Using the Firefish Api
• Displaying Dialog Boxes
• Displaying Confirmation Boxes
• Opening files from a Firefish media drive
• Saving objects to local storage
• Loading objects from local storage
• Opening a Url in a separate window

Currently there are two major versions of AiScript. Ones that were built with AiScript version 0.12 or lower and those built higher versions. Breaking changes occurred at that point. Firefish is currently running version 0.11.1 and scripts built with newer versions will not work out of the box.

Firefish Plugin Examples #

How to install a plugin #

First you need to find some plugins to install. I've got a few I have created in the list above, and even more from the community on the Firefish Snippets Collection.

NOTE: Only install plugins from a trusted source. ONLY install plugins from a TRUSTED source! 🚨 ONLY INSTALL PLUGINS FROM A TRUSTED SOURCE! 🚨 🙏🏽

Got it? Good.

• Copy the code from one of these plugins to your clipboard.
• On your Firefish instance website, click Settings, then Plugins.
• Paste the code into the textarea.
• Click install

A few things may happen next.

• On success, it will show a check mark, the reload the page (it will be empty)
• If the plugin requires access to the Firefish Api, you'll be prompted to accept those permissions before the plugin will be enabled.
• On a failure to save, it will most likely show a syntax error dialog without much else to help out.

If you aren't following my guidance and just downloading random plugins that aren't curated by a trusted source, note that many of these plugins won't work on Firefish. They were created for MissKey, which has upgraded their Plugin feature that makes them incompatible with Calckey's version.

If it was succesful, click on the Settings -> Plugins item in the menu again, and the Plugins page will reload with your newly installed Plugin appearing in the list!

You'll see a few properties and options listed:

• The name, version and author of your plugin as provided by the author.
• A description of the plugin.

Permissions display any specific permissions that the plugin has requested to access the Firefish API. Pay attention to this, and take caution if you see anything other than "read:" permissions listed. If any permissions are listed, ensure you have a good understanding of what the plugin is supposed to do.

Activate Enabled by default, you can disable the plugin so you still have it available, but it's not turned on and affecting your content.

Settings Depending on the plugin installed, there may be a "Settings" button. Clicking it will bring up Plugin specific settings as presribed by the plugin itself. You may have to configure settings before the plugin works.

Uninstall This uninstalls the plugin completely and it will no longer be available on your local browser instance (until you re-install). Note that if you have Preference Backups with this plugin included, it will get re-installed when you load the backup.

Building You Own Plugins #

Want to learn more? Great! Dig deeper with the following guides:

• Understanding AiScript
• Creating a Plugin
• Tips for Plugin Development
• Curated Development References