From 71772c69e7de3af23ab2f66d32e00591972e2ed4 Mon Sep 17 00:00:00 2001
From: Juraj Oravec <sgd.orava@gmail.com>
Date: Wed, 22 May 2019 17:09:45 +0200
Subject: [PATCH] Add 2. Basic extension

Signed-off-by: Juraj Oravec <sgd.orava@gmail.com>
---
 articles/2. Basic extension.md | 119 +++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 articles/2. Basic extension.md

diff --git a/articles/2. Basic extension.md b/articles/2. Basic extension.md
new file mode 100644
index 0000000..75cae5f
--- /dev/null
+++ b/articles/2. Basic extension.md	
@@ -0,0 +1,119 @@
+# 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
+
+```
+[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