Plasma/Package

Plasma Package Format

This document describes the Plasmoid Package Format. It uses the Plasma::Package implementation in libplasma as a basis.

A Plasmoid is packed in one zip compressed file that contains all the necessary files to run the plasmoid. It is best to give it a .plasmoid extension. It can also pick icons from the icon theme running in KDE as well as SVGs from the Plasma Theme.

The files in a Plasmoid package can be code, images, layout or plasmoid-specific data files.

To keep those files separated each filetype is stored in a subdirectory.

$PlasmoidName-$PlasmoidVersion/ (root)
- metadata.desktop
- contents/
  - code/ files containing scripting code
    - main the main file that will be loaded at plasmoid start (unless you specify a different name in metadata.desktop)
  - images/ image files in svg, png or jpeg format
  - locale/ translation files in a standard localization hierarchy; e.g. German translation would appear in locale/l10n/de/
  - ui/ user interface files, such as Qt Designer layouts
    - config.ui the main configuration dialog layout
  - config/ KConfigXt files describing the configuration
    - main.xml the main configuration description
  - ... additional plasmoid-specific files

In the root of the package, an XML format file called metadata.xml which gives a detailed description of the plasmoid.

metadata.desktop contains the following mandatory fields:

Name of the Plasmoid
Author
A version number for the Plasmoid
Icon (YES/NO/$iconName).
- If YES (uppercase), it should pick icon.png.
- If it's $iconName, it should pick the icon from the user KDE theme.
- If it's NO (uppercase), the plasmoid won't have an icon.
Used License
- This will be from a pre-selected list of possibilities.
- You can use a custom licence, specifying it in a file called COPYING.
- Should Plasma refuse to load improperly licensed Plasmoids?
The API the plasmoid is written in (e.g. javascript, webkit, ruby, python, edje ..)
Description of the Plasmoid giving the user a nice overview of the Plasmoid capabilities

Optionally these fields can be added:

Category of widget that the Plasmoids belongs to, see [Projects/Plasma/PIG|the Plasma Interface Guidelines] for a list of recognized category names
Homepage for more information to the Plasmoid
EMail of the author
Release notes
Required scripting version
A minimum version number for Plasma
path to the main code file, relative to contents/
default size of the plasmoid (if unset, the default is 200,200)

An example file can be seen here:

[Desktop Entry]
Name=Analog Clock
Comment=An SVG themable clock
Icon=chronometer
Type=Service

X-Plasma-API=javascript
X-Plasma-MainScript=code/main.js
X-Plasma-DefaultSize=150,150

X-KDE-ServiceTypes=Plasma/Applet
X-KDE-PluginInfo-Author=John Doe
X-KDE-PluginInfo-Email=[email protected]
X-KDE-PluginInfo-Name=clock
X-KDE-PluginInfo-Version=pre0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Category=Date and Time
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

Packager

When a Plasma package is installed via the Plasma Packager, it will store the package in $APPDATA/plasma/$PACKAGE_TYPE_ROOT then read metadata.xml and create a .desktop file which it will install into the services directory. In this way, Plasma can use KTrader to find all Plasmoids whether they are written in C++ or an interpreted language.

A user interface needs to be created for browsing through packages for installation as well as a class for browsing the contents of a package, getting information on it and pulling out files on demand.

Another nice thing to be done would be a small command-line app to quickly create plasmoids with arbitrary metadata information, just for testing purposes.