FalkonTutorials/python/articles/2.Basic_extension.md

# Falkon Python Tutorial - 2. Basic extension

## File structure

Each extension has to contain:

 * metadata.desktop
 * \__init__.py

Anything else depend on the creator.

## metadata.desktop
This file contain information which are displayed in Falkon settings and some configuration.

### Example file

```ini
[Desktop Entry]
Name=Example Python
Comment=Example Python extension
Icon=
Type=Service
X-Falkon-Type=Extension/Python

X-Falkon-Author=David Rosca
X-Falkon-Email=nowrep@gmail.com
X-Falkon-Version=0.1.0
X-Falkon-Settings=false
```

#### Name
Extension name shown in Falkon settings.

#### Comment
Extension description shown in Falkon settings.

#### Icon
Extension Icon shown in Falkon settings.  
Path to icon file or icon name from icon theme.

#### Type
Keep: `Service`  
I did not find a use of this field in code yet (maybe legacy ?).

#### X-Falkon-Type
Falkon Extension type.  
For Python extension use: `Extension/Python`

#### X-Falkon-Author
Author`s name shown in Falkon settings.

#### X-Falkon-Email
Author`s email shown in Falkon settings.

#### X-Falkon-Version
Extension version shown in Falkon settings.

#### X-Falkon-Settings
If extension has a setting dialog.  
Extension `Settings` button in Falkon preferences depends on this variable.  
Possible values: `true` or `false`



## \__init__.py
Entry point to our program.  
This file will be called when extension is loaded.  
Some people consider leaving this file almost empty with only license and import line.  
I will leave the decision up to you.

### Example extension
This code is from example extension from [store.falkon.org](https://store.falkon.org/p/1301043/).

```python
import Falkon
from PySide2 import QtCore

class ExamplePython(Falkon.PluginInterface, QtCore.QObject):
    def init(self, state, settingsPath):
        print("Example Python")
        print("{} {}".format(state, settingsPath))

    def unload(self):
        print("unload")

    def testPlugin(self):
        return True

Falkon.registerPlugin(ExamplePython())

```

The plugin / extension class inherits from `Falkon.PluginInterface`[1] and `QtCore.QObject`.  
The plugin class has to be registered with `Falkon.registerPlugin()`.

### Methods used

#### init()
Called when extension is loaded.

* **state**: possible values
   * **PyFalkon.PluginInterface.InitState.StartupInitState**  
Normal init state during Falkon start, nothing to do for us.
   * **Falkon.PluginInterface.LateInitState**  
The extension was loaded long after Falkon started.  
In this case we need to manually call functions which would normally be called during the start.  
The exact case will be shown in one of the next chapters.
* **settingsPath**: Contains path to extension setting directory

#### unload()
Called when the plugin is uloading by being disabled in settings or when Falkon is closing.

#### testPlugin()
Method to check if plugin is compatible with current Falkon version.  
Return `True` if is and `False` if not.



[1]: https://github.com/KDE/falkon/blob/master/src/lib/plugins/plugininterface.h