-
Notifications
You must be signed in to change notification settings - Fork 1
Plugin How To
Currently Supported Plugins can be found here: https://github.com/emesene/emesene-supported-plugins
If you need reference the API documentation, it can be found here: http://emesene.github.com/emesene-docs/ and http://marianoguerra.com.ar/emesene/api/
Emesene has a plugins folder*; inside that folder you must create a new one for your plugin.
The folder's name will be used as the display name on preferences, capitalizing words and replacing underscores "_" with spaces.
For this example, we'll make a "Hello World" plugin, so the folder's name will be "hello_world"
*The Emesene plugins folder is located at: (replace USERNAME with your username on your computer)
Windows XP: C:\Documents and Settings\USERNAME\Application data\emesene\emesene2\plugins
Windows Vista/7: C:\Users\USERNAME\AppData\Roaming\emesene\emesene2\plugins
Linux: ~/.config/emesene2/plugins (OR /home/USERNAME/.config/emesene2/plugins for another user)
for 2.11.4 and 2.11.5 ~/.config/emesene2/plugins does not work, instead use /usr/share/emesene/emesene/plugins
Mac: ~/Library/Application Support/emesene2/plugins
Inside that folder you need at least these files:
__init__.py (can be empty)
plugin.py (the plugin is loaded here)
You can have a preferences file, which is optional:
Preferences.py
*You can use more files and subfolders if your plugin requires that
Let's start with the basic, a plugin that prints "Hello World" on the terminal/console at start and "Goodbye World" at stop
Your plugin.py file should have this code inside (you can obviouslly remove the comments)
hello_world/plugin.py
from plugin_base import PluginBase
class Plugin(PluginBase):
#description and author/s
_description = "Plugin that prints 'Hello world'"
_authors = {"arielj": "[email protected]"}
#this will be called the first time the plugin is started
def __init__(self):
#first of all, call PluginBase's init
PluginBase.__init__(self)
#initialize variables and do things needed for your plugin
self.message = "Hello World"
print "plugin loaded:", self.message
#you MUST implement this, check /plugin_base.py on the root directory
def start(self, session):
'''do whatever your plugin will do at start
-subscribe session signals
-call some session's method
-etc...
'''
print "plugin started:", self.message
#you MUST implement this, check /plugin_base.py on the root directory
def stop(self):
'''do whatever your plugin will do at stop:
-unsubscribe session signals subscribed at start
-disconnect signals connected at start
-destroy or delete objects if needed (remember, Python uses a
Garbage collector)
-etc...
you can use the sentence "pass" if you want a blank method:
def stop(self):
pass
'''
print "plugin stopped: Goodbye World (?)"
#if you have some config for your plugin, you must implement this method
def config(self, session):
pass
# If you have config, please change this method to return True
def configurable(self):
return FalseNow open emesene, start the plugin on preferences and see how you get some "Hello World" and "Goodbye World" messages
Now we want to react to some event of the session, let's print "hello conversation" when a new conversation is created after a contact talked to us
For that we need to use some session signal, lucklly we have a session
object on the start method
So, let's save a reference on our plugin object, subscribe to a signal
using to call a method and then unsubscribe it at stop
The new code should be something like this instead...
hello_world/plugin.py
from plugin_base import PluginBase
class Plugin(PluginBase):
# Description and author/s to show on preferences
_description = "Plugin that prints 'Hello world'"
_authors = {"arielj": "[email protected]"}
# This will be called the first time the plugin is started
def __init__(self):
#first of all, call PluginBase's init
PluginBase.__init__(self)
#initialize variables and do things needed for your plugin
self.message = "Hello World"
print "plugin loaded:", self.message
# You MUST implement this, check /plugin_base.py on the root directory
def start(self, session):
'''do whatever your plugin will do at start
-subscribe session signals
-call some session's method
-etc...
'''
self.session = session
session.signals.conv_first_action.subscribe(self.on_new_conversation)
print "plugin started:", self.message
# You MUST implement this, check /plugin_base.py on the root directory
def stop(self):
'''do whatever your plugin will do at stop:
-unsubscribe session signals subscribed at start (always unsubscribe
all subscribed signals!!)
-disconnect signals connected at start
-destroy or delete objects if needed (remember, Python uses a
Garbage collector)
-etc...
you can use the sentence "pass" if you want a blank method:
def stop(self):
pass
'''
session.signals.conv_first_action.unsubscribe(self.on_new_conversation)
print "plugin stopped: Goodbye World (?)"
# If you have some config for your plugin, you must implement this method
def config(self, session):
pass
# If you have config, please change this method to return True
def configurable(self):
return False
# This parameters are the default parameters for the conv_first_action
# signal
def on_new_conversation(self, cid, members, other_started=True):
print "new conversation!, Hello conversation"
Now wait until someone talk's to you and check the terminal, you will have a nice (?) "Hello conversation"
Now for the final example, we'll do something more difficult, we want a new widget below user's panel with the text "Hello World"
We need some gui toolkit, I'll use gtk for this example
We need to check for the desired gui, what extensions do we have available to
modify the gui, check gtkui/__init__.py, it registers all the available gtkui's
categories for extensions
(for example, if you want to make a new Preferences window, there's a category
for that, line 134)
Ok, the code will look something like this...
I will use 2 files, one for the logic, and one for the gtk widget, just like the "ye_old_status_combo" plugin
hello_world/plugin.py
# We need to import the extension module to handle extensions
import extension
from plugin_base import PluginBase
# We also need to import the widget we are going to display
import Widget
class Plugin(PluginBase):
# Description and author/s to show on preferences
_description = "Plugin that prints 'Hello world'"
_authors = {"arielj": "[email protected]"}
# This will be called the first time the plugin is started
def __init__(self):
#first of all, call PluginBase's init
PluginBase.__init__(self)
# You MUST implement this, check /plugin_base.py on the root directory
def start(self, session):
'''do whatever your plugin will do at start
-subscribe session signals
-call some session's method
-etc...
'''
pass
# You MUST implement this, check /plugin_base.py on the root directory
def stop(self):
'''do whatever your plugin will do at stop:
-unsubscribe session signals subscribed at start
(always unsubscribe all subscribed signals!!)
-disconnect signals connected at start
-destroy or delete objects if needed (remember, Python uses a
Garbage collector)
-etc...
you can use the sentence "pass" if you want a blank method:
def stop(self):
pass
'''
pass
# If you have some config for your plugin, you must implement this method
def config(self, session):
pass
# If you have config, please change this method to return True
def configurable(self):
return False
# This is called automatically after the plugin is started
# There's also a "category_register" method that's called BEFORE the start method
def extension_register(self):
# Register the custom widget to the desired category
extension.register('below panel', Widget.HelloWorldWidget)
as you can see, line 5 imports Widget and the last line uses a class HelloWorldWidget from there, so let's create it
hello_world/Widget.py
import gtk
class HelloWorldWidget(gtk.Label):
"""a label to display 'Hello World' below the user panel"""
NAME = 'HelloWorld Label'
DESCRIPTION = 'plugin how to'
AUTHOR = 'Ariel Juodziukynas'
WEBSITE = 'www.arieljuod.com.ar'
# You can use something like grep to see where is this extension
# instantiated and check the parameters
# For this example, line 49 of MainWindow.py
def __init__(self, main_window):
gtk.Label.__init__(self)
self.set_text("Hello World")
Now you only need to go to preferences > extensions and choose your "Hello World Label" (This is defined on NAME) instead of Empty Widget for the "below panel" extension.
And that's it! if your Widget does something usefull, you have done a useful plugin!