Publish complete starter plugin packages 0.2.0 and update guidance
This commit is contained in:
1 parent
dd67b20525
commit
108aa9e5b1
27 files changed
+174
-48
No files matched your search
@@ -0,0 +1,6 @@
|
||||
# Starter plugins 0.2.0 — 2026-10-26
|
||||
|
||||
- Package Notes, Bookmarks, and Workspace status with their complete implementation, metadata, documentation, and namespaced page/widget templates in each plugin folder.
|
||||
- Keep compatibility with framework APIs while removing the dependency on shared starter implementation files.
|
||||
- Publish versioned archives and checksums for complete packages; retain prior archives.
|
||||
- Document persistent plugin/theme mounts and metadata-only startup/manual update checks in Web Framework 0.5.0.
|
||||
@@ -1,16 +1,26 @@
|
||||
# Web Framework Resources
|
||||
|
||||
Reusable plugins and theme templates for [Web Framework](https://gitea.coreplay.eu/Dymas/web-framework).
|
||||
Complete plugin packages and theme templates for [Web Framework](https://gitea.coreplay.eu/Dymas/web-framework).
|
||||
|
||||
The default catalog is `https://gitea.coreplay.eu/Dymas/web-framework-resources/raw/branch/main/catalog.json`.
|
||||
Open **Config → Add resources**, search, and install a plugin or theme. Restart the application, then enable it under **Plugins** or select it under **Themes**. Existing bundled plugins and default themes remain available without downloading anything.
|
||||
Default catalog: `https://gitea.coreplay.eu/Dymas/web-framework-resources/raw/branch/main/catalog.json`.
|
||||
Open **Config → Add resources**, search, and install a plugin or theme. Restart, then enable the plugin or select the theme. The initial packages are also bundled in the framework for offline first startup.
|
||||
|
||||
Each `plugins/<id>/plugin.json` or `themes/<id>/theme.json` declares an ID, name, description, and version. Plugins include `plugin.py`; the starter templates reuse the framework's factories. Themes declare `mode` (`dark`, `light`, `system`), `accent` (`violet`, `blue`, `green`), and `density` (`comfortable`, `compact`). Theme templates reuse the framework's design tokens and layouts.
|
||||
## Folder layout
|
||||
|
||||
Every resource has its own source folder: `plugins/<id>/` or `themes/<id>/`. Plugin v0.2.0 packages include `plugin.py`, `implementation.py`, `plugin.json`, README, and their page/widget templates. They depend on public framework APIs and the common shell, rather than on the shared starter implementation. Theme folders contain `theme.json` and any accompanying files; the bundled themes are presets using the framework design system.
|
||||
|
||||
Every JSON manifest declares `id`, `name`, `description`, and `version`. Themes also declare `mode` (`dark`, `light`, `system`), `accent` (`violet`, `blue`, `green`), and `density` (`comfortable`, `compact`). Versioned ZIP archives contain the entire resource with files at the archive root. Catalog entries record type, metadata, relative archive path and SHA-256.
|
||||
|
||||
## Persistence and updates
|
||||
|
||||
Framework Compose mounts host folders `./plugins` and `./themes` outside the container, with one subfolder per resource. Image rebuilds and restarts preserve existing files. Missing defaults are copied locally from the image; no resource ZIPs are downloaded at startup.
|
||||
|
||||
The app checks catalogs in the background on startup and through **Check for updates** on the configuration pages. Checks only compare metadata: they never replace code or download archives. Local versions use PEP 440 comparison; source provenance protects against same-ID packages from another publisher. Operators can disable startup checks with `[resources].check_updates_on_startup = false`.
|
||||
|
||||
To update, stop the workspace, back up the resource folder, verify a newer archive against its catalog SHA-256, extract it into that folder, then restart. Keep the mounted resource folders and control-data volume. Saved plugin content and configuration remain in the control store.
|
||||
|
||||
## Publish resources
|
||||
|
||||
Store newly developed plugins and themes here. Keep source directories and versioned ZIP archives in the repository. ZIP files contain resource files at their root, with no enclosing directory. Add entries to `catalog.json` with `type`, all metadata fields, a relative `archive` URL and the archive's SHA-256 digest. Increment a resource's version whenever its files change. Framework installs do not overwrite existing resources; operators back up and remove an old installed directory before installing a replacement. Installed data stays in the application's control store.
|
||||
Store newly developed plugins and themes here with all required helpers, templates, and assets in their own subfolder. Increment the resource version, build its complete ZIP, and update `catalog.json` with schema version 1. Commit source, archive, and catalog together. Keep old versioned archives for existing installations. Publish catalogs and archives for unauthenticated read access; never include secrets.
|
||||
|
||||
Catalog schema version 1 uses a top-level `resources` array. Custom catalogs follow this same format. Only configure trusted repositories: installing plugins allows their Python code to execute at the next application startup. Downloads require no repository credentials, so publish catalogs and archives for read access by the application.
|
||||
|
||||
The initial six resources can be regenerated using `PYTHONPATH=. python tools/prepare_resources.py /path/to/web-framework-resources` in the framework repository. Add custom entries separately before publishing; the exporter regenerates the bundled catalog.
|
||||
The initial six resources can be regenerated with `PYTHONPATH=. python tools/prepare_resources.py /path/to/web-framework-resources` from the framework repository. The exporter regenerates bundled source directories and their catalog; merge any custom entries before publishing. Only configure trusted repositories: plugin code runs with the application user's privileges after restart.
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
+9
-9
@@ -5,28 +5,28 @@
|
||||
"id": "notes",
|
||||
"name": "Notes",
|
||||
"description": "Shared notes with persistent content.",
|
||||
"version": "0.1.0",
|
||||
"version": "0.2.0",
|
||||
"type": "plugin",
|
||||
"archive": "archives/plugin-notes-0.1.0.zip",
|
||||
"sha256": "e31e7f5183b26529b4d1dde5a6d63a9bb89a2c711fcd6df016c5ceaa94fcd192"
|
||||
"archive": "archives/plugin-notes-0.2.0.zip",
|
||||
"sha256": "5e2e37c1b81aea62c58c79c8f0280a82e2208c08a6066223a430ed443192f507"
|
||||
},
|
||||
{
|
||||
"id": "bookmarks",
|
||||
"name": "Bookmarks",
|
||||
"description": "A shared collection of useful links.",
|
||||
"version": "0.1.0",
|
||||
"version": "0.2.0",
|
||||
"type": "plugin",
|
||||
"archive": "archives/plugin-bookmarks-0.1.0.zip",
|
||||
"sha256": "108d9d997b6ada86085f24c365c0ecca84c751cf97e5908bb1ef7994440fd291"
|
||||
"archive": "archives/plugin-bookmarks-0.2.0.zip",
|
||||
"sha256": "57d8f8c4407a34722b25c0777844b043485d528eaefaa80ccf1449f2c20385ba"
|
||||
},
|
||||
{
|
||||
"id": "status",
|
||||
"name": "Workspace status",
|
||||
"description": "Local uptime and configured integration counts. No external polling.",
|
||||
"version": "0.1.0",
|
||||
"version": "0.2.0",
|
||||
"type": "plugin",
|
||||
"archive": "archives/plugin-status-0.1.0.zip",
|
||||
"sha256": "d27edcc6dea923dac0d2ee8ffe3d097b14bf3937873ab0cdad0c1767c4b82260"
|
||||
"archive": "archives/plugin-status-0.2.0.zip",
|
||||
"sha256": "36ea5a836209a2188a7d5394cac13cfc0feaaa665d6bb50b7e9ec7236bff6bec"
|
||||
},
|
||||
{
|
||||
"id": "default",
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
# Bookmarks
|
||||
|
||||
Generated from the bookmarks template. Restart the workspace, then enable this plugin in Config → Plugins.
|
||||
|
||||
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
|
||||
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
|
||||
@@ -0,0 +1,42 @@
|
||||
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
|
||||
import time
|
||||
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
|
||||
from web_framework.auth import can, store
|
||||
from web_framework.config import safe_url
|
||||
from web_framework.modules import Widget
|
||||
from web_framework.plugins import Plugin, Setting
|
||||
|
||||
STARTED = time.monotonic()
|
||||
|
||||
def make_collection(plugin_id, name, kind="notes"):
|
||||
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
|
||||
|
||||
@blueprint.route("/", methods=["GET", "POST"])
|
||||
def index():
|
||||
if request.method == "POST":
|
||||
if not can("content.write"):
|
||||
from flask import abort
|
||||
abort(403)
|
||||
try:
|
||||
if request.form.get("action") == "delete":
|
||||
store().delete_item(plugin_id, request.form.get("item_id", ""))
|
||||
else:
|
||||
title = request.form.get("title", "").strip()
|
||||
value = request.form.get("value", "").strip()
|
||||
if not title or len(title) > 160 or len(value) > 10000:
|
||||
raise ValueError("Add a title (up to 160 characters) and content (up to 10,000 characters).")
|
||||
if kind == "bookmarks" and not safe_url(value):
|
||||
raise ValueError("Bookmarks need a safe HTTP(S) or root-relative URL.")
|
||||
store().put_item(plugin_id, {"title": title, "value": value})
|
||||
store().audit(g.user["username"], "plugin.content.changed", plugin_id)
|
||||
flash("Content updated.", "success")
|
||||
except ValueError as error:
|
||||
flash(str(error), "error")
|
||||
return redirect(url_for(blueprint.name + ".index"))
|
||||
return render_template(f"{plugin_id}/collection.html", title=name, collection=plugin_id, kind=kind, items=store().items(plugin_id), description=current_app.extensions["plugins"].configuration(plugin_id)["intro"])
|
||||
|
||||
return Plugin(plugin_id, name, version="0.2.0", settings_schema={"intro": Setting("Page introduction", default="A shared collection for your workspace.")}, description="Shared notes with persistent content." if kind == "notes" else "A shared collection of useful links.", blueprint=blueprint, endpoint=blueprint.name + ".index",
|
||||
widgets={"summary": Widget(f"{plugin_id}/collection_summary.html", context=lambda config: {"items": store().items(plugin_id)[:5], "kind": kind, "endpoint": blueprint.name + ".index"})})
|
||||
|
||||
def make_bookmarks(plugin_id="bookmarks", name="Bookmarks"):
|
||||
return make_collection(plugin_id, name, "bookmarks")
|
||||
@@ -2,5 +2,5 @@
|
||||
"id": "bookmarks",
|
||||
"name": "Bookmarks",
|
||||
"description": "A shared collection of useful links.",
|
||||
"version": "0.1.0"
|
||||
"version": "0.2.0"
|
||||
}
|
||||
@@ -1,3 +1,3 @@
|
||||
from web_framework.starter_plugins import make_bookmarks
|
||||
from .implementation import make_bookmarks
|
||||
|
||||
plugin = make_bookmarks()
|
||||
@@ -1,5 +0,0 @@
|
||||
[plugin]
|
||||
id = "bookmarks"
|
||||
name = "Bookmarks"
|
||||
version = "0.1.0"
|
||||
api_version = 1
|
||||
@@ -0,0 +1,11 @@
|
||||
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}
|
||||
{% block content %}
|
||||
{{ heading(title, description, 'PLUGIN') }}
|
||||
<div class="settings-layout"><div class="widget-column">
|
||||
{% for item in items %}{% call panel(item.title) %}
|
||||
{% if kind == 'bookmarks' %}<a href="{{ item.value }}">{{ item.value }} ↗</a>{% else %}<p class="widget-text">{{ item.value }}</p>{% endif %}
|
||||
{% if can('content.write') %}<form method="post" class="inline-form" data-confirm="Delete this item?"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><input type="hidden" name="action" value="delete"><input type="hidden" name="item_id" value="{{ item.id }}"><button class="button" type="submit">Delete {{ item.title }}</button></form>{% endif %}
|
||||
{% endcall %}{% else %}{% call panel('Nothing here yet') %}<p class="muted">{{ 'Add your first item using the form.' if can('content.write') else 'An editor can add content here.' }}</p>{% endcall %}{% endfor %}
|
||||
</div>{% if can('content.write') %}<aside>{% call panel('Add ' ~ ('bookmark' if kind == 'bookmarks' else 'note')) %}
|
||||
<form method="post" class="stack"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><label for="item-title">Title</label><input id="item-title" name="title" required maxlength="160"><label for="item-value">{{ 'URL' if kind == 'bookmarks' else 'Content' }}</label><textarea id="item-value" name="value" rows="6" maxlength="10000" required></textarea><button class="button primary" type="submit">Add item</button></form>{% endcall %}</aside>{% endif %}</div>
|
||||
{% endblock %}
|
||||
@@ -0,0 +1 @@
|
||||
<div class="link-list">{% for item in widget.data['items'] %}<a href="{{ item.value if widget.data.kind == 'bookmarks' else url_for(widget.data.endpoint) }}">{{ item.title }} <span aria-hidden="true">↗</span></a>{% else %}<p class="muted">No items yet.</p>{% endfor %}</div>
|
||||
@@ -1,5 +1,3 @@
|
||||
# Notes
|
||||
|
||||
Generated from the notes template. Restart the workspace, then enable this plugin in Config → Plugins.
|
||||
|
||||
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
|
||||
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
|
||||
@@ -0,0 +1,42 @@
|
||||
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
|
||||
import time
|
||||
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
|
||||
from web_framework.auth import can, store
|
||||
from web_framework.config import safe_url
|
||||
from web_framework.modules import Widget
|
||||
from web_framework.plugins import Plugin, Setting
|
||||
|
||||
STARTED = time.monotonic()
|
||||
|
||||
def make_collection(plugin_id, name, kind="notes"):
|
||||
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
|
||||
|
||||
@blueprint.route("/", methods=["GET", "POST"])
|
||||
def index():
|
||||
if request.method == "POST":
|
||||
if not can("content.write"):
|
||||
from flask import abort
|
||||
abort(403)
|
||||
try:
|
||||
if request.form.get("action") == "delete":
|
||||
store().delete_item(plugin_id, request.form.get("item_id", ""))
|
||||
else:
|
||||
title = request.form.get("title", "").strip()
|
||||
value = request.form.get("value", "").strip()
|
||||
if not title or len(title) > 160 or len(value) > 10000:
|
||||
raise ValueError("Add a title (up to 160 characters) and content (up to 10,000 characters).")
|
||||
if kind == "bookmarks" and not safe_url(value):
|
||||
raise ValueError("Bookmarks need a safe HTTP(S) or root-relative URL.")
|
||||
store().put_item(plugin_id, {"title": title, "value": value})
|
||||
store().audit(g.user["username"], "plugin.content.changed", plugin_id)
|
||||
flash("Content updated.", "success")
|
||||
except ValueError as error:
|
||||
flash(str(error), "error")
|
||||
return redirect(url_for(blueprint.name + ".index"))
|
||||
return render_template(f"{plugin_id}/collection.html", title=name, collection=plugin_id, kind=kind, items=store().items(plugin_id), description=current_app.extensions["plugins"].configuration(plugin_id)["intro"])
|
||||
|
||||
return Plugin(plugin_id, name, version="0.2.0", settings_schema={"intro": Setting("Page introduction", default="A shared collection for your workspace.")}, description="Shared notes with persistent content." if kind == "notes" else "A shared collection of useful links.", blueprint=blueprint, endpoint=blueprint.name + ".index",
|
||||
widgets={"summary": Widget(f"{plugin_id}/collection_summary.html", context=lambda config: {"items": store().items(plugin_id)[:5], "kind": kind, "endpoint": blueprint.name + ".index"})})
|
||||
|
||||
def make_notes(plugin_id="notes", name="Notes"):
|
||||
return make_collection(plugin_id, name)
|
||||
@@ -2,5 +2,5 @@
|
||||
"id": "notes",
|
||||
"name": "Notes",
|
||||
"description": "Shared notes with persistent content.",
|
||||
"version": "0.1.0"
|
||||
"version": "0.2.0"
|
||||
}
|
||||
@@ -1,3 +1,3 @@
|
||||
from web_framework.starter_plugins import make_notes
|
||||
from .implementation import make_notes
|
||||
|
||||
plugin = make_notes()
|
||||
@@ -1,5 +0,0 @@
|
||||
[plugin]
|
||||
id = "notes"
|
||||
name = "Notes"
|
||||
version = "0.1.0"
|
||||
api_version = 1
|
||||
@@ -0,0 +1,11 @@
|
||||
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}
|
||||
{% block content %}
|
||||
{{ heading(title, description, 'PLUGIN') }}
|
||||
<div class="settings-layout"><div class="widget-column">
|
||||
{% for item in items %}{% call panel(item.title) %}
|
||||
{% if kind == 'bookmarks' %}<a href="{{ item.value }}">{{ item.value }} ↗</a>{% else %}<p class="widget-text">{{ item.value }}</p>{% endif %}
|
||||
{% if can('content.write') %}<form method="post" class="inline-form" data-confirm="Delete this item?"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><input type="hidden" name="action" value="delete"><input type="hidden" name="item_id" value="{{ item.id }}"><button class="button" type="submit">Delete {{ item.title }}</button></form>{% endif %}
|
||||
{% endcall %}{% else %}{% call panel('Nothing here yet') %}<p class="muted">{{ 'Add your first item using the form.' if can('content.write') else 'An editor can add content here.' }}</p>{% endcall %}{% endfor %}
|
||||
</div>{% if can('content.write') %}<aside>{% call panel('Add ' ~ ('bookmark' if kind == 'bookmarks' else 'note')) %}
|
||||
<form method="post" class="stack"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"><label for="item-title">Title</label><input id="item-title" name="title" required maxlength="160"><label for="item-value">{{ 'URL' if kind == 'bookmarks' else 'Content' }}</label><textarea id="item-value" name="value" rows="6" maxlength="10000" required></textarea><button class="button primary" type="submit">Add item</button></form>{% endcall %}</aside>{% endif %}</div>
|
||||
{% endblock %}
|
||||
@@ -0,0 +1 @@
|
||||
<div class="link-list">{% for item in widget.data['items'] %}<a href="{{ item.value if widget.data.kind == 'bookmarks' else url_for(widget.data.endpoint) }}">{{ item.title }} <span aria-hidden="true">↗</span></a>{% else %}<p class="muted">No items yet.</p>{% endfor %}</div>
|
||||
@@ -1,5 +1,3 @@
|
||||
# Status
|
||||
# Workspace status
|
||||
|
||||
Generated from the status template. Restart the workspace, then enable this plugin in Config → Plugins.
|
||||
|
||||
Add business logic in plugin.py. Use require_permission('content.write') for mutations; include csrf_token() in forms. Do not store secrets in templates.
|
||||
This package includes its Python implementation and page/widget templates. It depends on the Web Framework plugin API.
|
||||
@@ -0,0 +1,18 @@
|
||||
"""Self-contained starter implementation; shared framework APIs remain dependencies."""
|
||||
import time
|
||||
from flask import Blueprint, current_app, flash, g, redirect, render_template, request, url_for
|
||||
from web_framework.auth import can, store
|
||||
from web_framework.config import safe_url
|
||||
from web_framework.modules import Widget
|
||||
from web_framework.plugins import Plugin, Setting
|
||||
|
||||
STARTED = time.monotonic()
|
||||
|
||||
def make_status(plugin_id="status", name="Workspace status"):
|
||||
blueprint = Blueprint("plugin_" + plugin_id.replace("-", "_"), __name__, template_folder="templates")
|
||||
def status(config=None):
|
||||
return {"uptime": int(time.monotonic() - STARTED), "plugins": len(current_app.extensions["plugins"].enabled()), "connections": len(current_app.extensions["connectors"].definitions())}
|
||||
@blueprint.get("/")
|
||||
def index():
|
||||
return render_template(f"{plugin_id}/status.html", title=name, status=status())
|
||||
return Plugin(plugin_id, name, version="0.2.0", description="Local uptime and configured integration counts. No external polling.", blueprint=blueprint, endpoint=blueprint.name + ".index", widgets={"summary": Widget(f"{plugin_id}/status_summary.html", context=status)})
|
||||
@@ -2,5 +2,5 @@
|
||||
"id": "status",
|
||||
"name": "Workspace status",
|
||||
"description": "Local uptime and configured integration counts. No external polling.",
|
||||
"version": "0.1.0"
|
||||
"version": "0.2.0"
|
||||
}
|
||||
@@ -1,3 +1,3 @@
|
||||
from web_framework.starter_plugins import make_status
|
||||
from .implementation import make_status
|
||||
|
||||
plugin = make_status()
|
||||
@@ -1,5 +0,0 @@
|
||||
[plugin]
|
||||
id = "status"
|
||||
name = "Status"
|
||||
version = "0.1.0"
|
||||
api_version = 1
|
||||
@@ -0,0 +1,4 @@
|
||||
{% extends 'base.html' %}{% from 'components.html' import heading, panel %}{% block content %}
|
||||
{{ heading(title, 'A local overview of your framework instance.', 'PLUGIN') }}
|
||||
<div class="plugin-grid">{% call panel('Process uptime') %}<p class="stat-value">{{ status.uptime }}s</p>{% endcall %}{% call panel('Enabled plugins') %}<p class="stat-value">{{ status.plugins }}</p>{% endcall %}{% call panel('Configured connections') %}<p class="stat-value">{{ status.connections }}</p><p class="muted">Configuration count; not a connectivity check.</p>{% endcall %}</div>
|
||||
{% endblock %}
|
||||
@@ -0,0 +1 @@
|
||||
<dl class="details-list"><dt>Process uptime</dt><dd>{{ widget.data.uptime }} seconds</dd><dt>Enabled plugins</dt><dd>{{ widget.data.plugins }}</dd><dt>Configured connections</dt><dd>{{ widget.data.connections }}</dd></dl>
|
||||
Reference in new issue
Block a user