Plugin Development
The range of functions of openmediavault can be expanded by means of plugins. This section describes how to implement such plugins.
Plugins are implemented in a declarative manner, this means no JavaScript or TypeScript knowledge is needed.
Overview
A plugin contains of various YAML files that have to be located in the
directory /usr/share/openmediavault/workbench
. The following
subdirectories each have a special meaning.
- component.d
This directory contains the manifest files of the pages shown in the openmediavault web interface.
- dashboard.d
This directory contains the manifest files of the dashboard widgets.
- log.d
This directory contains the manifest files that are used to configure the log content that is shown in the
Diagnostics | System Logs
datatable.- navigation.d
This directory contains the manifest files that are used to configure the navigation bar on the left side of the web interface.
- route.d
This directory contains the manifest files that are used to configure the web interface routes.
A manifest file must follow the following schema:
version: "1.0" type: component | dashboard-widget | log | navigation-item | route data: ...
Directories
component.d
A manifest file must follow the following schema:
version: "1.0" type: component data: name: string type: navigationPage | formPage | selectionListPage | textPage | tabsPage | datatablePage | rrdPage config: ...
The name field contains the unique identifier of the component. It is used to reference the component in a route configuration. The type field contains one of the following supported page types:
The available properties of each type can be found in the corresponding models.
Example:
version: "1.0"
type: component
data:
name: omv-services-clamav-onaccess-scan-form-page
type: formPage
config:
request:
service: ClamAV
get:
method: getOnAccessPath
params:
uuid: "{{ _routeParams.uuid }}"
post:
method: setOnAccessPath
fields:
- type: confObjUuid
- type: checkbox
name: enable
label: _("Enabled")
value: false
- type: sharedFolderSelect
name: sharedfolderref
label: _("Shared folder")
hint: _("The location of the files to scan on-access.")
validators:
required: true
buttons:
- template: submit
execute:
type: url
url: "/services/clamav/onaccess-scans"
- template: cancel
execute:
type: url
url: "/services/clamav/onaccess-scans"
dashboard.d
The following dashboard widget types are available:
grid
datatable
rrd
chart
text
value
The available properties of each type can be found in the corresponding model.
Example:
version: "1.0"
type: dashboard-widget
data:
id: 9984d6cc-741b-4fda-85bf-fc6471a61e97
permissions:
role:
- admin
title: _("CPU Usage")
type: chart
chart:
type: gauge
min: 0
max: 100
displayValue: true
request:
service: System
method: getInformation
label:
formatter: template
formatterConfig: "{{ value | tofixed(1) }}%"
dataConfig:
- label: Usage
prop: cpuUsage
backgroundColor: "#4cd964"
Check out the Dashboard widgets that are delivered with openmediavault for more examples.
log.d
Plugins can add their own log files to the web interface. The properties of the manifest file can be inspected here.
Example:
version: "1.0"
type: log
data:
id: clamav
text: _("Antivirus")
columns:
- name: _("Date & Time")
sortable: true
prop: ts
cellTemplateName: localeDateTime
flexGrow: 1
- name: _("Message")
sortable: true
prop: message
flexGrow: 2
request:
service: LogFile
method: getList
params:
id: clamav
route.d
A manifest file must follow the following schema:
version: "1.0" type: route data: url: string title: string editing: boolean notificationTitle: string component: string
The url is used to access the page via browser. A url like /foo/bar
will finally look like https://localhost/#/foo/bar
. The title field
will be shown in the breadcrumb bar.
The component references the page component that is displayed in the
main area of the web interface.
Example:
version: "1.0"
type: route
data:
url: "/services/clamav/onaccess-scans/create"
title: _("Create")
notificationTitle: _("Created on-access scan.")
component: omv-services-clamav-onaccess-scan-form-page
Build configuration
To build and apply the final web interface configuration you need to run omv-mkworkbench COMMAND
where COMMAND
is all | dashboard | log | navigation | route | i18n
.