some proper info
Zack
parent
ee396b913e
commit
c21a820d5b
|
|
@ -1,8 +1,274 @@
|
|||
[Example plugin](https://gist.github.com/rauenzi/e5f4d02fc3085a53872b0236cd6f8225)
|
||||
# Overview
|
||||
|
||||
Discord is an electron app, essentially a browser, so plugins are just JavaScript.
|
||||
1. BandagedBD plugins are limited to a single file.
|
||||
2. The file must be named as `pluginname.plugin.js`, the plugin name can be whatever you want.
|
||||
3. Plugin files require a special header ([see below](#plugins-require-a-special-header)).
|
||||
4. The name defined in the header must match the variable/classname
|
||||
5. Plugins must implement the [following functions](#required-functions): `getName`, `getDescription`, `getVersion`, `getAuthor`, `start` and `stop`.
|
||||
Optionally, you may implement `load` and `observer`. More details on each function below.
|
||||
6. Plugins can make use of the [`BdApi`](#bdapi) object described [below](#bdapi).
|
||||
7. Plugins can make use of any node modules or Discord modules (through webpack).
|
||||
|
||||
You can open the developer tools with
|
||||
# Details
|
||||
|
||||
* Windows: `Ctrl` + `Shift` + `i`
|
||||
* MacOS: `Cmd` + `Alt` + `i`
|
||||
Take a look at this [Example](https://gist.github.com/rauenzi/e5f4d02fc3085a53872b0236cd6f8225) for a template and description of each required and optional function.
|
||||
|
||||
## Plugins require a special header
|
||||
|
||||
BandagedBD requires one line at the beginning of a plugin file to identify it:
|
||||
|
||||
```js
|
||||
//META{"name":"testPlugin"}*//
|
||||
```
|
||||
|
||||
Be sure that `testPlugin` matches the variable name defined in the file. Without this, your plugin will not be identified by BD properly and will not show up in the list.
|
||||
|
||||
Optionally you can also include a website and source field in the meta like this example from ImageToClipboard:
|
||||
|
||||
```js
|
||||
//META{"name":"ImageToClipboard","website":"https://github.com/rauenzi/BetterDiscordAddons","source":"https://github.com/rauenzi/BetterDiscordAddons/tree/master/Plugins/ImageToClipboard"}*//
|
||||
```
|
||||
|
||||
## Required Functions
|
||||
|
||||
#### `getName()`
|
||||
The name for the plugin to be displayed to the user in the plugins page and for internal settings to use.
|
||||
|
||||
**@Returns** `{string}` - the name for the plugin.
|
||||
|
||||
***
|
||||
|
||||
#### `getDescription()`
|
||||
The description of the plugin shown in the plugins page.
|
||||
|
||||
**@Returns** `{string}` - the description of the plugin.
|
||||
|
||||
***
|
||||
|
||||
#### `getVersion()`
|
||||
The version of the plugin displayed in the plugins page.
|
||||
|
||||
**@Returns** `{string}` - the version of the plugin.
|
||||
|
||||
***
|
||||
|
||||
#### `getAuthor()`
|
||||
The author string for the plugin displayed in the plugins page.
|
||||
|
||||
**@Returns** `{string}` - the author of the plugin.
|
||||
|
||||
***
|
||||
|
||||
#### `start()`
|
||||
Called when the plugin is enabled or when it is loaded and was previously reloaded (such as discord start or reload).
|
||||
|
||||
***
|
||||
|
||||
#### `stop()`
|
||||
Called when the plugin is disabled.
|
||||
|
||||
***
|
||||
|
||||
|
||||
## Optional Functions
|
||||
|
||||
These functions can be useful but aren't necessary for the plugin to load and function.
|
||||
|
||||
#### `load()`
|
||||
Called when the plugin is loaded regardless of if it is enabled or disabled.
|
||||
|
||||
***
|
||||
|
||||
#### `observer(changes)`
|
||||
Called on every mutation that occurs on the `document`. For more information on observers and mutations take a look at [MDN's documentation](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`changes`|[MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord)|The mutation that occurred.|
|
||||
|
||||
***
|
||||
|
||||
|
||||
# BdApi
|
||||
|
||||
The following functions are available as a part of the `BdApi` object.
|
||||
|
||||
## Properties
|
||||
|
||||
#### `React`
|
||||
The [React](http://reactjs.org/) module being used inside Discord.
|
||||
|
||||
***
|
||||
|
||||
#### `ReactDOM`
|
||||
The [ReactDOM](https://reactjs.org/docs/react-dom.html) module being used inside Discord.
|
||||
|
||||
***
|
||||
|
||||
## Methods
|
||||
|
||||
#### `alert(title, content)`
|
||||
Creates an shows an alert modal to the user. A preview of how it may look can be found [here](https://i.zackrauen.com/7qnnNC.png).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`title`|string|The title to show on the modal.|
|
||||
|`content`|string|Content to show in the modal (can be html string).|
|
||||
|
||||
***
|
||||
|
||||
#### `clearCSS(id)`
|
||||
Removes a style added with [`injectCSS`](#injectcssid-css) below.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`id`|string|ID of the node to remove.|
|
||||
|
||||
***
|
||||
|
||||
#### `findModule(filter)`
|
||||
Searches for an internal Discord webpack module based on `filter`.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`filter`|function|A function to use to filter modules.|
|
||||
|
||||
**@Returns** `{any|null}` - the module found or null if none were found.
|
||||
|
||||
***
|
||||
|
||||
#### `findAllModules(filter)`
|
||||
Searches for multiple internal Discord webpack module based on `filter`. It's the same as [`findModule`](#findmodulefilter) but will return all matches
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`filter`|function|A function to use to filter modules.|
|
||||
|
||||
**@Returns** `{Array<any>}` - the modules found or null if none were found.
|
||||
|
||||
***
|
||||
|
||||
#### `findModuleByProps(...props)`
|
||||
Searches for an internal Discord webpack module that has every property passed.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`props`|...string|A series of properties to check for.|
|
||||
|
||||
**@Returns** `{any|null}` - the module found or null if none were found.
|
||||
|
||||
***
|
||||
|
||||
#### `getCore()`
|
||||
Returns BandagedBD's instance of the core module. Only use this if you know what you are doing.
|
||||
|
||||
**@Returns** `{Core}` - BBD's instantiated core module.
|
||||
|
||||
***
|
||||
|
||||
#### `getInternalInstance(node)`
|
||||
Gets the internal react instance for a particular node.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`node`|HTMLElement|jQuery|Node to find the react instance for.|
|
||||
|
||||
**@Returns** `{object|undefined}` - the instance if found or undefined otherwise.
|
||||
|
||||
***
|
||||
|
||||
#### `getPlugin(name)`
|
||||
Gets the instance of another plugin with the name `name`.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`name`|string|Name of the plugin to retreive.|
|
||||
|
||||
**@Returns** `{object|null}` - the plugin if found or null otherwise.
|
||||
|
||||
***
|
||||
|
||||
#### `injectCSS(id, css)`
|
||||
Adds a block of css to the current document's `head`.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`id`|string|Identifier for the node to be added. Can be used later with [`clearCSS`](#clearcssid) from above.|
|
||||
|`css`|string|String of css to be added.|
|
||||
|
||||
**@Returns** `{object|null}` - the plugin if found or null otherwise.
|
||||
|
||||
***
|
||||
|
||||
#### `linkJS(id, url)`
|
||||
Links some remote JavaScript to be added to the page. Useful for libraries like `Sortable.js`.
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`id`|string|Identifier for the node to be added. Can be used later with [`unlinkJS`](#unlinkjsid) below.|
|
||||
|`url`|string|URL of the js.|
|
||||
|
||||
***
|
||||
|
||||
#### `loadData(pluginName, key)`
|
||||
Gets some saved data for plugin `pluginName` with key `key`. Data can be saved with [`saveData`](#savedatapluginname-key-data).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`pluginName`|string|Which plugin this is being used for.|
|
||||
|`key`|string|Key for which data should be returned.|
|
||||
|
||||
**@Returns** `{any|null}` - The information that was saved previously, or null otherwise.
|
||||
|
||||
***
|
||||
|
||||
#### `saveData(pluginName, key, data)`
|
||||
Saved some `data` for plugin `pluginName` under `key` key. Gets saved in the plugins folder under `pluginName.config.json`. Data can be saved with [`loadData`](#loaddatapluginname-key).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`pluginName`|string|Which plugin this is being used for.|
|
||||
|`key`|string|Key for the data should be saved under.|
|
||||
|`data`|any|Data to save.|
|
||||
|
||||
***
|
||||
|
||||
#### `showToast(content, options = {})`
|
||||
Shows a simple toast message similar to on Android. An example of the `success` toast can be seen [here](https://i.zackrauen.com/zIagVa.png).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`content`|string|Content to show inside the toast.|
|
||||
|`[options]`|object|Options for the toast.|
|
||||
|`[options.type=""]`|string|Changes the type of the toast stylistically and semantically. Choices: "", "info", "success", "danger"/"error", "warning"/"warn". Default: ""|
|
||||
|`[options.icon=true]`|boolean|Determines whether the icon should show corresponding to the type. A toast without type will always have no icon. Default: true|
|
||||
|`[options.timeout=3000]`|number|Adjusts the time (in ms) the toast should be shown for before disappearing automatically. Default: 3000|
|
||||
|
||||
***
|
||||
|
||||
#### `unlinkJS(id)`
|
||||
Removes some previously linked JS by [`linkJS`](#linkjsid-url).
|
||||
|
||||
|Parameter|Type|Description|
|
||||
|-|-|:-|
|
||||
|`id`|string|ID of the node to remove.|
|
||||
|
||||
***
|
||||
|
||||
|
||||
# Third-party libraries
|
||||
|
||||
Some plugin developers have written their own libraries for developing plugins:
|
||||
|
||||
- [Zere's Plugin Library](https://github.com/rauenzi/BDPluginLibrary) \[1] ([Documentation](https://rauenzi.github.io/BDPluginLibrary/docs/))
|
||||
- [Lib Discord Internals](https://github.com/samogot/betterdiscord-plugins/tree/master/v2/1Lib%20Discord%20Internals) \[1]
|
||||
- [BDfunctionsDevilBro](https://github.com/mwittrien/BetterDiscordAddons/blob/master/Plugins/BDfunctionsDevilBro.js) \[2]
|
||||
|
||||
\[1] Licensed under the MIT license
|
||||
\[2] Not licensed
|
||||
|
||||
# Extra
|
||||
|
||||
## Add namespaces to your events
|
||||
|
||||
When using jQuery and listening on events like `$(document).on('dblclick', ...)`, use a namespace such as `$(document).on('dblclick.myplugin', ...)` in order to easily unload all events with `$(document).off('dblclick.myplugin')` or `$(document).off('*.myplugin')` without affecting Discord and other plugins.
|
||||
Loading…
Reference in New Issue