script.js API Reference — OS

Every OS plugin registers itself through script.js. The file assigns a function to plugins["name"]. Inside that function, this exposes all registration methods.

Quick Overview

plugins["my-plugin"] = function () {
    this.setFrame({ title: 'Music Player', icon: { type: 'icon', name: 'pi pi-music' } })

    this.setToolbar([
        { icon: 'pi pi-home', to: '/' },
        { icon: 'pi pi-cog', to: '/setting' },
    ])

    this.setMenu([
        { label: 'Tracks',   icon: 'pi pi-music', to: '/' },
        { label: 'Settings', icon: 'pi pi-cog',   to: '/setting' },
    ])

    this.addLanguage('en', 'music', { label: 'Music Player' })

    this.addPage({ name: '/[my-plugin]index.vue',   path: '',         file: ['index.vue']   })
    this.addPage({ name: '/[my-plugin]setting.vue', path: '/setting', file: ['setting.vue'] })
}

Methods

setFrame(options)

Configures the Electron window frame — the title shown in the OS window bar and the window icon.

Parameters:

Field	Type	Description
title	string	Window title displayed in the OS taskbar and title bar
icon	object	Window icon definition
icon.type	string	Icon type: 'icon' for PrimeIcons CSS class, 'image' for an image asset path
icon.name	string	PrimeIcons class (e.g. 'pi pi-music') or image path (e.g. 'images/logo.jpg')

Example:

// Using a PrimeIcon
this.setFrame({
  title: 'Music Player',
  icon: { type: 'icon', name: 'pi pi-music' }
})

// Using an image
this.setFrame({
  title: 'My App',
  icon: { type: 'image', name: 'images/logo.jpg' }
})

---

setToolbar(items)

Defines the toolbar navigation buttons shown at the top of the plugin window. Each item links to a route within the plugin.

Parameters:

items — array of toolbar button objects:

Field	Type	Description
icon	string	PrimeIcons class for the button icon
to	string	Root-relative route path (e.g. '/', '/setting')

Example:

this.setToolbar([
  { icon: 'pi pi-home', to: '/' },
  { icon: 'pi pi-list', to: '/tracks' },
  { icon: 'pi pi-cog', to: '/setting' },
])

Routes in to must match routes registered with addPage().

---

setMenu(items)

Defines the sidebar or navigation menu items shown inside the plugin window. Complements setToolbar() for plugins that need a richer navigation structure.

Parameters:

items — array of menu item objects:

Field	Type	Description
label	string	Display text for the menu item
icon	string	PrimeIcons class for the item icon
to	string	Root-relative route path

Example:

this.setMenu([
  { label: 'Tracks',   icon: 'pi pi-music', to: '/' },
  { label: 'Playlists', icon: 'pi pi-list',  to: '/playlists' },
  { label: 'Settings', icon: 'pi pi-cog',   to: '/setting' },
])

---

addPage(options, to)

Registers a Vue page component as a route in the plugin window.

Parameters:

Parameter	Type	Default	Description
options	object	—	Page definition
options.name	string	—	Internal route name
options.path	string	—	Root-relative route path
options.file	string[]	—	Array containing the .vue component filename, e.g. ["index.vue"]
to	string	'app'	Mount target — always 'app' for OS plugins

Path formatting:

Unlike SA where paths are relative, OS paths are root-relative. The main view uses an empty string "" for the root route:

Path value	Resulting route	Usage
""	/	Main / home view
"/setting"	/setting	Settings page
"/detail/:id"	/detail/:id	Detail page with param

Example:

this.addPage({ name: '/[my-plugin]index.vue',    path: '',           file: ['index.vue']   })
this.addPage({ name: '/[my-plugin]setting.vue',  path: '/setting',   file: ['setting.vue'] })
this.addPage({ name: '/[my-plugin]detail.vue',   path: '/detail/:id', file: ['detail.vue']  })

---

addLanguage(locale, namespace, translations)

Registers translation strings for the plugin.

Parameters:

Parameter	Type	Description
locale	string	Language code: 'en', 'ar', etc.
namespace	string	Unique key namespace for the plugin
translations	object	Key/value translation pairs

Example:

this.addLanguage('en', 'music', {
  label:    'Music Player',
  tracks:   'Tracks',
  settings: 'Settings',
})

this.addLanguage('ar', 'music', {
  label:    'مشغل الموسيقى',
  tracks:   'المقاطع',
  settings: 'الإعدادات',
})

In Vue templates, access with $t('music.label').

Method Summary

Method	Purpose
setFrame(options)	Set window title and icon
setToolbar(items)	Add toolbar navigation buttons
setMenu(items)	Define sidebar/navigation menu items
addPage(options, to)	Register a Vue route/page
addLanguage(locale, ns, translations)	Register i18n strings

Comparison: OS vs SA vs EA

Feature	OS	SA	EA
Window type	Own Electron window	Embedded in SA shell	Embedded in EA shell
Route paths	Root-relative ("", "/setting")	Relative ("setting")	Relative
Main view file	index.vue	index.vue	index.vue
Frame/toolbar config	setFrame + setToolbar + setMenu	—	—
Backend (main.js)	✗	✗	✓
Widgets	✗	addWidget	—
Tasks	✗	addTask	—
Roles	✗	✗	addRole
Navigation extension	✗	addTo	addTo
Native file dialogs	ipcRenderer	✗	✗
Local database	api.database()	api.database()	—

Related Pages

• Development Guide — Full walkthrough of building an OS plugin
• Vue UI Guide — OS-specific UI patterns and components
• README Format — Plugin metadata format