[RFC] Add Author Notes to Extension MetaData

Note: We are moving the topics of this forum and it will be deleted at some point

Publish your own request for comments/change or patches for the next version of phpBB. Discuss the contributions and proposals of others. Upcoming releases are 3.2/Rhea and 3.3.
User avatar
MattF
Extension Customisations
Extension Customisations
Posts: 675
Joined: Mon Mar 08, 2010 9:18 am

[RFC] Add Author Notes to Extension MetaData

Post by 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"
Has an irascible disposition.

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: [RFC] Add Author Notes to Extension MetaData

Post by nickvergessen »

I'd not say author notes, but allow extensions to display some messages/pages after enabling/disabling/purging
Member of the Development-TeamNo Support via PM

leschek
Registered User
Posts: 164
Joined: Tue Aug 28, 2012 1:30 pm

Re: [RFC] Add Author Notes to Extension MetaData

Post by leschek »

And they should be translatable...

User avatar
MattF
Extension Customisations
Extension Customisations
Posts: 675
Joined: Mon Mar 08, 2010 9:18 am

Re: [RFC] Add Author Notes to Extension MetaData

Post by 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.
Has an irascible disposition.

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: [RFC] Add Author Notes to Extension MetaData

Post by 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.
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: [RFC] Add Author Notes to Extension MetaData

Post by 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).
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: [RFC] Add Author Notes to Extension MetaData

Post by nickvergessen »

imkingdavid wrote: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
Member of the Development-TeamNo Support via PM

User avatar
MattF
Extension Customisations
Extension Customisations
Posts: 675
Joined: Mon Mar 08, 2010 9:18 am

Re: [RFC] Add Author Notes to Extension MetaData

Post by MattF »

nickvergessen wrote: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.
Attachments
Screen Shot 2014-03-20 at 4.40.55 PM.png
Screen Shot 2014-03-20 at 4.40.55 PM.png (11.32 KiB) Viewed 16632 times
Has an irascible disposition.

User avatar
DavidIQ
Customisations Team Leader
Customisations Team Leader
Posts: 1904
Joined: Thu Mar 02, 2006 4:29 pm
Location: Earth
Contact:

Re: [RFC] Add Author Notes to Extension MetaData

Post by 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.
Image

User avatar
MattF
Extension Customisations
Extension Customisations
Posts: 675
Joined: Mon Mar 08, 2010 9:18 am

Re: [RFC] Add Author Notes to Extension MetaData

Post by MattF »

DavidIQ wrote: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.
Has an irascible disposition.

Post Reply