> How do you build a custom plugin?
The SPX [[Documentation/Graphics Controller/Plugins & Extensions|plugin system]] is designed for modularity, allowing developers to inject custom functionality directly into the core environment. By creating a dedicated folder within the `ASSETS/plugins/` directory and including a mandatory `init.js` file, you can register new JavaScript logic, add custom buttons to the UI, and create independent extension panels. This architecture provides a direct bridge to the [[Documentation/Control Interfaces/REST/Overview of SPX API|SPX API]], enabling your plugins to control rundowns, update field data, and interact with the [[Documentation/Renderer/Overview|renderer]] in real-time, all while maintaining a clean separation from the core server code.
---
## Plugin Structure
Create a folder in `ASSETS/plugins/` with your plugin name:
```
ASSETS/plugins/
└── myPlugin/
├── init.js # Required: Plugin initialization
├── package.json # Optional: Plugin metadata
├── html/ # Optional: HTML files
├── css/ # Optional: Stylesheets
└── js/ # Optional: JavaScript files
```
## Required Files
### init.js
The `init.js` file is required and contains the plugin initialization code:
```javascript
// Plugin initialization
window.SPXPlugin = window.SPXPlugin || {};
window.SPXPlugin.myPlugin = {
name: 'My Plugin',
version: '1.0.0',
init: function() {
// Plugin initialization code
console.log('My Plugin initialized');
},
// Plugin functions
myFunction: function() {
// Custom function
}
};
```
## Plugin Lifecycle
1. **Load** - Plugin folder is scanned
2. **Init** - `init.js` is executed
3. **Register** - Plugin is registered with SPX
4. **Ready** - Plugin is available for use
## Adding UI Controls
Plugins can add custom controls to the UI:
```javascript
window.SPXPlugin.myPlugin = {
init: function() {
// Add custom button
this.addButton({
text: 'My Button',
onClick: function() {
// Button click handler
}
});
}
};
```
## Accessing SPX API
Plugins can interact with SPX through the [[Documentation/Control Interfaces/REST/Overview of SPX API|API]]:
```javascript
// Control rundown
window.top.spxAPI.rundown.play();
// Get status
var status = window.top.spxAPI.rundown.getStatus();
// Update item
window.top.spxAPI.rundown.updateItem({
fields: {
f0: 'New Value'
}
});
```
## Extension Panels
Plugins can create extension panels (additional UI):
```javascript
window.SPXPlugin.myPlugin = {
init: function() {
// Create extension panel
this.createPanel({
title: 'My Extension',
html: '<div>Extension content</div>',
position: 'right'
});
}
};
```
## Using Plugin Library
Access common UI elements from `plugins/lib`:
```javascript
// Use library components
var button = SPXPluginLib.createButton({
text: 'Click me',
onClick: function() {
// Handler
}
});
```
## Best Practices
1. **Namespace your plugin** - Use unique plugin name
2. **Handle errors gracefully** - Don't break SPX if plugin fails
3. **Document your plugin** - Include README with usage instructions
4. **Test thoroughly** - Test in different scenarios
5. **Follow conventions** - Use consistent code style
## Plugin Examples
Study existing plugins for reference:
- Check `ASSETS/plugins/` folder
- Review plugin structure
- Learn from implementation patterns
## Distribution
Plugins can be:
- Shared privately within organization
- Distributed via [SPX Store](https://spxgraphics.com/store)
- Included in template packs
> [!TIP] Want your plugin featured? [Contact us](https://spxgraphics.com/contact).
---
## Read Next
- [[Documentation/Graphics Controller/Plugins & Extensions|Plugins & Extensions]] - Full documentation on the plugin system
- [[Documentation/Control Interfaces/REST/Overview of SPX API|Overview of SPX API]] - Complete API reference for plugin development
- [[Guides/Tutorials/My first HTML template|My first HTML template]] - Learn the basics of SPX templates
- [[Documentation/Control Interfaces/Overview|Control Interfaces Overview]] - External control options for SPX