Client Plugins
==============

For information on how client plugins are installed, see the
:wiki:`Client Plugins<Client-Plugins>` wiki page.

Client plugins need to inherit from the
:py:class:`~king_phisher.client.plugins.ClientPlugin` class which provides the
basic outline. Client plugins have access to a dictionary for persistent
configuration storage through the
:py:attr:`~king_phisher.client.plugins.ClientPlugin.config` attribute. In order
for the plugin's meta-data to be available to the GUI, class attributes are
used. This allows information such as the title, description, etc. to be
accessed without initializing the class.

Plugin Manager
--------------

When the Plugin Manager window is loaded, all available plugins are loaded in
order for their information to be retrieved from the class attributes. This is
the effective equivalent of importing the module in Python. When the module is
enabled, an instance of the Plugin class created allowing it to fulfill its
intended purpose.

Reloading Plugins
~~~~~~~~~~~~~~~~~

Plugin modules and classes can be "reloaded" to allow changes made to the plugin
on disk to take effect. This can be accomplished by right clicking the plugin
and selecting the "Reload" option from the manager window. If an enabled plugin
is reloaded, it will first be disabled before being re-enabled causing it to
lose any state information it may have been storing.

Plugin Compatibility
~~~~~~~~~~~~~~~~~~~~

Plugin modules that have requirements can have their compatibility checked by
viewing the plugin information pane. This includes a simple yes or no regarding
whether all of the plugin's requirements are met and the plugin is thus
compatible. Additional information regarding the specific requirements a
particular plugin has can be accessed by clicking the ``Compatible`` link which
will show each of the requirements, their values and whether or not they are
met. This allows users to easily determine why a particular plugin may not be
compatible.

Plugin Options
--------------

Client plugins have special `ClientOption` classes available to them for
specifying options that the user can set. The
:py:meth:`king_phisher.client.plugins.ClientOptionMixin.__init__` method offers
additional parameters such as *display_name* to configure the information shown
to the end user in the configuration widget.

The following are the different option classes available for client plugins:

- :py:class:`~king_phisher.client.plugins.ClientOptionBoolean`
- :py:class:`~king_phisher.client.plugins.ClientOptionEnum`
- :py:class:`~king_phisher.client.plugins.ClientOptionInteger`
- :py:class:`~king_phisher.client.plugins.ClientOptionPath`
- :py:class:`~king_phisher.client.plugins.ClientOptionPort`
- :py:class:`~king_phisher.client.plugins.ClientOptionString`

Example
-------

The following is a commented example of a basic "Hello World" plugin.

.. code-block:: python

   import king_phisher.client.plugins as plugins
   import king_phisher.client.gui_utilities as gui_utilities

   try:
       # imports that may not be available need to be an exception handler so
       # the plugin module will still load
       import advancedhttpserver
   except ImportError:
       # set a variable to whether this package is available or not for later use
       has_ahs = False
   else:
       has_ahs = True

   # this is the main plugin class, it is necessary to inherit from plugins.ClientPlugin
   class Plugin(plugins.ClientPlugin):
       authors = ['Spencer McIntyre']  # the plugins author
       title = 'Hello World!'          # the title of the plugin to be shown to users
       description = """
       A 'hello world' plugin to serve as a basic template and demonstration. This
       plugin will display a message box when King Phisher exits.
       """                             # a description of the plugin to be shown to users
       homepage = 'https://github.com/securestate/king-phisher-plugins'  # an optional home page
       options = [                     # specify options which can be configured through the GUI
           plugins.ClientOptionString(
               'name',                               # the name of the option as it will appear in the configuration
               'The name to which to say goodbye.',  # the description of the option as shown to users
               default='Alice Liddle',               # a default value for the option
               display_name='Your Name'              # a name of the option as shown to users
           ),
           plugins.ClientOptionBoolean(
               'validiction',
               'Whether or not this plugin say good bye.',
               default=True,
               display_name='Say Good Bye'
           ),
           plugins.ClientOptionInteger(
               'some_number',
               'An example number option.',
               default=1337,
               display_name='A Number'
           ),
           plugins.ClientOptionPort(
               'tcp_port',
               'The TCP port to connect to.',
               default=80,
               display_name='Connection Port'
           )
       ]
       req_min_py_version = '3.3.0'         # (optional) specify the required minimum version of python
       req_min_version = '1.4.0'            # (optional) specify the required minimum version of king phisher
       req_packages = {                     # (optional) specify a dictionary of required package names
           'advancedhttpserver': has_ahs    # set from within the exception handler when importing
       }
       req_platforms = ('Linux', 'Windows') # (optional) specify the supported platforms
       version = '1.0'                      # (optional) specify this plugin's version
       # this is the primary plugin entry point which is executed when the plugin is enabled
       def initialize(self):
           print('Hello World!')
           self.signal_connect('exit', self.signal_exit)
           # it is necessary to return True to indicate that the initialization was successful
           # this allows the plugin to check its options and return false to indicate a failure
           return True

       # this is a cleanup method to allow the plugin to close any open resources
       def finalize(self):
           print('Good Bye World!')

       # the plugin connects this handler to the applications 'exit' signal
       def signal_exit(self, app):
           # check the 'validiction' option in the configuration
           if not self.config['validiction']:
               return
           gui_utilities.show_dialog_info(
               "Good bye {0}!".format(self.config['name']),
               app.get_active_window()
           )
