Theme Admin Extensions
APayShop now supports theme-owned admin extension pages. This mechanism allows each active storefront theme to provide its own backend workspace without replacing the core /admin shell.
Design Goal
The goal is not to let themes fully rewrite the admin dashboard. Instead, APayShop keeps the core admin system unified and lets themes register additional pages through a predictable extension boundary.
This means:
- Core admin pages still live under
app/pages/admin/ - Authentication, layout, navigation shell and system workflows stay centralized
- Themes can add their own backend pages under
/admin/extensions/*
File Structure
Each theme can register custom admin pages with the following structure:
app/themes/[theme]/
theme.admin.json
admin/
pages/
theme-workspace.vue
content-studio.vue
Manifest File
The manifest file is:
app/themes/[theme]/theme.admin.json
It declares which admin extension pages should be exposed for the current theme.
Component Directory
The actual Vue page components live in:
app/themes/[theme]/admin/pages/
Runtime Flow
At runtime, APayShop uses a shared extension registry to:
- Read the current
active_theme - Load that theme's
theme.admin.json - Match the registered route
- Resolve the Vue component from
admin/pages - Render it through the common admin extension route
The core loader is implemented in useAdminExtensions.ts.
Route Namespace
Theme-owned admin pages are rendered through:
/admin/extensions/*
The common route entry is:
This route acts as a stable container for all theme extension pages.
Sidebar and Search Integration
Registered extension pages are automatically injected into:
- The default admin sidebar
- The mobile admin menu
- The admin route search palette
Relevant files:
This avoids scattering hardcoded links across multiple places whenever a theme adds a new backend page.
Example Manifest
{
"name": "Extensions",
"pages": [
{
"key": "theme-workspace",
"title": "Theme Workspace",
"description": "Manage storefront-specific operator workflows.",
"route": "/admin/extensions/theme-workspace",
"component": "theme-workspace.vue",
"icon": "ph:stack",
"order": 10
}
]
}
Current Principles
API authentication and host integration
Declare theme API permissions in theme.host.json, next to theme.admin.json:
{
"adminApiPermissions": {
"models": { "permission": "ext:example:models" }
}
}
Both /api/admin/example/models and an existing /api/example/admin/models
compatibility address use the host administrator gate and the same permission.
GET/HEAD require ext:example:models:view; writes require :edit. A legacy bare
ext:example:models grant permits both. Unknown mappings remain restricted to
administrators with full access. Compatibility addresses are audited too.
Existing service-token callbacks must declare their exact route and methods; they keep handler-level validation and do not exempt canonical admin URLs. Qingpu maintenance and rule publication retain their existing credentials.
theme.host.json also declares programmatically managed public/private settings,
frontend login policy, sitemap source modules and theme build checks. Run
node scripts/generate-theme-build.mjs after changes. Storefront selection and
business API selection are separate: unset APAY_SERVER_THEMES preserves
existing production URLs; an explicit list includes those modules plus the
selected storefronts. core selects only the storefronts' API modules.
Core ticket screenshots now upload through POST /api/admin/tickets/upload
(tickets:edit) or POST /api/users/tickets/upload (logged-in user). Send one
multipart file; the response is { "url": "/uploads/tickets/..." }. JPEG,
PNG and WebP are limited to 10MB. Existing attachment URLs remain valid, and
these endpoints do not require a theme database or provider credentials.
When extending the admin system through themes, follow these rules:
- Keep core admin pages in
app/pages/admin/ - Put theme-specific admin pages inside the theme directory
- Register extension entries through
theme.admin.json - Reuse the shared
/admin/extensions/*namespace - Do not make a theme take over the entire admin layout
Why This Matters
This design keeps APayShop:
- Easier to maintain
- Safer to upgrade
- Cleaner for multi-theme projects
- More understandable for AI-assisted development
In short, themes can now extend the admin dashboard, but the system still owns the admin shell.
Panel Custom Applications
The Panel application store editor supports docker-compose.yml, data.yml and .env. Editing data.yml updates the installation parameter table when the editor loses focus; table changes update additionalProperties.formFields. Saving uses the YAML defaults as the source for the published application catalog. Numbers, booleans, select options and custom metadata are preserved. Application keys and versions follow the corresponding form fields.
.env is an independent text file for package environment defaults. Comments, quotes and empty values are preserved; editing it does not rewrite installation form defaults. The final installed values follow GoPanel's installation and Compose rules.
| Endpoint | Method | Permission | Contract |
|---|---|---|---|
/api/admin/panel/apps/custom | GET | ext:panel:appstore:view | Returns custom application definitions and presets; ?key=... returns one definition. Versions may include dataYml and envContent. |
/api/admin/panel/apps/custom | POST | ext:panel:appstore:edit | Saves an application version, repacks its offline archive and rebuilds the catalog. |
/api/admin/panel/apps/compose | GET | ext:panel:appstore:view | With key and version, returns { compose, dataYml, envContent, filePath, isLocal, isFallback? } from the actual package. Missing sidecar files return empty strings. |
The existing POST fields (key, name, version, compose, formFields and application metadata) remain supported. Two optional string fields are added:
dataYml: YAML application version metadata. Nonempty YAML takes precedence over the suppliedformFields; itsadditionalProperties.formFieldsfeeds both the package and catalog. Empty YAML regenerates metadata from the form. Omitting it preserves existing custom metadata while allowing legacyformFieldsupdates.envContent: exact.envtext. An empty string writes an empty.env; omission preserves existing content. It is returned only by administrator APIs and packaged in the downloadable application archive, never included in the public catalog JSON.
Responses use { code: 0, data }. Invalid YAML, nonobject metadata, invalid form fields or nontext file content return HTTP 400 before saving. Uploaded packages retain .env, data.yml and companion files when registered and edited. Existing records without the new fields are hydrated from their local package; files previously removed by older releases require restoration from the original archive.
New archives are completed before replacing the existing package and saving the custom application record. A YAML or tar generation failure leaves the previous package and record unchanged. Filesystem replacement and the subsequent catalog rebuild are separate steps: an I/O or catalog failure after replacement may require restoring the backed-up data/custom-apps.json and the affected archive, then rebuilding the catalog. Publishing changes future downloads; it does not change already installed containers.