User Tools

Site Tools


Sidebar

plugins:01_files

Plugin API: File Structure

At the very minimum an XTension plugin consists of a folder that contains the necessary files and any other resources for your plugin. The “info.json” file that describes your interface, communications options and unit types. The “XTensionHelpers.py” file appropriate for the plugin API version that you are using that provides constants and helper functions necessary for communicating with XTension. Lastly the main script file as defined in the info.json file which will be loaded and sent all the various events from XTension and communications.

The name of the plugin folder must be unique across all available plugins as they must all live in one of two folders so you should use a bundle style file identifier that includes your name or your company name and the name of your plugin. Awesomeware warp or some such.

Plugin Installation

As of version 9.3.1 there is not a hook for installing or managing plugins in XTension itself. That will come in a future update but for the moment plugins must be installed manually.

Plugin Search Path

There are 2 places where plugins can be installed. The recommended placement is inside the users XTension database. The XTension database is a bundle folder. Inside the bundle is a folder named “Pitchers” (historically named Pitchers as the helper apps within “Pitch” the common interchange formatted data packets up to XTension) In a future release this will be changed to be called “Plugins”.

If you place the plugin folder inside that Pitchers folder within the database then the plugin files will be backed up along with the XTension database nightly as well as moving with the XTension install to any new machines or updates that the user might perform.

If for some reason you don’t wish to install the plugin inside the Database it can be installed in the XTension Support folder in the users Application Support folder. You will find a folder there also currently called “Pitchers” which will soon be renamed “Plugins” this is not the preferred install location for a plugin as it will then be separate from the user data and may need to be re-installed if the user moves to a new machine and does not preserve the application support folder but only their database.

Since accessing either of those folders is a complicated bit extra work for the user there are 2 menu items under the Database menu of XTension: “Reveal Plugins Folder For This User” which shows the Application Support folder, and “Reveal Plugins Folder In This Database” which will reveal the folder in the current active database in the finder. This makes it much easier to describe how to install the plugin until XTension can manage them itself.

XTension Finds New Plugins

It is not necessary to quit and restart XTension to have it discover new plugins. The plugin search locations are rescanned whenever the New Interface dialog is opened so your new plugin should be available in the list as soon as it’s in one of those locations and the user opens the window to create a new interface. If the New Interface sheet window is being displayed the window must be closed and re-opened to discover new plugins.

Updating Existing Plugins

Again, it is not necessary to quit and restart XTension when replacing a plugin with a new version. Changes to the info.json data will be available immediately however if the scripts have changed any currently running interface will have to be disabled and re-enabled to reload the scripts.

Standard Python Includes

In your Python scripts you need to include both the entirety of the XTension module and the XTensionHelpers module. This should be the first line of your main script entry point as well as anywhere else you need to use any of the XTension provided commands.

from XTension import *
from XTensionHelpers import *

Previous:The XTension Plugin API | NEXT:Plugin API: info.json and Communication Settings

plugins/01_files.txt · Last modified: 2017/07/14 13:21 (external edit)