[RFC] Add Author Notes to Extension MetaData

[MattF]

Extension authors need a way to communicate information about their extensions to the users inside phpBB.

MODs allowed this with the Author Notes section in the MOD.XML file.

This is always a good place to tell the user where they may find any settings/controls to their new extension. Where they may be able to find extra support (links). Or any information they should know about the extension they just installed installed, like if it needs permissions created before it will appear to work, how it all works (if its complicated), etc.

I think this could be added to the "Details" link of the extension manager, and added to the Composer.json metadata under the label of "Author Notes" and could come after the requirements, but before all the Author Names are listed on the details page.

For example:

Authour Notes: You can configure this extension's settings by visiting the "Extensions" tab above. The extension was installed in a disabled state, so you will need to enable it to take effect. You can adjust how many foobars it displays and use phpBB's caching feature to speed up its performance. Most importantly, you should also visit the Permissions tab above -> Group Permissions and define which groups you would like to be able to use the features of this extensions. Further support can be found at http://www.phpbb.com/myextnesionslocation"

[nickvergessen]

I'd not say author notes, but allow extensions to display some messages/pages after enabling/disabling/purging

[leschek]

And they should be translatable...

[MattF]

The benefit of putting it in the Extension Details, is the Admin can revisit it anytime they want... In case they forget some months or years later on and want to make a change. If it's tied to the enable/disable process... they only get one shot to see the instructions... and many will probably click ok before reading them and then they are out of luck, and have missed their chance to read them - or re-read them if they realize they may have misunderstood something... In which case its a trip to the support forum to bug the authors.

Besides, ins't the extension details, by the very nature of that title, the best place to get all the details about the extension from anyways, including how to use it?

It could of course be named something else than "Author Note"s inside the details section:
Extension notes:
Extension instructions:
Usage notes:
Usage details:
Important details:
Additional information:
How to use:
How to setup:

Like all the composer meta data, it would be somewhat optional. So if you don't need to add anything, it just won't appear in your extensions details. But it'd be nice to have if we could.

[imkingdavid]

With MODX we have both Authors Notes and Do It Yourself instructions. The former is for anything the author wants to mention about the MOD, such as requiring a certain version of PHP or another MOD dependency, or an extra feature in a contrib folder. Of course, with Extensions you can already specify a PHP version and hopefully will eventually be able to specify other extension dependencies and such.

We should probably retain an Authors Notes section just in case there's something the extension author wants to let admins know before they install the extension. We should also keep the DIY section, but perhaps using one of the labels you specified above (or perhaps "Setup Instructions"? something like that)

It might also be good to able to link to the extension's settings page. We could let the extension author provide a "settings_page" (or something) field in JSON that specifies either the url relative to the admin directory (would need append_sid run on it so the user doesn't get logged out), or a URL to a non-admin page, as suggested here. This would be optional, but if present would display on the Extensions list page, as well as after the extension is installed. Note that WordPress has this sort of functionality, though I don't think the settings URL is manually set because I think they have a more standardized way of organizing the admin section so that each plugin gets its own page, instead of potentially having settings mixed into the core pages.

[imkingdavid]

And to add, I think making them translatable as leschek suggested would be a good idea, so how about an autoloaded ./ext/<vendor>/<ext>/language/<iso>/install.php (or something) with some predefined language KEYS the extension author can provide (we should make them empty by default in phpBB and only show them if they are provided by the extension).

[nickvergessen]

And to add, I think making them translatable as leschek suggested would be a good idea, so how about an autoloaded ./ext/<vendor>/<ext>/language/<iso>/install.php (or something) with some predefined language KEYS the extension author can provide (we should make them empty by default in phpBB and only show them if they are provided by the extension).

We can also use something like {VENDOR}/{EXT}_ as a prefix to the language key, so we don't need to empty anything.

As for adding stuff, keep in mind, that composer.json is a special json format: https://github.com/composer/composer/bl ... chema.json

[MattF]

As for adding stuff, keep in mind, that composer.json is a special json format: https://github.com/composer/composer/bl ... chema.json

Well, according to that, there is nowhere in the composer.json spec where this would fit in.

So That brings us back to the central question, how is the best user-interface way to present this? Maybe under the options list as an optional "Help" link?

That "Help" link would load the ./ext/vendor/extension/language/iso/info.php (or help.php or info_help.php, we should standardize it) if it exists, to show the user additional information about how to set up and use the extension.

[DavidIQ]

I like that idea. Info.php is what gets my vote in this case. The link would only be present if the file is present. That keeps this away from the extensions management page and will prevent the huge clutter I think this would create if we were to add this somewhere there instead. Not sure if it should come up in a new window or just load in the parent.

[MattF]

Not sure if it should come up in a new window or just load in the parent.

Well, if phpBB had nice modals, I'd say that for sure.