Pophelp in plugins?

jakob · 2025-04-04 06:00:04

EDIT: Bringing this over from another thread but under a new topic heading:

Bloke wrote #298945:

OK, pophelp first. Register a callback on the admin_help event with a ‘step’ of the language string and your plugin will get called:

register_callback('abc_pophelp', 'admin_help', 'some_language_string_key');

While looking for a way to include pophelp in a plugin using your example above, the info on admin_help in the docs, and dissecting the pophelp function, I’ve managed to get something working but is there a better way of doing this? Adding the data-item and passing it back to pophelp resulted in a loop.

register_callback('abc_pophelp', 'admin_help', 'help_item_name');

function abc_pophelp($evt, $stp, $ui, $atts) {
	$atts['data-item'] = gTxt('pophelp_' . $atts['help_var']);
	return sp.href(span(gTxt('help'), array('class' => 'ui-icon ui-icon-help')), '#', $atts);
}

and then:

pophelp_help_item_name => My help text goes here

in the plugin’s textpack.

Non-essential but out of interest: Can I also influence the title of the pophelp box using this method? The regular pophelp provides that in the title attribute the XML entry, but the textpack format is different here.

Bloke · 2025-04-04 07:18:45

Hmm, that is a conundrum. I never really fathomed a way to let pophelp files be loaded from anywhere other than core’s /lang directory, and we don’t really want people adding their own strings in there, or dumping their own files in.

Ideally, a plugin should read its own lang/{lang}_pophelp.xml file from its own directory and merge it with core’s ones, just like the textpack strings are read from anything with the plugin name in the txp_lang table and merged with core strings.

The ini format of the pophelp files isn’t ideally suited for this. The good news is that once it’s read into memory using parse_ini_file() there’s no reason we can’t load a second one in and then do some creative array merging to combine them. Would have to try something out. Putting pophelp in the lang table feels wrong and, as you say, doesn’t allow you to alter the headings.

I’ll give this some thought later or tomorrow. Thanks for the nudge.

jakob · 2025-04-04 11:22:15

No worries. It works for now and I imagine a file-based solution entails changing the plugin folder and compression routines (and perhaps plugins that do that too). To be honest, I’m not aware of any plugins with pophelp in them.

I was initially just asking if I had gone about it using the callback right way, by excerpting only the line from the function that shows inline pophelp rather than adding the inline help string and passing it to pophelp.

Bloke · 2025-04-13 21:54:30

Okay, give this commit a play. You can now make your own lang/{langcode}_pophelp.xml files inside your plugin’s folder and set up pophelp topics in there however you wish. For example, for adi_matrix, I would create adi_matrix/lang/en_pophelp.xml and construct entries like this inside it:

<?xml version="1.0" encoding="utf-8"?>
<resources>
<help lang="en">
    <group id="adi_matrix_admin" title="Matrix administration">
        <item id="admin_ordinal" title="Matrix order"><![CDATA[
<h2>Matrix order</h2>
<p>Supply any value here to influence the order in which the matrices appear in a menu.</p>
<p>The matrices will be displayed in alphabetical order by name if this field is empty.</p>
        ]]></item>
        <item id="admin_publish" title="Publish"><![CDATA[
<h2>Publish</h2>
<p>Setting this to Yes allows new articles to be created on the Matrix panel.</p>
<p>An empty row will be enabled allowing a new entry to be constructued and added to the articles when the matrix is saved.</p>
        ]]></item>
    </group>
</help>
</resources>

To render these custom topics you don’t even need to utilise the admin_help callback (although you can if you wish to make more sweeping changes). Just prefix the help string name with the plugin name and a colon. So, for the above in the relevant inputLabel() functions, set the 4th parameters to:

adi_matrix:admin_ordinal
adi_matrix:admin_publish
…

If the pophelp file doesn’t exist or the topic doesn’t exist inside it, the popup will render the ‘missing’ string as normal. If the language you’re using doesn’t exist, it should fall back on the default language, just like it does now in core. Please test.

This works fine for your own plugin panels or even (via the callback) anywhere you want to divert/override or augment the core pophelps to your own plugin. You could, for example, intercept pophelp topics on any panel like this:

