FalkonTutorials/qml/articles/2.Basic_extension.md

# Falkon QML Tutorial - 2. Basic extension

This will create a basic extension which Falkon will be able to load and
unload. It will also print text to the standard output and to see it
start falkon from terminal.

## File structure

Each extension has to contain:

 * metadata.desktop
 * main.qml

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 QML
Comment=Example QML extension
Icon=
Type=Service
X-Falkon-Type=Extension/Qml

X-Falkon-Author=Juraj Oravec
X-Falkon-Email=jurajoravec@mailo.com
X-Falkon-Version=1.0.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.  
For the final product it is best to provide the icon with the extension
so that machines without this icon or on some obscure systems the icon
will be present.

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

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

#### 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`



## main.qml
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

```qml
import org.kde.falkon 1.0 as Falkon

Falkon.PluginInterface {

    init: function(state, settingsPath){
        console.log(i18n('"Tutorial2" plugin loaded'))
    }

    testPlugin: function() {
        return true
    }

    unload: function() {
        console.log(i18n('"Tutorial2" plugin unloaded'))
    }

}
```

The plugin / extension inherits from `Falkon.PluginInterface` [^1] .
The full code can be found at
[extensions/qml_tutorial_2](../extensions/qml_tutorial_2)

### Methods used

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

* **state**: possible values
   * > The init state ENUM is for Falkon QML API version `1.0` broken and
       raw values has to be used
   * `0` **Falkon.PluginInterface.StartupInitState**  
Normal init state during Falkon start, nothing to do for us.
   * `1` **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 usecase will be shown in one of the next chapters.
* **settingsPath**: Contains path to an 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://falkon.sgorava.xyz/docs/class_qml_plugin_interface.html