Nova Flow OS
KDE Developer Platform
KDE Developer Platform
  • KDE Developer Platform
    • Getting started
      • Building KDE software
        • KDE software
        • Where to find the development team
        • Learning more
        • Choose what to work on
        • Source code cross-referencing
        • Installing build dependencies
        • Set up a development environment
        • Building KDE software with kdesrc-build
        • Basic troubleshooting
        • Tips and tricks
        • IDE Configuration
          • Setting up an IDE for KDE development
          • Visual Studio Code
          • Qt Creator
          • Kate
          • KDevelop
          • CLion
          • Sublime Text
        • Building KDE software manually
        • Building KDE software with distrobox and podman
      • Kirigami
        • KDE is ours
        • Setting up and getting started
        • Explaining pages
        • Layouts, ListViews, and Cards
        • Adding actions
        • Adding a dialog
        • Using separate files
        • Next steps
        • Colors and themes in Kirigami
        • Typography
        • Actions based components
        • Page rows and page stacks
        • Scrollable pages and list views
        • Cards
        • Drawers
        • Chips
        • Dialog types
        • Controls and interactive elements
        • Form layouts
        • Inline messages
        • Action toolbars
        • Progress bars and indicators
        • List views
        • Understanding CMakeLists
        • Figuring out main.cpp
        • Connect logic to your QML user interface
        • Connect models to your QML user interface
        • About page
        • Introduction to Kirigami Addons
        • FormCard About pages
        • Form delegates in your settings pages
      • KXmlGui
        • Getting started with KXmlGui
        • Hello World!
        • Creating the main window
        • Using actions
        • Saving and loading
        • Command line interface
      • Python with Kirigami
        • Apps with QML and Python
        • Your first Python + Kirigami application
        • Creating a Python package
        • Creating a Flatpak
      • Common programming mistakes
      • Adding a new KDE project
    • Features
      • Icons
      • Configuration
        • The KConfig Framework
        • Introduction to KConfig
        • Using KConfig XT
        • KDE Frameworks 6 porting guide
        • Settings module (KCM) development
        • KConfigDialog
      • D-Bus
        • What is D-Bus practically useful for?
        • Introduction to D-Bus
        • Accessing D-Bus interfaces
        • Intermediate D-Bus
        • Creating D-Bus interfaces
        • Using custom types with D-Bus
        • D-Bus autostart services
      • Create your own mouse cursor theme
      • Session management
      • Archives
      • Desktop file
      • KAuth
        • Privilege Escalation
        • Using actions in your applications
      • KIdleTime
      • Akonadi: personal information management
        • Debugging Akonadi Resources
        • Using Akonadi in applications
      • Concurrent programming
      • Solid
      • Sonnet
    • Plasma themes and plugins
      • Getting started
      • Plasma Widget tutorial
        • How to create a plasmoid
        • Setup
        • Porting Plasmoids to KF6
        • Testing
        • QML
        • Plasma's QML API
        • Widget Properties
        • Configuration
        • Translations / i18n
        • Examples
        • C++ API
      • KWin Effects
      • Plasma Desktop scripting
        • Javascript Interaction With Plasma Shells
        • Templates
        • Examples
        • API documentation
        • Configuration keys
      • Plasma Style tutorial
        • Creating a Plasma Style quickstart
        • Understanding Plasma Styles
        • SVG elements and Inkscape
        • Background SVG format
        • System and accent colors
        • Theme elements reference
        • Porting themes to Plasma 5
        • Porting themes to Plasma 6
      • Aurorae window decorations
      • KWin scripting tutorial
        • Quick start
        • KWin scripting API
      • Wallpapers
      • Plasma comic
        • Tutorial
        • Testing and debugging
        • Examples
      • Create a custom Window Switcher
      • KRunner C++ Plugin
        • Basic Anatomy of a Runner
        • KRunner metadata format
    • Applications
      • Creating sensor faces
      • Dolphin
        • Creating Dolphin service menus
      • Kate
        • Kate plugin tutorial
      • KMines
        • Making a KMines theme
      • Writing tests
        • Appium automation testing
    • Packaging
      • Android
        • KDE on Android
        • Building applications for Android
        • Packaging and publishing applications for Android
        • Publishing on Google Play
          • Introduction
          • Packaging your app
          • Adding your app to Google Play
          • Publishing your app
          • Releasing new versions of old apps
        • Porting applications to Android
          • Basic porting
          • Making applications run well on Android
          • Metadata
      • Windows
        • Packaging and publishing applications for Windows
        • Publish your app in the Microsoft Store
          • Packaging your app for the Microsoft Store
          • Submitting your app to the Microsoft Store
      • Plasma Mobile
        • KDE on mobile devices
        • Porting a new device to Plasma Mobile
        • KDE Telephony stack
          • General Overview
          • Kernel layer
          • System daemons
            • General overview
            • Developing Telephony functionality
            • ModemManager Telephony functions
          • Session daemons
          • QML declarative plugin layer
          • KDE application layer
        • Execute applications
      • Distributing KDE software as Flatpak
        • Your first Flatpak
        • Extending your package
        • Nightly Flatpaks and Flathub
        • Testing your Flatpak
    • System administration
      • Shell scripting with KDE dialogs
      • Kiosk: Simple configuration management for large deployment
        • Abstract
        • Introduction to Kiosk
        • Kiosk keys
    • Contribute to the documentation
    • About
      • Readme
      • License
        • Creative Commons Attribution-ShareAlike 4.0 International
        • GNU General Public License 3.0 or later
