How to make your own custom version of a plugin

[James Sentman]

Good morning folks,

It occurs to me that several of you have made your own edits to some of the plugin files now and that I should outline how to turn one into your own that won’t either break the code signature of the app or get overwritten with each update. Of course you should all still send me your code changes, or let me know that you have done such a thing and I will create an open source git hub archive of the real code for you to fork and possibly contribute to. I’ve done that for several things already but getting everything into it did not seem like a huge rush.

So if you have, or wish to, make changes to a plugin file that is part of XTension here is how to do it without editing inside the actual app.

Inside your Database is another plugins folder that is for exactly this, a place you can install plugins that are not included in the app. When you do an install plugin from the Database menu this is where it puts it. There is even a “Reveal Plugins Folder In This Database…” menu item in the Database menu that will open the database for you in the finder and highlight the plugins folder within it.

Now you can make a copy of the plugin.isf folder from within XTension into that folder. XTensions built in plugins you can get to by doing a right click and “show package contents” then opening the Contents folder, then the Resources folder and finally the Plugins folder. 

You MUST change the folder name of your newly copied plugin folder, it must end in .isf I would recommend regular unix naming conventions possibly using underscores instead of spaces and to create your own name space that you use for such things just so that it’s easy to remember. For example if you are editing the tplink.isf plugin then change the name to tplink_peter.isf or something, obviously using your own name unless peter is someone close to you and you think it’s humorous to use his name...

and then you must edit the copied “info.json" file to reflect the changes and to make sure XTension doesn’t confuse it with the built in version.

You can use a json editor, or just Text Edit as long as you are careful not to turn it into styled text when saving it back again. The keys that you must change are:

The name line is:
    "name":"Kasa & TP-Link”,

You should change the name to reflect which one you altered so you can find it in the popup list of plugins, something like:
    “name”:”Kasa & TP-Link Peter”,

The tag line is:
    "tag":"xt.tplink”,

This is used internally by XTension to reference this plugin, so if this doesn’t change it will think the 2 plugins are versions of the same one and try to use the newest one but there may be other confusions so this must change and must be unique for every plugin. I would use the same naming convention so possibly something like:
    "tag”:"peter.tplink”,

The isf line:
    "isf":"tplink.isf”,

Change this to be the name of the parent folder so continuing the same example as above it would be:

    "isf":”tplink_peter.isf”,


Save the file (verifying the json if possible, otherwise XTension may log an error as it loads the plugin if there are any json syntax errors) and restart XTension and you will see your new plugin listed. If it does not show up look for an error in the log at startup where it failed to parse the json file. I would then recommend running the file through a json validator like at https://jsonformatter.org or elsewhere to point exactly what went wrong, it’s probably a missing comma or something not in quotes ;)



Things you MAY change but do not have to:

The “desc” line is the longer description displayed in parans and smaller non-bold type in the popup menu of plugins, so changing it to something like “My custom version of the plugin to fix things James hasn’t gotten around to yet” would be acceptable.

There are 2 version tags that you may wish to change as well. DO NOT change the “APIVersion” this is used internally to indicate which version of the plugin includes you are using and what low level protocol it should use to talk between the plugin and XTension and not something that you can change like this.

The “vers” line is an integer and should increment with each new version. This just simplifies internally letting XTension know this is a different version than what it had installed and which version is newer than the other, regardless of the format of the user readable version string. 

The “readableVers” (and yes, capitalization counts for these) is what is displayed to the user in the various interfaces for the version. It is never parsed by XTension and can be any short string. Might just say “1.0” or it might say “4.2.34.7” or possibly “4.5.23 b3” but longer strings may not fit properly into various display windows around the app. So keep it short if possible.

You can change what is used for the two web links in the edit interface window. The “more info” link takes it’s value from the key “link” in the info file and the “wiki” link takes it’s link from the “wiki” keyed line. Not all plugins have either or both, but you can add them to the file as long as you follow json formatting properly. The data itself MUST be properly json escaped so the tplink wiki link actually looks like this:

"wiki":"http:\/\/machomeautomation.com\/doku.php\/supported_hardware\/tplink",

The “info” tag, which also may not already be present in every plugin, contains a slightly longer description that is displayed in the edit interface window when a particular plugin type is selected. 


And then you have your own version that you can keep separate from the one in the app, not break the code signing and not get it overwritten every time you update the app.

Thanks,
 James


James Sentman                       http://www.PlanetaryGear.org		http://MacHomeAutomation.com