-
-
Notifications
You must be signed in to change notification settings - Fork 25
Plugins꞉ 1. The basics
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.
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.
The metadata file contains information about the plugin, which is displayed in the Plugins window and used for compatibility checking.
[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| 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. |
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.
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.
JavaScript file that is executed in the popup notification window.
run(){
// executed every time a new notification is displayed
}Do not create any global variables or functions, as every time a new notification is shown, the entire page is reloaded.
| App Documentation | 1. User interface | 2. Notifications | 3. Plugins | 4. Advanced |
| Plugin Development |
1. The basics | 2. Global functions | 3. Bridge object | 4. Remote functions | 5. Browser window | 6. Notification window |
| Miscellaneous | Send anonymous data | Supported systems | Troubleshooting |