UI Plugin API
Table of Contents
The PluginApi
object is a global object in the window
object.
PluginApi
is considered experimental and is subject to change without notice. This documentation covers only the plugin-specific API. It does not necessarily cover the core UI API. Information on these methods should be referenced in the UI source code.
An example using various aspects of PluginApi
may be found in the source code under pkg/plugin/examples/react-component
.
Properties
React
An instance of the React library.
ReactDOM
An instance of the ReactDOM library.
GQL
This namespace contains the generated graphql client interface. This is a low-level interface. In many cases, StashService
should be used instead.
libraries
libraries
provides access to the following UI libraries:
ReactRouterDOM
Bootstrap
Apollo
Intl
FontAwesomeRegular
FontAwesomeSolid
Mousetrap
MousetrapPause
register
This namespace contains methods used to register page routes and components.
PluginApi.register.route
Registers a route in the React Router.
Parameter | Type | Description |
---|---|---|
path | string | The path to register. This should generally use the /plugin/ prefix. |
component | React.FC | A React function component that will be rendered when the route is loaded. |
Returns void
.
PluginApi.register.component
Registers a component to be used by plugins. The component will be available in the components
namespace.
Parameter | Type | Description |
---|---|---|
name | string | The name of the component to register. This should be unique and should ideally be prefixed with plugin- . |
component | React.FC | A React function component. |
Returns void
.
components
This namespace contains all of the components available to plugins. These include a selection of core components and components registered using PluginApi.register.component
.
utils
This namespace provides access to the NavUtils
and StashService
namespaces. It also provides access to the loadComponents
method.
PluginApi.utils.loadComponents
Due to code splitting, some components may not be loaded and available when a plugin page is rendered. loadComponents
loads all of the components that a plugin page may require.
In general, PluginApi.hooks.useLoadComponents
hook should be used instead.
Parameter | Type | Description |
---|---|---|
components | Promise[] | The list of components to load. These values should come from the PluginApi.loadableComponents namespace. |
Returns a Promise<void>
that resolves when all of the components have been loaded.
hooks
This namespace provides access to the following core utility hooks:
useSpriteInfo
useToast
It also provides plugin-specific hooks.
PluginApi.hooks.useLoadComponents
This is a hook used to load components, using the PluginApi.utils.loadComponents
method.
Parameter | Type | Description |
---|---|---|
components | Promise[] | The list of components to load. These values should come from the PluginApi.loadableComponents namespace. |
Returns a boolean
which will be true
if the components are loading.
loadableComponents
This namespace contains all of the components that may need to be loaded using the loadComponents
method. Components are added to this namespace as needed. Please make a development request if a required component is not in this namespace.
patch
This namespace provides methods to patch components to change their behaviour.
PluginApi.patch.before
Registers a before function. A before function is called prior to calling a component’s render function. It accepts the same parameters as the component’s render function, and is expected to return a list of new arguments that will be passed to the render.
Parameter | Type | Description |
---|---|---|
component | string | The name of the component to patch. |
fn | Function | The before function. It accepts the same arguments as the component render function and is expected to return a list of arguments to pass to the render function. |
Returns void
.
PluginApi.patch.instead
Registers a replacement function for a component. The provided function will be called with the arguments passed to the original render function, plus the original render function as the last argument. An error will be thrown if the component already has a replacement function registered.
Parameter | Type | Description |
---|---|---|
component | string | The name of the component to patch. |
fn | Function | The replacement function. It accepts the same arguments as the original render function, plus the original render function, and is expected to return the replacement component. |
Returns void
.
PluginApi.patch.after
Registers an after function. An after function is called after the render function of the component. It accepts the arguments passed to the original render function, plus the result of the original render function. It is expected to return the rendered component.
Parameter | Type | Description |
---|---|---|
component | string | The name of the component to patch. |
fn | Function | The after function. It accepts the same arguments as the original render function, plus the result of the original render function, and is expected to return the rendered component. |
Returns void
.
PluginApi.Event
Allows plugins to listen for Stash’s events.
PluginApi.Event.addEventListener("stash:location", (e) => console.log("Page Changed", e.detail.data.location.pathname))