Altering the Plugin Template

maverick · 2015-09-10 13:52:40

I have mucked about the code of various plugins over the years, but have only the most rudimentary understanding of them. So I’m not sure if what I am suggesting is workable or desirable.

My understanding of the current Textpattern plugin template is that the meta data such as author, version, etc. goes at the top, followed by the help/documentation, then the php code proper, all in a single file. This file is then encoded and ready for installation.

Using various plugins (such as ied_plugin_compose or the import/export plugins) you can bypass the encoded file and install the php file directly. However, it is still a single file.

Correct so far?

I also have a memory of reading a thread a while back where it was suggested that the help be broken out as its own file (possibly in textile format?) and then using some php magic the separate help and php file would be merged into one, encoded installable file? I think maybe Bloke mentioned that as a possibility?

The reason I ask, is the discussion about having a community list of plugins on github, and developing the ability to install directly from github.

One of the needs we have discussed related to Textpattern.org and in the github plugin discussion is the need to note what versions of Textpattern a plugin is known to work with. Other additional meta data might be of use as well – a dependency on another plugin for example.

However, the current Textpattern template does not provide a place for that type of information.

This got me thinking “what if”. What if the Textpattern plugin template was updated to a four file model – at least and especially on Github:

raw php file
Help/documentation file
Expanded Meta Data File
Encoded File

We could provide the desired information more accurately and more easily.

How this would best work – a xml file for the meta data, or a json file, etc. I’m not sure. I think it is do-able somehow — symphony extensions offer this functionality. We would need to specify the meta data schema.

Thoughts? Achieveable? Desirable? Good idea? Bad? Not enough need?

ruud · 2015-09-10 14:04:19

There’s a downside to letting a plugin author declare the plugin compatibility with TXP versions: if I write a plugin, I’d claim it was compatible with TXP 4.0.x and higher… but then comes along TXP 4.6 and the plugin isn’t compatible, which the plugin author couldn’t predict when he released it.

So the question is, should plugin compatibility be set only by the plugin author or also/instead by the community?

As for the template, I prefer to have everything in a single file.

maverick · 2015-09-10 14:21:18

The approach the Symphony extensions have uses is to have a base compatibility and a most recent version know to work with.

It the meta data includes a version w/in the range, it shows a yes on compatibility. It a version is not specifically included in a version it shows as “no”. Of course that does not mean it would not work, but that the meta data has not been updated to confirm it works.

Ideally there might be a yes/no/unknown option.

If we keep the single file approach, is it difficult to read just the meta data, or just the help/documentation from the github file repo?

ruud · 2015-09-10 14:34:44

Not difficult, it would just require an extra field in the template.

maverick · 2015-09-10 14:43:35

Disclaimer: I am not advocating that the approach by Symphony extensions are necessarily the right or best solution, but they seem farther down the road than we are on this, and are useful for inspiration.

As an xml based CMS, they use an individual meta data file with a specified schema. There are required and optional meta data fields. Below is an example that uses a number of the optional data fields:

