Plugins꞉ 3. Bridge object

Both browser.js and notification.js have access to a special object called $TDP, which has several functions that communicate directly with TweetDuck. These functions can also access the file system, which cannot be normally done in pure JavaScript.

All bridge functions require the plugin's randomly generated token which can be retrieved using this.$token, and return a Promise object which uses callbacks to process the output and handle exceptions.

Call .then(func) on the Promise object to add a success callback (function that takes the output, if there is any), and .catch(func) to add an error callback (function that takes an Error object).

Note: Don't forget when using this.$token, that this may have a different meaning based on the context.

---

Messages & Prompts

TODO upcoming update

---

File Manipulation

Each plugin has a read-only root folder with metadata, scripts, and any additional files placed there by the plugin developer, and a both readable and writable data folder for storing settings and state.

All paths have to be relative to the plugin's root or data folder, otherwise the functions throw an exception. The functions will also throw exceptions if the IO operation fails, so it's a good idea to use .catch(func) and show the user an error message if that happens.

---

Creating / Writing Files

Signature	promise<void> writeFile(token, path, contents)
Since	1.3.1

Creates or overwrites a file, including any directories on the path that don't exist.

Examples

$TDP.writeFile(this.$token, "data/hello_world.txt", "Hello World!").then(() => {
  $TD.alert("info", "File was written successfully!");
}).catch(err => {
  $TD.alert("error", "Problem creating or writing file: "+err.message);
});

---

Reading Files

Signature	promise<string> readFile(token, path, cache)
Since	1.3.1

Signature	promise<string> readFileRoot(token, path)
Since	1.5

Reads the file contents as a string. Will throw an exception if the file or directory does not exist. The readFileRoot version will always use cache.

Parameters

• cache - true to use internal file cache to retrieve the contents without re-reading the file

Caution

In version 1.3.1, the function did not have a cache parameter, plus caching was broken in general. The issue was fixed in 1.3.2.

Examples

$TDP.readFile(this.$token, "data/hello_world.txt", true).then(contents => {
  $TD.alert("info", "File contents: "+contents);
}).catch(err => {
  $TD.alert("error", "Problem reading file: "+err.message);
});

---

Deleting Files

Signature	promise<void> deleteFile(token, path)
Since	1.3.1

Examples

$TDP.deleteFile(this.$token, "data/hello_world.txt").then(() => {
  $TD.alert("info", "File was successfully deleted.");
}).catch(err => {
  $TD.alert("error", "Problem deleting file: "+err.message);
});

---

Checking File Existence

Signature	promise<bool> checkFileExists(token, path)
Since	1.3.3

Signature	promise<bool> checkFileExistsRoot(token, path)
Since	1.5

Caution

The function will only throw an exception if the path is invalid. If the file exists but an IO or permission error happens, it will pass false to the Promise object instead of triggering the exception.

Examples

$TDP.checkFileExists(this.$token, "data/hello_world.txt").then(exists => {
  $TD.alert("info", exists ? "File exists!" : "File does not exist!");
}).catch(err => {
  $TD.alert("warning", "Problem checking file's existence: "+err.message);
});

---

Injecting HTML Into Notifications

Signature	promise<void> injectIntoNotificationsBefore(token, key, search, html)
Since	1.7

Signature	promise<void> injectIntoNotificationsAfter(token, key, search, html)
Since	1.7

When modifying the DOM inside notification.js, it may take a short amount of time which causes a visible update a split second after a notification is displayed. To remedy that, a plugin can use these functions to insert their own HTML into the notification before it's shown, for example by calling it from browser.js after the plugin configuration is loaded.

Each injection has a unique string key which identifies it (if the same key is used twice, the old injection will be replaced). Keys are only unique within the context of each individual plugin.

When an injection is applied, the search property is used to find where the html should be inserted. If search is empty, it will count as the beginning of the notification HTML. Note that only the first occurrence will be updated.

To view the HTML structure of the notification contents, see example.html. The contents are placed into a simple generated HTML structure which can be viewed in TweetNotification.cs.

There is no guarantee on the order of injections (the only guarantee is that injections of each individual plugin will be applied in a single batch). When a plugin is disabled, all of its injections will be removed.

Examples

$TDP.injectIntoNotificationsBefore(this.$token, "css", "</head>", [
  "<style type='text/css'>",
  ".avatar { border-radius: 0 !important }",
  "</style>"
].join(""));