Mac Home Automation

User Tools

Site Tools

You are here: Macintosh Home Automation With XTension » plugins » Plugin API: File Structure
plugins:01_files

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Last revisionBoth sides next revision
plugins:01_files [2018/07/06 17:17] – James Sentmanplugins:01_files [2018/08/11 16:14] – more API v2 updates James Sentman
Line 5: Line 5:
  
 ====Minimum Requirements==== ====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.+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 or executable 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==== ====Python Requirements====
Line 12: Line 12:
 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: /Library/Python/2.7/site-packages any modules you have installed will be there. Only the actual module named folder is necessary to be copied. You will not need the distribution info or the .egg files or other support folders. Not all plugins folders are obvious from their names however, and some create more than one folder. It’s best to look at the folder before and after doing the module install so that you are sure what you need to copy. Once the files are copied to the plugin folder use pip to uninstall them properly from the system and make sure that your plugin still runs.  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: /Library/Python/2.7/site-packages any modules you have installed will be there. Only the actual module named folder is necessary to be copied. You will not need the distribution info or the .egg files or other support folders. Not all plugins folders are obvious from their names however, and some create more than one folder. It’s best to look at the folder before and after doing the module install so that you are sure what you need to copy. Once the files are copied to the plugin folder use pip to uninstall them properly from the system and make sure that your plugin still runs. 
  
-You should also verify that the licenses of any modules you are including allow you to do so. +Please verify that the licenses of any modules you are including allow you to do so. 
  
- +Lastly for Python you should pre-compile your python scripts so that you can include both the .py and .pyc files. This makes sure that the plugin folder doesn’t actually change it’s contents when you run it. If we are able to code sign a plugin file and python creates that file in the folder after it’s signed and verified then that will break the code signature and could result in a message from OSX about the application being corrupt or damaged.
-====Plugin Installation==== +
-As of version 9.4.5 the plugin manager is not completely implemented. There is no facility to check plugin versions or recommend updates or to install directly from the internet yet but those things are coming. Installing plugins from inside the app is implemented however. Once the plugin is downloaded but the user and unzipped they can select “Install Plugin” from the Database menu. This will drop down a select folder dialog for them to locate the plugin folder and it will copy that folder and it’s contents into the Plugins folder in the current database and load the info file so that it will now be listed in the device type popup. If an existing version of the plugin is already in the database plugin folder then the existing one is moved to the trash and replaced with the new one. Upgrading plugin versions can be done in this way. Upgrading a plugin that is currently enabled and running will require disabling and re-enabling the interface after the new plugin is installed. +
- +
-Plugins are stored in the XTension Database inside the “Plugins” folder. You can manually remove or add them there as well if you wish. Use the “reveal database in finder” menu item from the Database menu to show the Plugins folder inside the current database. The Database is a package or bundle so if you wish to access it in the Finder control click on the file and select “show package contents.” Do not alter any other files inside the database.+
  
  
 ===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.+Plugin installation is discussed on the [[http://machomeautomation.com/doku.php/plugins#installing_and_un-installing_plugins|first page of the plugin docs]].  
 + 
 +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 a New Interface dialog is already open it’s popup is not refreshed and would need to be closed and re-opened in order to have the new plugin be listed.
  
 During development it may be necessary to open the edit interface dialog to get changes to a plugins info.json file to be reloaded. During development it may be necessary to open the edit interface dialog to get changes to a plugins info.json file to be reloaded.
Line 28: Line 26:
  
 ====XTension Standard Python Includes==== ====XTension Standard Python Includes====
 +
 XTension provides 2 python files that will be necessary for any plugin. If your plugin requires a specific version of the plugin includes you can simply copy them into the same folder with your application. Or to save space you can load them from inside the XTension app via the following code. If changes are ever made to the existing include files that could potentially break previous plugins I will increment the version and continue to include both versions inside XTension. You can link to the “current” version or to a specific version in your plugin code.  XTension provides 2 python files that will be necessary for any plugin. If your plugin requires a specific version of the plugin includes you can simply copy them into the same folder with your application. Or to save space you can load them from inside the XTension app via the following code. If changes are ever made to the existing include files that could potentially break previous plugins I will increment the version and continue to include both versions inside XTension. You can link to the “current” version or to a specific version in your plugin code. 
  
Line 87: Line 86:
 ====Custom Script Handlers==== ====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.+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 you can add any number of them to the “Insert...” toolbar item in the Edit Script window. They will be added to the list of XTension defaults when editing the On script of a plugin unit.  
 + 
 +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 any number of handler definitions for units or for the Interface script. 
 + 
 +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: 
 + 
 +<code> 
 +"appleScriptHandlers”:[ 
 +   {"handler":"centralScene",  
 +    "name":"Central Scene Handler",  
 +    "desc":"Button index and gesture type will be sent to this handler.",  
 +    "file":"centralscene_handler_applescript.txt"} 
 +] 
 +</code> 
 +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==== ====Icon Support====
Line 93: Line 110:
 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. 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. +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:[[:plugins|]]  | NEXT:[[:plugins:02_infojson|]] Previous:[[:plugins|]]  | NEXT:[[:plugins:02_infojson|]]