<?xml version="1.0" encoding="UTF-8"?>
<extension id="multilingual_oembed_field" status="released" xmlns="http://symphony-cms.com/schemas/extension/1.0">
	<name>Multilingual oEmbed Field</name>
	<description>
	A multilingual version of the oembed_field extension

	Easily embed videos/images from ANY* website that implements the oEmbed format. See http://oembed.com and https://github.com/Solutions-Nitriques/oembed_field
	</description>
	<repo type="github">https://github.com/DeuxHuitHuit/multilingual_oembed_field</repo>
	<url type="discuss">http://symphony-cms.com/discuss/thread/110407/</url>
	<url type="issues">https://github.com/DeuxHuitHuit/multilingual_oembed_field/issues</url>
	<types>
		<type>Field</type>
		<type>Third Party Integration</type>
		<type>Multilingual</type>
	</types>
	<authors>
		<author>
			<name github="DeuxHuitHuit" symphony="nitriques" twitter="DeuxHuitHuit">Deux Huit Huit</name>
			<website>https://deuxhuithuit.com/</website>
		</author>
	</authors>
	<dependencies>
		<dependency version="1.8.9">oembed_field</dependency>
		<dependency version="2.5">frontend_localisation</dependency>
	</dependencies>
	<releases>
		<release version="1.0.2" date="2015-08-25" min="2.5.0" max="2.6.x">
			- Fixed a bug where the default language value was always returned in data sources
		</release>
		<release version="1.0.1" date="2015-06-26" min="2.5.0" max="2.6.x">
			- Added version checking for oEmbed (Fixed #2)
		</release>
		<release version="1.0" date="2015-05-15" min="2.5.0" max="2.6.x">
			- First release
		</release>
	</releases>
</extension>

Does offering a way to include meta data like this seem workable? If so, it seems like this would go a long way to building a robust browser/viewer/auto-installer.

Last edited by maverick (2015-09-10 14:44:39)

michaelkpate · 2015-09-10 14:53:06

ruud wrote #294664:

As for the template, I prefer to have everything in a single file.

Using one of my own Github repositories as an example michaelkpate/mkp_gravatar it includes

raw php file
Help/documentation file
Encoded File

The only one I don’t include is the “Expanded Meta Data File” partly because I created everything with ied_plugin_composer and it includes some basic metadata at the top of the Encoded File. My question is, what else would we need to include?

maverick · 2015-09-10 15:47:39

michaelkpate wrote #294676:

My question is, what else would we need to include?

I happen to like the data in the xml file I posted above. In particular I would add:

Releases
- revision notes – nice info to have
- Especially helpful for autmagically sending a cascading update: Update the github file and:
  - update the forum, (provided a forum plugin was written to pull in the info)
  - update the plugin author’s personal website,
  - update Textpattern.org

Compatibility
- each release has a compatibility line -
- this would be a key part of an on-going robust plugin tracking system

Dependencies (Obvious why)

Types
- Github has no real organizational features
- types allows a rudimentary tagging / categorizing system.
- This would be of great help:
  - on Textpattern.org
  - In a browser/viewer. Especially if the viewer has a sort/filter feature.

I personally find it useful to have the additional urls included – discussion forum, github, etc – as well as the plugin author’s website.

Once a plugin is on Github, and forked to the community, the community can help maintain at least key parts of the meta data.

Down the road, I could see a browser/view that

allows you to click on “About” to see the meta data in a modal window,
“help/docs” link would use the modal to let you read the documentation before installing, and
“code” to view the actual code if desired.
Next to these would be an install button, with a check box that allows you to install disabled or enabled.

In this fantasy browser/installer it could check the compatibility chart, and throw a warning “not listed as compatible, proceed at your own risk”.

maverick · 2015-09-10 16:02:59

A quick note on the xml meta data file above in relation to compatibility:

Symphony extension sites can show compatibility based on their meta data as follows:

If the Min and Max are left empty, it shows “unknown” compatibility for all versions
If the Min is set,
- it shows incompatible (no) for all prior versions to the Min
- Yes for the version in the Min. field.
If Min is set, but Max is empty,
- It shows no for versions prior to the minimum,
- it shows compatible(yes) on the version set for min,
- and unknown for subsequent versions.
If Min is set, and Max is set,
- it shows no prior to the min,
- yes for the min,
- compatible (yes) for all versions between min and max,
- and yes for the max version
If Min is not set, but Max is set,
- it shows unknown for all versions prior to the Max,
- compatible (yes) on the version set in Max,
- and incompatible (no) for subsequent version.

maverick · 2015-09-10 17:13:29

I see Jukka is doing something similar, but has built it out around Composer. I’m still trying to wrap my head around Github, and have only looked briefly at Composer.

There is a file called manifest.json which seems to function in part as a meta data file, though perhaps more than just meta data. It appears to call the ReadMe.textile file plus any other necessary code files (eg a php file).

It does provide an example if we choose json rather than xml to convey the info.

{
    "name": "rah_backup",
    "description": "Manages site backups",
    "version": "0.1.0",
    "type": 4,
    "author": "Jukka Svahn",
    "author_uri": "https://github.com/gocom/rah_backup",
    "order": 5,
    "flags": 3,
    "help": {"file" : "./README.textile"},
    "code": {"file" : [
        "./src/Rah/Backup.php",
        "./src/Rah/Backup/Exception.php"
    ]}
}

Last edited by maverick (2015-09-10 17:29:43)

maverick · 2015-09-10 17:29:02

If we used the current format, am I correct we add to the fields here?

$plugin['version'] = 'x.x';
$plugin['author'] = 'plugin author';
$plugin['author_uri'] = 'http://www.example.com';
$plugin['description'] = 'description';
$plugin['type'] = 5;

Something like:

$plugin['min_txp_version']="4.1"
$plugin['max_txp_version']="4.5.7"

Can this format handle nested information?

xml example:

<release version="1.0.2" date="2015-08-25" min="2.5.0" max="2.6.x">

How would that translate into the current format?

$plugin['version']="0.1" $plugin['min_txp_version']="4.1" $plugin['max_txp_version']="4.4"
$plugin['version']="0.2" $plugin['min_txp_version']="4.4" $plugin['max_txp_version']="4.5.7"

Or perhaps this is where a separate meta data file using json or xml would be easier, and keep the plugin code cleaner?

Last edited by maverick (2015-09-10 17:31:17)

ruud · 2015-09-10 19:27:24

maverick wrote #294691:

If we used the current format, am I correct we add to the fields here?

$plugin['version'] = 'x.x';...

Something like:

$plugin['min_txp_version']="4.1"...

Yes. or something like (although that’s probably too much work for plugin authors):

$plugin['compatible'] = array('4.0', '4.0.1', ... '4.5', 4.5.1', ... '4.5.7');

Can this format handle nested information?

Do you mean info about multiple plugin versions? No, nor should it, because you’d add it to a single plugin version.

The benefit of keeping it all contained in a single file for one version of a plugin is that you can generate all the other suggested files from that single file instead of having to maintain separate files manually. I can imagine textpattern.org taking advantage of that, by periodically scanning all known GIT repositories (or we simply fork each plugin into a central repository), collecting the raw plugin.php files, so TXP.org then knows about compatibility, can show source code, can create the .txt files for copy/pasting and can show you the plugin help on the website.

What Jukka does with his plugins and Composer is interesting. I wonder how well that integrates with the way users typically install plugins (via the TXP admin interface).

maverick · 2015-09-10 19:52:36

ruud wrote #294694:

Or something like

$plugin['compatible'] = array('4.0', '4.0.1', ... '4.5', 4.5.1', ... '4.5.7');...

That makes sense.

Do you mean info about multiple plugin versions? No, nor should it, because you’d add it to a single plugin version.

Yes, I was picturing sort of a master “release” history. But that would be working from a model with a separate file, and it tracks with various repo updates. From a single file model, that would not make sense, as you point out.

Stef also mentioned Jukka’s use of Composer in the thread where we are discussing a curated list of plugins.

Ruud — are you familiar with Composer and it’s use? If so, is the current plugin format something that we would use with Composer (both/and), or is it an alternative format (either this format or that format)?

Textpattern CMS

Textpattern CMS support forum

#1 2015-09-10 13:52:40