Build a GPlayer plugin.

my-plugin/
  plugin.json              # manifest — required, at the ZIP root
  background.mjs           # optional long-running worker
  state.json               # runtime state, preserved on upgrade via keep_files
  views/
    frontend/
      index.html           # public page at /p/my-plugin/
      report.mjs           # public page at /p/my-plugin/report/
    backend/
      tools.mjs            # admin page at /administrator/p/my-plugin/tools/
  hooks/
    video-save.mjs         # handler for the video.save hook
  widgets/
    status.html            # widget injected into an admin slot
  assets/
    styles.css             # served at /plugins/my-plugin/assets/styles.css
    icon.svg

{
  "name": "Hello Analytics",
  "folder": "hello-analytics",
  "version": "1.0.0",
  "icon_uri": "/plugins/hello-analytics/assets/icon.svg",
  "keep_files": ["state.json"],
  "background": "background.mjs",
  "config": { "endpoint": "https://analytics.example.com/collect", "enabled": true },
  "hooks": {
    "video.save": [{ "file": "hooks/video-save.mjs", "priority": 0 }]
  },
  "widgets": {
    "backend.dashboard.bottom": [
      { "file": "widgets/status.html", "priority": 0, "admin_only": true }
    ]
  },
  "config_fields": [
    { "name": "endpoint", "label": "Collect endpoint", "type": "url", "required": true,
      "description": "HTTPS URL that receives events." },
    { "name": "enabled", "label": "Enable tracking", "type": "checkbox", "required": false }
  ]
}

Node.js page handler

Export render, default, or run. The handler receives one input object and returns a string or a response object:

// views/backend/tools.mjs
export function render ({ context, config, plugin }) {
  if (context.method === 'POST') {
    return { status: 303, body: '', headers: { location: `${context.baseUrl}${context.adminDirectory}/p/${plugin.folder}/tools/` } }
  }
  return {
    status: 200,
    contentType: 'text/html; charset=utf-8',       // or application/json, text/plain
    body: `<h1>${plugin.name}</h1><p>Endpoint: ${config.endpoint}</p>`,
    headers: { 'cache-control': 'private' }        // only cache-control and location are honored
  }
}

The input object contains context (method, path, page, query, body, user, baseUrl, adminDirectory, csrf), config (saved plugin configuration), and plugin (id, name, folder, version).

HTML template pages

<!-- views/frontend/index.html -->
<link rel="stylesheet" href="{{plugin_asset_base}}styles.css">
<h1>{{plugin_name}} v{{plugin_version}}</h1>
<p>Endpoint: {{config.endpoint}}</p>
<form method="post" action="{{base_url}}p/{{plugin_folder}}/save/">
  <input type="hidden" name="csrf" value="{{csrf}}">
</form>

Available placeholders: {{csrf}}, {{base_url}}, {{admin_directory}}, {{plugin_name}}, {{plugin_folder}}, {{plugin_version}}, {{plugin_asset_base}}, and {{config.<key>}}. All values are HTML-escaped.

// hooks/video-save.mjs
export default async function ({ data, config, context, plugin }) {
  await fetch(config.endpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ event: 'video.save', video: data, by: context.user?.id })
  })
  return { tracked: true }   // merged into the hook data
}

Each execution runs in its own worker thread with a 2-second timeout and a 2 MB output limit.

// widgets/status.mjs
export function render ({ data, config }) {
  return { html: `<div class="plugin-widget">Slot ${data.slot} — endpoint ${config.endpoint}</div>` }
}

Available admin slots

• backend.dashboard.main_bottom
• backend.dashboard.sidebar_bottom
• backend.dashboard.bottom
• backend.plugins.list.top / .bottom
• backend.settings.form_bottom / backend.settings.bottom
• backend.users.list.top / .bottom
• backend.users.sessions.bottom
• backend.users.new.form_bottom / .bottom
• backend.users.edit.form_bottom / .bottom
• backend.users.profile.form_bottom / .bottom
• backend.videos.list.top / .bottom
• backend.videos.new.form_bottom / .bottom
• backend.videos.edit.form_bottom / .bottom
• backend.videos.subtitles.bottom
• backend.load_balancers.list.bottom
• backend.load_balancers.new.form_bottom / .bottom
• backend.load_balancers.edit.form_bottom / .bottom
• backend.gdrive.list.bottom
• backend.gdrive.new.form_bottom / .bottom
• backend.gdrive.edit.form_bottom / .bottom
• backend.gdrive.files.bottom
• backend.gdrive.backup_files.bottom
• backend.gdrive.backup_queue.bottom
• backend.log.bottom

Each field takes name, label, type, required, an optional description, and for selects an options array. Config keys not declared as fields are preserved untouched when the admin saves the form.

// background.mjs
import { readFile, writeFile } from 'node:fs/promises'

export default async function run ({ pluginDirectory }) {
  const statePath = `${pluginDirectory}/state.json`   // listed in keep_files
  let state = { ticks: 0 }
  try { state = JSON.parse(await readFile(statePath, 'utf8')) } catch {}
  for (;;) {
    await new Promise((resolve) => setTimeout(resolve, 60_000))
    state.ticks += 1
    await writeFile(statePath, JSON.stringify(state))
  }
}

Workers run with capped resources (32 MB old-generation heap, 16 MB young generation, 4 MB stack). Persist state under the plugin directory and list those files in keep_files so upgrades don't erase them.

# plugin.json
{
  "name": "Hello World",
  "folder": "hello-world",
  "version": "1.0.0"
}

# views/frontend/index.html
<link rel="stylesheet" href="{{plugin_asset_base}}styles.css">
<h1>Hello from {{plugin_name}}!</h1>

# assets/styles.css
h1 { font-family: sans-serif; }

1. Zip the three files with plugin.json at the archive root.
2. Upload the ZIP on /administrator/plugins/list/.
3. Enable the plugin from the list.
4. Open /p/hello-world/ — your page is live.

← Back to the application guide