Plugins꞉ 1. The basics

Daniel Chýlek edited this page Aug 18, 2018 · 14 revisions

All unofficial plugins are stored in <installation folder>/plugins/user, which can be accessed by opening the Plugins window and clicking Open Plugin Folder.

Each plugin has its own folder, which is called the root folder and serves as a unique identifier. The folder should only use lowercase letters, numbers, and hyphens, for example my-1st-plugin. When distributing the plugin, it's recommended to create a .zip archive with the folder and a README file with installation instructions (TODO: make an example plugin).

The root folder must contain 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 default configuration or large data files. This folder is strictly read-only.

When a plugin interacts with the file system, TweetDuck creates a data folder where the plugin can freely write and read both files and folders. The data folders of all plugins can be exported/imported as part of the user profile, if the Plugin Data item is selected.

Tips

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

Use the Dev Tools to debug your plugin, see console output, and explore the TweetDeck code. If you haven't selected Install dev tools while installing TweetDuck, download the app again and install it into the same folder as your current installation.

Whenever specifying the name of a file or folder in the .meta file or in JavaScript, do not use uppercase letters, and always use / to separate folders.


.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.
website optional Displayed as a clickable link.
configfile optional Points to a file in the data folder. 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. When both configdefault and configfile are present, this file will be copied to the location of configfile on first run.
requires optional Specifies the minimum version of TweetDuck required to run the plugin.

browser.js

JavaScript file that is executed in the main browser window.

constructor(){
  super({
    // whether to reload the browser window when enabled or disabled;
    // it's always better when a plugin can be toggled without reloading,
    // but the option is available if needed (default: false)
    requiresPageReload: false
  });
}

enabled(){
  // executed immediately after constructor if the plugin is enabled,
  // or later if the plugin is enabled manually

  // only the <head> tag and the main .js-app elements are guaranteed to exist

  // load configuration, define variables and functions,
  // create custom styles, modify {{mustache}} templates
}

ready(){
  // executed once the app layout is generated,
  // or immediately after enabled() if the plugin is enabled manually later

  // the TweetDeck accounts, settings, and column list are available
  // most of the website layout is generated, but column contents are still loading

  // add event listeners, modify the sidebar,
  // inject your code into TweetDeck functions
}

configure(){
  // if present, the plugin will have a 'Configure' button which calls this method

  // if used alongside the 'configfile' meta tag, this method will take precedence
  // over the default behavior of opening Windows Explorer
}

disabled(){
  // executed when the plugin is manually disabled
  // omit if you set 'requiresPageReload' to true

  // remove custom elements and event listeners,
  // revert {{mustache}} templates and injected functions
}

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. Use enabled() to define variables and functions, otherwise they may be deleted.

Tips

Please, make sure your plugin is functional when disabled and re-enabled in the program. If you modify a mustache, it will most likely not update if the plugin is enabled after TweetDeck has already loaded. In this case, check whether TD.ready is true in enabled(), and modify the elements manually (see example).

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.

After a plugin is disabled, all properties of the object are deleted. If you absolutely must persist some data for 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.

View additional tips


notification.js

JavaScript file that is executed in the popup notification window.

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

Tips

Do not create any global variables or functions, as every time a new notification is shown, the entire page is reloaded.

View additional tips

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.