plugins:01_files
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionLast revisionBoth sides next revision | ||
plugins:01_files [2017/07/14 13:21] – external edit 127.0.0.1 | plugins:01_files [2018/08/11 16:14] – more API v2 updates James Sentman | ||
---|---|---|---|
Line 1: | Line 1: | ||
=====Plugin API: File Structure===== | =====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==== | + | ====Folder Name==== |
- | As of version 9.3.1 there is not a hook for installing | + | An Xtension plugin |
- | ===Plugin Search Path=== | + | |
- | There are 2 places where plugins can be installed. The recommended placement is inside | + | ====Minimum Requirements==== |
- | \\ | + | At the very least the plugin folder |
- | If you place the plugin folder | + | |
- | \\ | + | ====Python Requirements==== |
- | If for some reason you don’t wish to install | + | 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 |
- | \\ | + | |
- | Since accessing either | + | If your plugin |
+ | |||
+ | Please verify that the licenses | ||
+ | |||
+ | Lastly | ||
===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 | + | Plugin installation |
- | ===Updating Existing Plugins=== | + | It is not necessary to quit and restart XTension |
- | Again, it is not necessary to quit and restart XTension | + | |
- | ====Standard Python Includes==== | + | During development it may be necessary to open the edit interface dialog to get changes to a plugins info.json file to be reloaded. |
- | In your Python scripts | + | |
+ | |||
+ | ====XTension | ||
+ | |||
+ | XTension provides 2 python files that will be necessary for any plugin. If your plugin requires a specific version of the plugin includes | ||
+ | |||
+ | Upon launch XTension will create a file in it’s ~/ | ||
+ | |||
+ | <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 XTension version however and so this is recommended. If there | ||
+ | # 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 and you can just change the | ||
+ | # 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 | ||
+ | # 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 * | ||
+ | |||
+ | |||
+ | </ | ||
+ | |||
+ | |||
+ | ====Custom Script Handlers==== | ||
+ | |||
+ | Just like the user can send custom commands to the plugin via the tell xUnit “name” to doAPluginFunction() your plugin code can send a command to execute a handler in the interface or unit’s On script. In order to make these easier for the user to insert properly | ||
+ | |||
+ | Create a text file that contains the handler definition for AppleScript and enough comments to describe what it does and how to use it. Then include a structure similar to this in the unit definition portion of the info.json file. You can include | ||
+ | |||
+ | At this moment only AppleScript handlers are supported, but in the future if we adopt other languages there will be the opportunity to include specific include information for those as well. | ||
+ | |||
+ | An example of what you might include in the info.json file. This is from the VeraUI7 plugin: | ||
< | < | ||
- | from XTension import * | + | " |
- | from XTensionHelpers import * | + | {" |
+ | " | ||
+ | " | ||
+ | " | ||
+ | ] | ||
</ | </ | ||
+ | since the AppleScriptHandlers is an array you can include any number of handlers there. The key “file” should contain the name of the text file that contains the handler prototype. | ||
+ | To add the same for the Edit Interface Script dialog include that same structure but at the root level of the JSON file rather than inside a unit definition. | ||
+ | |||
+ | ====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. | ||
+ | |||
+ | Note, that this is unimplemented as of XTension 9.4.8.\\ | ||
+ | \\ | ||
Previous: | Previous: | ||
+ | |||
+ | ====History==== | ||
+ | * 7/6/2018 updated for plugin API 2.0 |