Skip to content

Extensions

Jump to bottom Edit New page
Seamus Tuohy edited this page Apr 29, 2014 · 4 revisions

Extensions

The commotion_client's main user-facing functionality will take place within extensions. This series of swappable components will provide the configuration, visualization, and other networking functionality of the client. These components will be intentionally loosely coupled from the core GUI so that as developers want to add functionality it is easy to implement new extensions without digging into the commotion_client code-base. As more protocols are adopted this will also allow for communities to easily remove extensions that are not compatible with their unique network configurations. After installation users will be able to install, uninstall, enable, disable, update, and configure extension from a extension menu.

Core vs. Contrib Extensions

The core functionality of Commotion will be provided upon install by a set of "core" extensions. The only difference between the two is that "core" extensions, unlike user-installed extensions, will not be uninstall-able. Commotion currently only supports the OLSR routing protocol. As such, Version 2.0 will have a set of "core" extensions that are OLSR based. As Commotion extends support for various protocols the "core" extension set will also adapt or grow to accommodate the full core functionality of the underlying commotion networking software.

Examples of "core" extensions:

  • Commotion Application Manager
  • Network Visualizer
  • Commotion Profile Manager

Examples of "contrib" extensions: (NOTE: I just made these up... they are not on the development roadmap for the commotion-client)

  • Network favorites (save signature and address' of applications on the network you like)
  • Node management tool-kit (for remote management and monitoring of commotion-router's)

Extension Development

Structure

An extension can contain the following components.

├── extension_name
│   ├── __init__.py 
│   ├── extension_name.conf
│   ├── main.py
│   ├── settings.py
│   ├── toolbar.py
│   ├── tests.py
│   └── ui
│       ├── __init__.py
│       └── config_manager.ui

Interface Development

Unlike the core commotion_client code base which will be hand-written PyQt code extensions should be, whenever possible, developed using a PyQt graphical development environment that calls a python library written by the development team. By decoupling the graphical components from the underlying code that interacts with commotion we will ensure that the back end's of extensions are easy to update and test for developers unfamiliar with the PyQt API. This will also mean that those developers can rapidly build a functional GUI with a PyQt graphical environment that can later be polished and made compliant with the human interface guidelines.

Extension Packaging

Extensions are delivered to a user as a single "zip" file. Each extension must be bundled using the zip archiving format.

To package up an extension for the Commotion Client follow these steps.

  • Download the Commotion_Client repository.
  • Create a folder in the commotion_client/extensions/ directory with the name of your extension
  • Run make extensions from the root directory of the Commotion_Client
  • There should be a single zip file in the build/resources/ folder with the same name as your extension.
  • That file is your extension

Extension Verification

Much needed research on signature verification and UI/UX means this will not be implemented until Version 2.0.

In the future upon loading, and extension may, optionally, be checked against a "verification" text file containing a pgp signature of the compressed extension that the user has obtained separately from the application.

Adding Extensions to Builds

Extensions are built-in to the Commotion client by adding them to the extension folder and then adding that folder name to the core_extensions list in the setup.py.

core_extensions = ["config_editor", "main_window", "your_extension_name"]

Default Extension Installation Directories

OSX:

  • user: $HOME/Library/Commotion/extension_data/
  • global: /Library/Application Support /Commotion/extension_data/

Windows:

  • user: %APPDATA%\Local\Commotion\extension_data\
  • global: %COMMON_APPDATA%\Local\Commotion\extension_data\
    • The %APPDATA% path is usually C:\Documents and Settings\User Name\Application Data; the %COMMON_APPDATA% path is usually C:\Documents and Settings\All Users\Application Data.

Linux:

  • user: $HOME/.Commotion/extension_data/
  • global: /usr/share/Commotion/extension_data/

Extension Config

An extension config file is used my the Commotion Client for the installation and execution of extensions. This JSON formatted file contains the following values.

naming convention: Commotion config files must end in .conf and cannot contain any invalid characters for the platform that they are installed on. Because the Commotion Client will be extended to be at least OSX, Win, and Linux compatible the following characters should be avoided in all names. |\?*<":>+[]/

example config: A complete config file will look like this.

{

"name":"test_ext001",

"menu_item":"Test Extension 001",

"menu_level":10,

"parent":"Test Suite",

"settings":"mySettings",

"toolbar":"myToolBar",

"main":"myMain"

}

Extension Config Properties

name

overview: The name of the extension. This will be the name that the commotion client will use to import the extension after installation, and MUST be unique across the extensions that the user has installed.

default value:

  • None: Required Value

example usage:

import os.path

if os.path.isfile("commotion_client/extensions/"+name):
    from extension import name

relevant files:

  • commotion_client/utils/extension_manager.py

menu_item:

overview: The name displayed in the sub-menu that will load this extension. This is a string that is between 2 and 40 chars.

default value:

  • str(config.name)

relevant files:

  • commotion_client/GUI/menu_bar.py
  • commotion_client/utils/extension_manager.py

menu_level:

overview: The level at which this sub-menu item will be displayed in relation to other sub-menu items. This number must be between 0 and 100. The lower the number the higher up in the sub-menu.

default value:

  • int(10)

relevant files:

  • commotion_client/GUI/menu_bar.py
  • commotion_client/utils/extension_manager.py

parent:

overview: The top-level menu-item that this extension falls under. If this top-level menu does not exist it will be created. The top-level menu-item is simply a container that when clicked reveals the items below it. This is a string that is between 2 and 40 chars.

default value:

  • str("Extensions")

relevant files:

  • commotion_client/GUI/menu_bar.py
  • commotion_client/utils/extension_manager.py

main: (optional)

The file name to use to populate the extensions initial view-port. This can be the same file as the settings and toolbar as long as that file contains seperate functions for each object type.

default value:

  • str("main")

example usage:

from extension import name.main

self.extension_viewport = main.Viewport()

relevant files:

  • commotion_client/GUI/main_window.py
  • commotion_client/utils/extension_manager.py

settings: (optional)

The file that contains the settings page for the extension. If this is not included in the config file and a "SettingsMenu" class is not found in the file listed under the "main" option the extension will not list a settings button in the extension settings page.

default value:

  • str(config.main)

example usage:

from extension.name import settings

self.settings_menu = settings.SettingsMenu()

relevant files:

  • commotion_client/GUI/extension_settings.py
  • commotion_client/utils/extension_manager.py

toolbar: (optional)

The file that contains the function that will return the custom tool-bar when run. The implementation of this is still in development. If not set and a "ToolBar" class is not found in the file listed under the "main" option the default toolbar will be implemented.

default value:

  • str(config.main)

example usage:

from extension.name import toolbar as extension_toolbar
from GUI import toolbar as default_toolbar

try:
    self.toolbar = extension_toolbar.ToolBar()
except AttributeError as _excpt:
    self.toolbar = default_toolbar.ToolBar()

relevant files:

  • commotion_client/utils/extension_manager.py

tests: (optional, but bad form if missing)

The file that contains the unitTests for this extension. This will be run when the main test_suite is called. If missing you will make the Commotion development team cry.

default value:

  • str("tests")

example usage:

from extension.name import tests

suite = unittest.TestLoader().loadTestsFromModule(tests)
unittest.TextTestRunner(verbosity=2).run(suite)

relevant files:

  • commotion_client/utils/extension_manager.py
  • tests/run_tests.py
  • commotion_client/tests/run_unittests.py
Add a custom footer
Add a custom sidebar
Clone this wiki locally