plugins:01_files
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
plugins:01_files [2018/07/06 15:43] – [Plugin API: File Structure] James Sentman | plugins:01_files [2018/07/06 17:17] – James Sentman | ||
---|---|---|---|
Line 3: | Line 3: | ||
====Folder Name==== | ====Folder Name==== | ||
An Xtension plugin is a folder or a bundle. The name must end with the “.isf” suffix so that XTension will recognize the folder or bundle as a plugin. The name should be unique and follow something like a bundle naming convention. So don’t just name your plugin “insteon.isf” as thats the built in XTension plugin naming convention. XTension reserves all non-bundle naming plugin names. While the exact layout of the names is up to you you should use a path that contains your name or company name and then the plugin type so that the file can be easily recognized as to what it is by a user and also that it will always be unique. “james_insteon.isf” or “james.insteon.isf” are all acceptable. | An Xtension plugin is a folder or a bundle. The name must end with the “.isf” suffix so that XTension will recognize the folder or bundle as a plugin. The name should be unique and follow something like a bundle naming convention. So don’t just name your plugin “insteon.isf” as thats the built in XTension plugin naming convention. XTension reserves all non-bundle naming plugin names. While the exact layout of the names is up to you you should use a path that contains your name or company name and then the plugin type so that the file can be easily recognized as to what it is by a user and also that it will always be unique. “james_insteon.isf” or “james.insteon.isf” are all acceptable. | ||
+ | |||
+ | ====Minimum Requirements==== | ||
+ | At the very least the plugin folder must contain the info.json file that describes the plugin and the units that it will create and the main script file that will be executed and passed the setup info from XTension. You can also include any other support files or python includes that are necessary for your plugin to run. | ||
+ | |||
+ | ====Python Requirements==== | ||
+ | At this time the plugin support files will only run in python 2.7. Python 2.7 is included in OSX so this is the best language to use as it won’t require that you embed the entire python 3 runtime into the plugin or require the user to install python 3 first. | ||
+ | |||
+ | If your plugin needs python modules that are not available by default on OSX best practice is to include them alongside the plugin files. You can usually do this by making a copy of the needed library into the plugin folder. I would recommend using pip to install the package onto your development mac. Then going to python’s site packages folder and getting the installed folder from there. You’ll find the site packets folder on OSX in: / | ||
+ | |||
+ | You should also verify that the licenses of any modules you are including allow you to do so. | ||
====Plugin Installation==== | ====Plugin Installation==== | ||
- | As of version 9.3.1 there is not a hook for installing | + | As of version 9.4.5 the plugin manager |
- | ===Plugin Search Path=== | + | |
- | There are 2 places where plugins | + | Plugins |
- | \\ | + | |
- | If you place the plugin folder | + | |
- | \\ | + | |
- | If for some reason you don’t wish to install | + | |
- | \\ | + | |
- | 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 | + | |
===XTension Finds New Plugins=== | ===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. | 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=== | + | During development it may be necessary to open the edit interface dialog to get changes to a plugins info.json file to be reloaded. |
- | Again, it is not necessary to quit and restart | + | |
+ | |||
+ | ====XTension Standard Python Includes==== | ||
+ | XTension | ||
+ | |||
+ | Upon launch XTension | ||
+ | |||
+ | <code python> | ||
+ | # | ||
+ | # Importing Necessary XTension Connection Modules | ||
+ | # | ||
+ | # normally you can just include this small block of code as is unless you need to control | ||
+ | # specifically which plugin module version you need to include | ||
+ | # | ||
+ | # import the current version of the XTension python plugin modules by setting our path to the | ||
+ | # contents of the helper file in the XTension Support folder | ||
+ | # if you have had to make changes to the xtension support modules or wish to guarente that | ||
+ | # a specific version is included with your plugin then you may instead include the 2 support | ||
+ | # files in the same folder with your application. You would comment out the following up | ||
+ | # until the instructions below for how to include them in that case. | ||
+ | # doing it this way does guarente that you're using the versions that are most compatible | ||
+ | # with the currently running | ||
+ | # are any changes to the higher level interface to XTension that would potentially cause | ||
+ | # problems for a plugin then the previous version will be preserved | ||
+ | # link to go direct and not through /current | ||
+ | # | ||
+ | |||
+ | from os.path import expanduser | ||
+ | userHomePath = expanduser( ' | ||
+ | del expanduser | ||
+ | |||
+ | # XTension will always create this file in the XTension Support folder when it starts up | ||
+ | # with a path to the python support files that we need to add to the search path so | ||
+ | # this program can load them. | ||
+ | pluginLocationFile = open( userHomePath + '/ | ||
+ | if pluginLocationFile.mode == ' | ||
+ | pluginLocationPath = pluginLocationFile.read() | ||
+ | pluginLocationFile.close | ||
+ | else: | ||
+ | print( "Error opening the XTension Plugin Includes path file, cannot continue" | ||
+ | sys.exit() | ||
+ | |||
+ | # | ||
+ | # the pluginLocationPath will need either a specific version number or /current appended | ||
+ | # as the path is to the folder that contains the different version folders. To access | ||
+ | # the current most recent version as included in the currently running XTension append "/ | ||
+ | # to access a specific version append that something like "/ | ||
+ | # | ||
+ | |||
+ | pluginLocationPath += "/ | ||
+ | |||
+ | sys.path.append( pluginLocationPath ) | ||
+ | |||
+ | from xtension_plugin.xtension_constants import * | ||
+ | from xtension_plugin.xtension_plugin import * | ||
- | ====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 * | ||
</ | </ | ||
+ | |||
+ | ====Custom Script Handlers==== | ||
+ | |||
+ | Your plugin can send doScript commands that can execute named handlers with passed data in either the Interface Script for your interface, or if an address and addressprefix is included then the handler can be executed in a Unit’s ON script, if any. You can define script handlers in the info.json file which will point to specific file names inside your plugin folder. For example if you have an overtemperature event that you can send to the unit you may wish to allow the user to take specific action based on that by executing an “on overtemperature( currentTemp)” handler in the units ON script. In order to make it easier for the user to insert these handlers you can add any number of special handlers to the “Insert” toolbar dropdown menu for the ON script of the unit type. Those files are defined in the info.json file and can be included along with the plugin. | ||
+ | |||
+ | ====Icon Support==== | ||
+ | |||
+ | If your plugin includes a folder named “Icons” then those icons will be loaded along with your plugin and be made available as unit icons inside the application. You can include custom icon images for your units in this way. Use the defaultOnIcon and defaultOffIcon keys into the info,json file to assign any icons as the default. | ||
+ | |||
+ | Icon file format should be png with a mask though jpeg and gif files are also supported. | ||
Previous: | Previous: | ||
+ | |||
+ | ====History==== | ||
+ | * 7/6/2018 updated for plugin API 2.0 |