Powered by GitBook
On this page
  1. KDE Developer Platform
  2. Plasma themes and plugins
  3. Plasma Desktop scripting

Templates

Templates provides a way for common functionality to be easily reused.

PreviousJavascript Interaction With Plasma ShellsNextExamples

Last updated 8 months ago

Templates are named packages that contain scripts. This provides a way for common functionality to be easily reused, helping to increase consistency and lower maintenance costs. Templates can be loaded from other scripts by name and they are also used to populate some parts of the user interface, such as the entries in the Add Panels menu.

A template is a small set of files in a specified file hierarchy (or, in Plasma terms, a "Package"). In particular, a Template package contains the following files:

  • metadata.json: a file describing the template

  • contents/layout.js: a Javascript file containing the actual script

Templates are stored in:

  • /usr/share/plasma/layout-templates/

  • ~/.local/share/plasma/layout-templates/

and may be installed using:

kpackagetool5 --type=Plasma/LayoutTemplate -i /path/to/package

Instead of installing a directory, template packages may also be provided as a .zip file renamed to have a .plasmalayout suffix.

(cd ~/Code/mytemplate && zip -r ../mytemplate.plasmalayout *)
kpackagetool5 --type=Plasma/LayoutTemplate -i ~/Code/mytemplate.plasmalayout

The metadata.json file contains the usual entries such as Name and Icon but must also contain the KPackageStructure entry set to Plasma/LayoutTemplate. If the layout is specific to a given Plasma application, such as plasma-desktop, this can be specific using X-Plasma-Shell. X-Plasma-ContainmentCategories defines what kind of layout it is with possible values being panel and desktop. Finally, a X-KDE-PluginInfo-Name entry is required to provide a globally unique internal name for the Template. Here is an example of a Template that provides a Panel layout for Plasma Netbook:

{
    "KPlugin": {
        "Authors": [
            {
                "Email": "aseigo@kde.org",
                "Name": "Aaron Seigo"
            }
        ],
        "EnabledByDefault": true,
        "Id": "org.kde.CoolNetbookPanel",
        "License": "GPL",
        "Name": "Cool Panel",
        "Version": "1.0",
        "Website": "https://kde.org/plasma-desktop"
    },
    "X-Plasma-ContainmentCategories": [
        "panel"
    ],
    "X-Plasma-Shell": "plasma-netbook",
    "KPackageStructure": "Plasma/LayoutTemplate"
}

When running a template, two global variables will be accessible in read-only mode: templateName and templateComment. They will contain the Name and Description fields of the above json file, and are translated if a localization is available.

In case you have an existing plugin that uses a metadata.desktop file, you can follow the migration instructions from the [Widget Properties]({{< relref "docs/plasma/widget/properties.md#kpackagestructure" >}}) documentation.

Examples of Usage

Creating panels

A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on the first start. There is a Template called org.kde.plasma.desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and because it is marked as a Panel Template in the metadata.json file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.

Activity templates

Probably the most user visible use of templates are "Activity templates". The structure of Activity templates is similar to the other use of templates, but a few extra features are provided in the metadata.json file. Here is an example of such an activity template:

{
    "KPlugin": {
        "Authors": [
            {
                "Email": "john@doe.org",
                "Name": "John Doe"
            }
        ],
        "Category": "",
        "EnabledByDefault": true,
        "Icon": "user-desktop",
        "Id": "org.kde.plasma-desktop.CoolTemplate",
        "License": "GPL",
        "Name": "Cool Activity Template",
        "Version": "1.0",
        "Website": "http://john.doe.org"
    },
    "X-Plasma-ContainmentCategories": [
        "desktop"
    ],
    "X-Plasma-ContainmentLayout-ExecuteOnCreation": "dolphin $desktop, gwenview $pictures",
    "X-Plasma-ContainmentLayout-ShowAsExisting": "true",
    "X-Plasma-Shell": "plasma-desktop",
    "KPackageStructure": "Plasma/LayoutTemplate"
}

The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the X-Plasma-ContainmentLayout-ShowAsExisting key. Additionally, it starts applications in the newly created activity using the X-Plasma-ContainmentLayout-ExecuteOnCreation key.

That key is a list of commands to execute, and it supports the following variables:

  • $desktop

  • $autostart

  • $documents

  • $music

  • $video

  • $downloads

  • $pictures

They all expand into the path toward the user corresponding default folder.

KPluginMetaData