KDE PIM/Akonadi/Firstrun: Difference between revisions
| Line 18: | Line 18: | ||
A Akonadi Firstrun description file uses the normal ini file syntax known from KDE config files. It also supports some of the KConfigXT/Kiosk features such as evaluating environment variables in setting values. | A Akonadi Firstrun description file uses the normal ini file syntax known from KDE config files. It also supports some of the KConfigXT/Kiosk features such as evaluating environment variables in setting values. | ||
=== Agent creation === | |||
A description files consists of two sections. The first one defines which type of agent should be created, the following example creates a iCal file resource. | A description files consists of two sections. The first one defines which type of agent should be created, the following example creates a iCal file resource. | ||
| Line 29: | Line 31: | ||
Besides the ''Type'' key, the ''Id'' one is most important in this section. The value defined there is used to determine if a description file has been executed already. This means moving or renaming a description file will not execute it again, changing the ''Id'' value does however. This can be useful when description files evolve over time. | Besides the ''Type'' key, the ''Id'' one is most important in this section. The value defined there is used to determine if a description file has been executed already. This means moving or renaming a description file will not execute it again, changing the ''Id'' value does however. This can be useful when description files evolve over time. | ||
=== Agent configuration === | |||
The second section defines the settings for the agent that just has been created. The available settings depend on the agent type of course, the following example configures two settings of an iCal file resource. | The second section defines the settings for the agent that just has been created. The available settings depend on the agent type of course, the following example configures two settings of an iCal file resource. | ||
| Line 37: | Line 41: | ||
AutosaveInterval=1 | AutosaveInterval=1 | ||
</code> | </code> | ||
The available settings are defined by the .kcfg file of the resource. These should be installed to ''$KDEDIR/share/config.kcfg''. If this is not the case you find those files as part of the agent source code, for those shipped with KDE SC for example here: http://websvn.kde.org/trunk/KDE/kdepim/runtime/resources/ . | |||
Note that unlike agent creation, configuration of agents requires support by the agent itself. More precisely it needs to expose it settings to D-Bus (below ''/Settings''). While all agents shipped as part of KDE SC do this, it is not guaranteed to be supported by all 3rd-party agents. | |||
[[Category:PIM]] [[Category:Akonadi]] | [[Category:PIM]] [[Category:Akonadi]] | ||
Revision as of 19:37, 29 April 2010
Akonadi Firstrun
This page documents the Akonadi Firstrun framework and how to use it to customize initial Akonadi setups.
What is Akonadi Firstrun?
Akonadi Firstrun allows you to automatically set up Akonadi agents. The most common use case is to provide an initial setup for new users.
Akonadi Firstrun is easily customizable, allowing distributions and system administrators to provide an optimized setup for their users.
How does it work?
The agents Akonadi Firstrun sets up as well as their configuration are defined by description files. These are searched for in $KDEDIR/share/apps/akonadi/firstrun and $KDEHOME/share/apps/akonadi/firstrun (exact paths may vary depending on your distribution).
When starting a Akonadi application, Firstrun checks if there is a description file that has not been executed yet and, if so, does that. This means that starting the first Akonadi application will create the intial agents as well as that you can add additional description files later on to augment existing setups.
How do I create a Akonadi Firstrun description file?
A Akonadi Firstrun description file uses the normal ini file syntax known from KDE config files. It also supports some of the KConfigXT/Kiosk features such as evaluating environment variables in setting values.
Agent creation
A description files consists of two sections. The first one defines which type of agent should be created, the following example creates a iCal file resource.
[Agent]
Id=defaultcalendar
Type=akonadi_ical_resource
Name=Personal Calendar
Besides the Type key, the Id one is most important in this section. The value defined there is used to determine if a description file has been executed already. This means moving or renaming a description file will not execute it again, changing the Id value does however. This can be useful when description files evolve over time.
Agent configuration
The second section defines the settings for the agent that just has been created. The available settings depend on the agent type of course, the following example configures two settings of an iCal file resource.
[Settings]
Path[$e]=~/.kde/share/apps/korganizer/std.ics
AutosaveInterval=1
The available settings are defined by the .kcfg file of the resource. These should be installed to $KDEDIR/share/config.kcfg. If this is not the case you find those files as part of the agent source code, for those shipped with KDE SC for example here: http://websvn.kde.org/trunk/KDE/kdepim/runtime/resources/ .
Note that unlike agent creation, configuration of agents requires support by the agent itself. More precisely it needs to expose it settings to D-Bus (below /Settings). While all agents shipped as part of KDE SC do this, it is not guaranteed to be supported by all 3rd-party agents.