register_callback('abc_my_pophelp_handler', 'admin_help');

function abc_my_pophelp_handler($evt, $stp, $ui, $atts)
{
    if ($stp === 'status' || $stp === 'override_form') {
        return sp.href(span(gTxt('help'), array('class' => 'ui-icon ui-icon-help')), '?event=help&step=pophelp&item='.urlencode('abc_plugin:'.$atts['help_var']), $atts);
    }
}

Then, any clicks on the status or override_form pophelp topics on the Write panel will be diverted to the abc_plugin/lang directory pophelp files for you to deliver. Handy if your plugin adds functionality to a core element (e.g. a new Status value).

If you wanted to add a pophelp for section (which is missing in core) then you just need an additional callback to intercept the inputLabel() first and add a pophelp entry (otherwise your plugin has nothing to hang off). After that, proceed as above to render the help topic by adding an entry to the admin_help callback for section and write your topic text in your own XML file.

There’s one current downside: this doesn’t (yet) work for plugins using the Preferences panel.

The reason is that core cheats here. Instead of looking up the topic each time, it fetches a pre-rendered list of all topic titles from the core’s pophelp file and then compares the topic title as it draws it on-screen with the list. If it’s in there, it adds a pophelp icon. If not, it skips it.

That’s fine for core strings, but for plugins it poses a problem because its own pophelp topics aren’t in core files. And it’s (probably) an unreasonable burden to scan all plugin directories for all pophelp topics to build a list of custom strings to add to the list of ‘allowed’ topics.

I’m giving this some thought, but if anone has any neat ideas on how we can detect if plugin prefs have their own pophelp and render an icon automatically, please shout.

P.S. As always (well, since about 4.7.0) you can construct a URL to a resource on a different system (e.g. your website or a GitHub page) and fetch topics directly from there. People then fetch help topics across the web instead of from the file system.

Last edited by Bloke (2025-04-13 22:01:50)

Bloke · 2025-04-13 22:38:26

btw, I did consider allowing pophelp to be loaded from the data area in the plugin’s data table but it would require more sweeping changes than I’d really like to consider at this stage of development. Plus it’s not really set up for multilingual content so it’s a hack at best.

The system for loading XML pophelp files uses a well-established convention, so it made sense to simply extend it for plugins’ use.

Bloke · 2025-04-14 01:23:03

Bloke wrote #339521:

There’s one current downside: this doesn’t (yet) work for plugins using the Preferences panel.

And that’s not true any more. :)

It turns out it’s not that intrusive to scan the entire plugins directory tree for /lang/ XML files, cache the names of any plugins that expose pophelp, and then just extract the keys for the prefs group for all of them.

Note that, on the preferences panel only:

Your pophelp topic ID must match the preference name exactly for it to render the poplink.
You can supply a {plugin_name}_overview topic name in the prefs group to render a poplink adjacent to the plugin group title. Useful for supplying an overview of what the settings on the panel do overall.

This hasn’t been battle tested with fallback languages yet – or in fact anything other than en – so please test and report back.

Hope it helps.

jakob · 2025-04-14 08:12:39

Phenomenal! Blown away by the thought you’ve put into it. I’ll need to read that more carefully in detail, but it looks like you’ve made it really simple for straightforward input pophelps. Two questions:

Can you test for support to provide an alternative if not available in past versions?
I’m assuming for the moment you have to then package plugins as a .zip file for the file to be included? Or can the plugin compiler also incorporate the pophelp as a section?

Bloke · 2025-04-14 09:58:06

No worries. Glad it works.

There’s no direct way to check for inclusion. If you supply the files in your lang directory, they’ll be ignored by anything less than 4.9.0 so it won’t break anything. But if you want to offer a fallback like your lang string hack above, your only real safe bet is a version check, unfortunately.

And yes, you’ll need to zip it up for inclusion. I haven’t tested it but the Export button on the admin panel might work and bundle everything in the directory up. Can’t remember.

Textpattern CMS

Textpattern CMS support forum

#1 2025-04-04 06:00:04