Plugins꞉ 1. The basics

All unofficial plugins are placed in <installation folder>/plugins/user. Each plugin is a folder that contains a .meta file describing the plugin, browser.js and/or notification.js with JavaScript code which runs in the respective environment, and any other resources you want to ship with the plugin such as styles and default configuration. This is called the root folder.

When a plugin interacts with the file system, TweetDuck automatically creates a data folder inside which the plugin can freely write and read files, and which can be also exported and imported as part of the user profile. It is also possible to read files from the root folder.

Tips

View the official plugin source codes for working examples, however note that the .meta file structure is different between official and unofficial plugins.

When debugging a plugin, download dev tools to use the JavaScript console in the app.

---

.meta

The metadata file contains information about the plugin, which is displayed in the Plugins window and used for compatibility checking.

Example .meta File

[name]
Example plugin

[description]
This is an example plugin.
It does stuff.

[author]
chylex

[version]
1.0

[website]
https://chylex.com

[configfile]
configuration.js

[configdefault]
resources/configuration.default.js

[requires]
1.2.3

List of Tags

Tag	Presence	Information
name	required	Should use sentence case as shown in the example.
description	suggested	May have multiple lines, but only 3 lines will be displayed without a scroll bar.
version	suggested	Should be short, otherwise no restrictions on the format.
configfile	optional	Points to a file in the data folder. Use / to separate folders in the path. When present, a Configure button in the Plugins window opens Windows Explorer with the file highlighted.
configdefault	optional	Points to a file in the root folder. Use / to separate folders in the path. When both this and configfile are present, TweetDuck will copy this file to the location of configfile.
requires	optional	Specifies the minimum version of TweetDuck required to run the plugin.

---

browser.js

This file is a script that runs in the main browser window.

constructor(){
  super({
    // reloads page when manually enabled or disabled; not recommended, as it's
    // always better when a plugin can be toggled seamlessly without reloading,
    // but the option is available if needed (default: false)
    requiresPageReload: true
  });
}

enabled(){
  // runs immediately after constructor if the plugin is enabled (can modify the
  // head tag or add overlay elements to the body tag), or when manually enabled
  // in the program

  // prepare variables and functions, create stylesheets
}

ready(){
  // runs once the main app (.js-app div element) is displayed (the columns
  // themselves may not be loaded yet); will also be called immediately after
  // enabled() if the plugin is manually enabled after the page has loaded

  // modify the contents as the page has finished loading, add event listeners
}

configure(){
  // if this method is present, the plugin will have a 'Configure' button
  // in the UI, which calls this method when clicked (requires version 1.13+)

  // you may use the configfile tag alongside configure(), in which case this
  // method takes precedence over the default behavior of opening Windows Explorer
}

disabled(){
  // runs when the plugin is manually disabled in the program

  // remove event listeners and revert everything to original state
  // not necessary to use this if 'requiresPageReload' is set to true
}

All methods are optional. If you implement constructor(), please DO NOT run any code in it besides the super call with plugin settings, since the constructor runs even when the plugin is disabled.

Tips

Please, make sure your plugin is functional when disabled and re-enabled in the program. If it's not possible to support seamless disable(), use the requiresPageReload property to force a page reload.

Save any persistent data as soon as possible, as the user may close the app or reload the browser anytime, which immediately stops all plugin execution.

Starting from version 1.8, all properties of the plugin object are deleted when the plugin is seamlessly disabled. If you want to persist some data when the plugin is disabled and re-enabled, use the $$ prefix (for example this.$$property = 10). Of course, if the browser is reloaded at any point, this data will be lost.

---

notification.js

This file is a script that runs in the notification popup window.

constructor(){
  super({
    // currently no options
  });
}

run(){
  // runs every time a new notification is displayed
}

Implementing constructor() is not necessary as there are currently no options plugins can use.

Tips

Do not create global variables or functions since the entire page is regenerated, and all plugins are reconstructed every time a new notification is displayed.

View the full collection of tips.