plugin infrastruktur
This commit is contained in:
th committed
1 parent
1545b90f39
commit
3f4ba3c0f4
35 files changed
+1303
-195
No files matched your search
@@ -89,8 +89,9 @@ hyprcrd/
|
||||
├── docker-entrypoint.sh
|
||||
├── dist.sh # Build distribution ZIP
|
||||
├── src/
|
||||
│ ├── bootstrap.php # Initialization
|
||||
│ ├── bootstrap.php # Initialization + plugin discovery
|
||||
│ ├── Database.php # SQLite schema & migrations
|
||||
│ ├── PluginManager.php # Plugin scanner & asset/slot renderer
|
||||
│ ├── CalDavClient.php # CalDAV HTTP client + iCal parser
|
||||
│ └── CalDavSync.php # Bidirectional CalDAV sync engine
|
||||
├── public/ # Document root
|
||||
@@ -103,9 +104,13 @@ hyprcrd/
|
||||
│ │ └── vendor/ # Phosphor Icons CSS + fonts
|
||||
│ ├── fonts/ # JetBrains Mono & Silkscreen
|
||||
│ ├── js/
|
||||
│ │ ├── hyprcrd.js # Plugin API (window.hyprcrd, sync-loaded)
|
||||
│ │ ├── app.js # Orchestrator
|
||||
│ │ ├── modules/ # Feature modules
|
||||
│ │ ├── modules/ # Core feature modules
|
||||
│ │ └── vendor/ # marked.js, DOMPurify
|
||||
│ ├── plugins/ # Optional, drop-in plugin folders
|
||||
│ │ ├── canvas/ # ASCII art canvas editor
|
||||
│ │ └── tests/ # UI + state test runner
|
||||
│ └── uploads/ # User media (writable)
|
||||
├── relay/ # Relay service (mobile inbox + card sharing)
|
||||
│ ├── index.php # Single-file API + Mobile UI
|
||||
@@ -121,7 +126,7 @@ hyprcrd/
|
||||
- **Cards** with markdown body, color, tags, and position
|
||||
- **Buckets** for organizing cards into groups
|
||||
- **Tags** written as `#tagname` or hierarchical `#parent/child` in card body, extracted automatically
|
||||
- **Markdown** with `[[Card Title]]` wiki-links, ```` ```gallery ```` image galleries, ```` ```tree ```` list views
|
||||
- **Markdown** with `[[Card Title]]` wiki-links, ```` ```gallery ```` image galleries, ```` ```tree ```` list views, ```` ```ascii ```` art canvas (via canvas plugin)
|
||||
- **Search** combining text and `#tag` filters (e.g. `#project meeting notes`)
|
||||
- **Image gallery** with orphan detection and fullscreen viewer
|
||||
- **Split view** showing tag-related and content-related cards
|
||||
@@ -138,6 +143,101 @@ hyprcrd/
|
||||
- **Superview** compact multi-column list with hover cards
|
||||
- **Keyboard shortcuts**: `Ctrl+K` search, `F1` help, `Shift+scroll` zoom, arrow keys in autocomplete
|
||||
|
||||
## Plugins
|
||||
|
||||
hyprcrd has a drop-in plugin system. A plugin is just a folder under `public/plugins/` with a `plugin.json` manifest. The core scans the directory at startup, loads each plugin's CSS/JS/HTML, and the plugin self-registers against `window.hyprcrd`. Plugins are entirely optional — removing a plugin folder removes the feature, with no code changes anywhere else.
|
||||
|
||||
### Bundled plugins
|
||||
|
||||
- **`canvas/`** — ASCII art canvas editor. Adds a toolbar button + ` ```ascii ` fenced block. Draw with brush, line, rectangle, ellipse, fill, and text tools using a monospace character grid.
|
||||
- **`tests/`** — UI + state test runner (40+ test files). Loaded only when `?test` is in the URL or `Ctrl+Shift+T` is pressed, so production users pay no cost for it.
|
||||
|
||||
### Plugin layout
|
||||
|
||||
```
|
||||
public/plugins/myplugin/
|
||||
├── plugin.json # Manifest (required)
|
||||
├── myplugin.js # Entry point (loaded as ES module)
|
||||
├── myplugin.css # Optional styles
|
||||
├── myplugin.html # Optional HTML fragment (overlays, modals, etc.)
|
||||
└── backend.php # Optional PHP hooks
|
||||
```
|
||||
|
||||
**`plugin.json`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "myplugin",
|
||||
"version": "1.0.0",
|
||||
"description": "What this plugin does",
|
||||
"frontend": {
|
||||
"js": ["myplugin.js"],
|
||||
"css": ["myplugin.css"],
|
||||
"html": ["myplugin.html"]
|
||||
},
|
||||
"backend": "backend.php"
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin API (`window.hyprcrd`)
|
||||
|
||||
Loaded synchronously before any module, so plugins can register handlers immediately:
|
||||
|
||||
| Namespace | Methods | Purpose |
|
||||
|---|---|---|
|
||||
| `hyprcrd.editor` | `registerCommand(name, fn)`, `getCommand(name)`, `api.{body, insertMd, updatePreview}` | Add toolbar commands. The `data-md="<name>"` button dispatches to the registered handler. `api` is set after the editor initializes. |
|
||||
| `hyprcrd.markdown` | `registerFencedBlock(lang, fn)`, `registerPreProcessor(fn)`, `registerPostProcessor(fn)` | Add ` ```<lang> ` block renderers (returns HTML, passes through DOMPurify). Pre/post processors run on the source/HTML around `marked.parse()`. |
|
||||
| `hyprcrd.hooks` | `on(name, fn)`, `off(name, fn)`, `emit(name, data)` | Generic event bus. Use for cross-plugin or core→plugin signaling. |
|
||||
| `hyprcrd.util` | `$(idOrSel)`, `$$(sel)`, `esc(s)` | Lightweight DOM/escape helpers so plugins don't need to import core modules. |
|
||||
| `hyprcrd.registerPlugin(meta)` | — | Register the plugin's metadata for introspection. |
|
||||
|
||||
### Minimal plugin example
|
||||
|
||||
`public/plugins/hello/plugin.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "hello",
|
||||
"version": "1.0.0",
|
||||
"description": "Inserts a greeting",
|
||||
"frontend": { "js": ["hello.js"] }
|
||||
}
|
||||
```
|
||||
|
||||
`public/plugins/hello/hello.js`:
|
||||
|
||||
```js
|
||||
const h = window.hyprcrd;
|
||||
|
||||
h.editor.registerCommand('hello', () => {
|
||||
h.editor.api.insertMd('Hello, world! ', '', '');
|
||||
});
|
||||
|
||||
// Inject a toolbar button
|
||||
const btn = document.createElement('button');
|
||||
btn.dataset.md = 'hello';
|
||||
btn.className = 'toolbar-btn';
|
||||
btn.title = 'Hello';
|
||||
btn.textContent = '👋';
|
||||
document.getElementById('md-toolbar').appendChild(btn);
|
||||
|
||||
h.registerPlugin({ name: 'hello', version: '1.0.0' });
|
||||
```
|
||||
|
||||
That's the entire plugin. Drop the folder in, reload, the button appears.
|
||||
|
||||
### Backend hooks (PHP)
|
||||
|
||||
If a plugin needs server-side code, set `"backend": "backend.php"` in the manifest. The file is `require_once`'d during bootstrap. Backend plugins can use `PluginManager::instance()->addToSlot('slot-name', '<html>')` to inject HTML into named slots in `index.php` (e.g. `md-toolbar`).
|
||||
|
||||
### Removing a plugin
|
||||
|
||||
```bash
|
||||
rm -rf public/plugins/canvas
|
||||
```
|
||||
|
||||
That's it. The toolbar button, overlay, CSS, and markdown handler all disappear together. The core has no awareness of any specific plugin.
|
||||
|
||||
## Data & Backup
|
||||
|
||||
All data lives in two places:
|
||||
@@ -318,8 +418,8 @@ After changing Tailwind utility classes in HTML or JS files:
|
||||
# Download standalone CLI (once)
|
||||
curl -sL https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64 -o tailwindcss && chmod +x tailwindcss
|
||||
|
||||
# Build
|
||||
./tailwindcss --input public/css/tailwind.css --output public/css/tailwind.out.css --content "public/index.php,public/js/**/*.js" --minify
|
||||
# Build (includes plugins so plugin HTML/JS contributes utility classes)
|
||||
./tailwindcss --input public/css/tailwind.css --output public/css/tailwind.out.css --content "public/index.php,public/js/**/*.js,public/plugins/**/*.{js,html}" --minify
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
Reference in new issue
Block a user