Plugin Installation Guide

Preface:

This document explains how to install and configure plugins for Editra. It is broken into two sections, the first section describes using the built-in Plugin Manager and the second section describes the manual installation of plugins.



Plugin Manager:


The plugin manager can be opened by going to Tools=>Plugin Manager

Part 1:

Configuration


Plugin Manager

The above screenshot shows the plugin configuration page in the Plugin Manager. Its usage is fairly straight forward and easy to understand, simply check or uncheck the box next to the plugins name to enable/disable the plugin, and the plugins will be activated/deactivated the next time the program is launched.


Part 2:

Downloading Plugins


The Plugin Manager also features a built-in plugin downloader that automatically fetches plugins that are compatible with your python installation. The screenshot below shows the Download section of the Plugin Manager. As can be seen the usage is very similar to the configuration page, just select the desired plugins and click the "Download" button to download the plugin(s).

Plugin Downloader

Once the downloads are complete the Plugin Manager will switch to the installation page.


Part 3:

Installation

Plugins downloaded through the Plugin Manager are automatically added to the install list on the Installation Page, plugins that were downloaded manually or that came from elsewhere can be added to the list by simply dragging and dropping them into the list.

Plugin Installation

If an unwanted item was accidently added to the list it can be removed by selecting it and hitting "Delete" on the keyboard. Once all the items that you wish to install are in the list, choose the installation location by checking one of the boxes on the bottom of the page and then click on the "Install" button to complete the installation.

Thats all there is to installing and managing plugins through the Plugin Manager. If you enjoy doing things the hard way read on to the next section to see how to do it manually ;)




Manual Plugin Installation:


Part 1: Choosing the Correct Plugin

From version 0.1.0 Editra has support for plugins that allow extensions to be made to the editor without having to modify any of the internal code. The plugins that Editra uses are packaged as python eggs. Python eggs are basically a special zip file with the extension .egg. When downloading a new plugin it is important to get an egg that was built for the version of Python that you are using on your system. Luckily there are only two versions to choose from, and they are easily distinguishable by the file name. A typical plugin file name will be formatted as follows.

    AAA-X.X-py#.#.egg

    Key:
    AAA   = Plugin Name
    X.X   = Plugin Version (i.e 1.0)
    py#.# = Python version needed (either 2.4 or 2.5).

If you installed a binary version (Windows exe, or OS X dmg) of Editra you will always want the Python 2.5 version as this is what the binary distributions on these systems use.

If you are running a Unix/Linux version or installed manually using the source package you can check which version of Python you are using by typing the following at the command line. (note if using a source based version you will also need to install setuptools as an extra dependancy)

 python --version


Part 2:

Where to put your plugin

Now that you have downloaded the correct plugin that you need for your installation of Editra you need to put install it in the proper directory so that Editra knows where to find it. There are two separate (albeit very similar) explanations below, read the one that best describes your installation.

All instructions assume a default installation, if you have installed Editra in some other manner please interpret the instructions to point to your installation directory instead.

  1. Binary:

    • OS X:
      • Option 1: Plugin available to all users

        Editra.app should be installed in your Applications Folder (Shift+CMD+A), so using either Terminal or Finder navigate to that folder. Open Editra.app as a folder.
         If using Terminal: cd Editra.app\
         
         If using Finder: Ctrl+Click => "Show Package Contents"
        
        Then navigate to the following path:
         Editra.app\Contents\Resources\plugins\
        
        Finally copy the downloaded (*.egg) plugin to the above path.

      • Option 2: Plugin available to just your account

        Open up Terminal and enter the following command
        cp YOUR_PLUGIN.egg /Users/YOUR_ACCOUNT/Library/Application Support/Editra/plugins/.
    • Windows:
      • Option 1: Plugin available to all users By default Editra is installed to the following directory:
        C:\\Program Files\Editra
        If you have write access to that directory and want to make the plug available to all users of the system simply copy the plugin (*.egg) file you downloaded to the following directory.
        C:\\Program Files\Editra\plugins\
      • Option 2: Plugin available to just your account

        To make the plugin only available to your user account. Copy your downloaded (*.egg) plugin to the following directory.
        C:\\Documents and Settings\YOUR_USER_NAME\Application Data\Editra\plugins\

  2. Source Based Installation:

    • Option 1: Plugin available to all users To make the plugin available to all users on the system you need to copy the downloaded (*.egg) plugin to the plugin directory of your installation. Where this directory is located could be in one of many places depending on your system and what version of python you are using. I will make the assumption that if you are using the source version you know where to find the following path.
      YOUR_PYTHON_PATH\site-packages\Editra\plugins
    • Option 2: Plugin available to only your account To make the plugin only available to your account copy the downloaded (*.egg) plugin to the following path. Linux:
      $HOME/.Editra/plugins
      Macintosh:
      $HOME/Library/Application Support/Editra/plugins
      Windows:
      C:\\Documents and Settings\$USERNAME$\Application Support\Editra\plugins



Plugin Usage:

Now that you have a/some plugins installed you need to activate them, before they can be used. Just follow the following five steps to activate and enable your chosen plugins.

  1. Launch Editra
  2. Open the Plugin Manager
  3. Click on the Configure page
  4. Click the check box next to the plugin(s) you wish to activate
  5. Restart Edtira to enable the activated plugins

Notices

If Editra crashes or fails to start after installing a plugin there is likely something wrong with the plugin. So if this happens please remove the plugin from the plugin directory and try the editor again to see if the plugin was at fault for the crash before reporting issues with Editra.