Salastil/DankMaterialShell
1
0
Fork 0
mirror of https://github.com/AvengeMedia/DankMaterialShell.git synced 2026-01-30 16:32:50 -05:00
Code Packages Releases Activity

plugin readme update

Browse Source
This commit is contained in:
bbedward
2025-10-02 14:01:20 -04:00
parent 6021815fd3
commit bd02923616
2 changed files with 12 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
PLUGINS/README.md
View File

@@ -29,6 +29,7 @@ The plugin system enables developers to create custom widgets that can be displa
- Renders plugin widgets in the bar - Renders plugin widgets in the bar
- Merges plugin components with built-in widgets - Merges plugin components with built-in widgets
- Supports left, center, and right sections - Supports left, center, and right sections
- Supports any dankbar position (top/left/right/bottom)
## Plugin Structure ## Plugin Structure
@@ -39,7 +40,6 @@ $CONFIGPATH/DankMaterialShell/plugins/YourPlugin/
├── plugin.json # Required: Plugin manifest ├── plugin.json # Required: Plugin manifest
├── YourWidget.qml # Required: Widget component ├── YourWidget.qml # Required: Widget component
├── YourSettings.qml # Optional: Settings UI ├── YourSettings.qml # Optional: Settings UI
├── qmldir # Optional: QML module definition
└── *.js # Optional: JavaScript utilities └── *.js # Optional: JavaScript utilities
``` ```
@@ -96,7 +96,7 @@ import qs.Widgets
import qs.Modules.Plugins import qs.Modules.Plugins
PluginComponent { PluginComponent {
// Define horizontal bar pill (optional) // Define horizontal bar pill, for top and bottom DankBar positions (optional)
horizontalBarPill: Component { horizontalBarPill: Component {
StyledRect { StyledRect {
width: content.implicitWidth + Theme.spacingM * 2 width: content.implicitWidth + Theme.spacingM * 2
@@ -114,12 +114,12 @@ PluginComponent {
} }
} }
// Define vertical bar pill (optional) // Define vertical bar pill, for left and right DankBar positions (optional)
verticalBarPill: Component { verticalBarPill: Component {
// Same as horizontal but optimized for vertical layout // Same as horizontal but optimized for vertical layout
} }
// Define popout content (optional) // Define popout content, opens when clicking the bar pill (optional)
popoutContent: Component { popoutContent: Component {
PopoutComponent { PopoutComponent {
headerText: "My Plugin" headerText: "My Plugin"
@@ -295,7 +295,7 @@ PluginSettings {
**Available Setting Components:** **Available Setting Components:**
All settings automatically save on change and load on component creation. No manual `pluginService.savePluginData()` calls needed! All settings automatically save on change and load on component creation.
**How Default Values Work:** **How Default Values Work:**
@@ -640,12 +640,11 @@ Or edit `$CONFIGPATH/quickshell/dms/config.json`:
2. **Follow Theme**: Use `Theme` singleton for colors, spacing, and fonts 2. **Follow Theme**: Use `Theme` singleton for colors, spacing, and fonts
3. **Data Persistence**: Use PluginService data APIs instead of manual file operations 3. **Data Persistence**: Use PluginService data APIs instead of manual file operations
4. **Error Handling**: Gracefully handle missing dependencies and invalid data 4. **Error Handling**: Gracefully handle missing dependencies and invalid data
5. **Performance**: Keep widgets lightweight, avoid expensive operations 5. **Performance**: Keep widgets lightweight, avoid long operations that block the UI loop
6. **Responsive Design**: Adapt to `compactMode` and different screen sizes 6. **Responsive Design**: Adapt to `compactMode` and different screen sizes
7. **Clean Code**: Follow QML code conventions from CLAUDE.md 7. **Documentation**: Include README.md explaining plugin usage
8. **Documentation**: Include README.md explaining plugin usage 8. **Versioning**: Use semantic versioning for updates
9. **Versioning**: Use semantic versioning for updates 9. **Dependencies**: Document external library requirements
10. **Dependencies**: Document external library requirements
## Debugging ## Debugging
@@ -711,7 +710,7 @@ The plugin API is currently **experimental**. Breaking changes may occur in mino
## Resources ## Resources
- **Example Plugin**: https://github.com/rochacbruno/WorldClock - **Example Plugins**: [Emoji Picker](./ExampleEmojiPlugin/) [WorldClock](https://github.com/rochacbruno/WorldClock)
- **PluginService**: `Services/PluginService.qml` - **PluginService**: `Services/PluginService.qml`
- **Settings UI**: `Modules/Settings/PluginsTab.qml` - **Settings UI**: `Modules/Settings/PluginsTab.qml`
- **DankBar Integration**: `Modules/DankBar/DankBar.qml` - **DankBar Integration**: `Modules/DankBar/DankBar.qml`

2
README.md
View File

@@ -650,6 +650,8 @@ More comprehensive details available in the [PLUGINS](PLUGINS/README.md) - and e
The example plugin can be installed by `cp -R ./PLUGINS/ExampleEmojiPlugin ~/.config/DankMaterialShell/plugins` - then it will appear in dms settings. The example plugin can be installed by `cp -R ./PLUGINS/ExampleEmojiPlugin ~/.config/DankMaterialShell/plugins` - then it will appear in dms settings.
**Only install plugins from TRUSTED sources.** Plugins execute QML and javascript at runtime, plugins from third parties should be reviewed before enabling them in dms.
### Calendar Setup ### Calendar Setup
Sync your caldev compatible calendar (Google, Office365, etc.) for dashboard integration: Sync your caldev compatible calendar (Google, Office365, etc.) for dashboard integration: