Heffalump traps for unwary plugin authors in TXP 4.6

gomedia · 2016-05-20 05:32:34

I don’t want to appear the harbinger of doom but I thought it’d be useful to document the location of a few cowpats on the path to TXP 4.6 plugin compatibility.

It’s not a definitive list, so if anyone’s slipped in some particularly smelly deposits in their own programming paddocks or can see some potential guano mountains on the horizon please let me know.

The only way is Hive: In 4.6, the standard (and only) supplied admin theme is Hive. There are major class & styling differences between Remora and the new Hive which will need to be taken into account. Admin plugins which favour Remora … beware!
HTML5 is alive: TXP 4.6 admin markup is HTML5. So, for example, div.txp-nav is now nav.txp-nav. This may affect your admin plugin styling.
Responsive responsibilities: TXP 4.6 admin is responsive, so be narrow-mindful. The @media breakpoints are 60em & 47em.
Dropdown drop outs: Long dropdown submenus are truncated at the bottom of the window. This has always been the case in Hive, but us long-dropdown Remora fanciers will now notice it. The workaround is to use a Hive-tweak theme. And on the subject of submenus, in TXP 4.6 they no longer appear on hover (a click is required). Again, a theme-tweak will change this. If you’re new to themes, Wet has created an example but note that the install directory is now /textpattern/admin-themes.
The white screen of death: There’s an arcane method of injecting markup into admin tabs which uses ob_start() and preg_replace_callback(). It may just be a peculiarity of my local development set-up but three of my adi_admin_plugins have caused the aforementioned crime scene. The fix is to use the pluggable_ui system instead, and if there’s no socket in the right place, chuck your markup somewhere convenient and shift it into place using jQuery.
get_prefs() is now prejudiced: Prior to TXP 4.6, get_prefs() would retrieve all preference values by default. Now it only retrieves system prefs. If you want user prefs then a second call is required – get_prefs($txp_user) – and you have to merge the two. So, if you’ve been using $prefs = get_prefs() as an easy sledgehammer approach to refreshing the prefs cache you’ll end up destroying your user prefs, and possibly get strange results on your pref input screens. The fix is to individually get_pref() from the database – either straight after you’ve set_pref(), or when displaying preference input field values.
Lost without trace_add: trace_add() is deprecated in 4.6, so you’ll need to use the new trace functionality. trace_add() still works but you’ll see error messages on your website.
Alien registration: For reasons of future security, public tags should now be registered. Read about it here but use this syntax. If you don’t register your plugin tags, you’ll get warnings on your website.
jQuery where?: In TXP 4.5 the jQuery path was textpattern/jquery.js, in 4.6 it’s textpattern/vendors/jquery/jquery/jquery.js and now jQuery UI is provided as well (textpattern/vendors/jquery/jquery-ui/jquery-ui.js)
No more multiple (callback) births: In TXP 4.5, repeated callbacks e.g. several calls to something like: register_callback('my_callback_func','some_ui','extend_detail_form') would result in my_callback_func being executed each time. In 4.6, the called-back function is only executed once. The fix is to place all the action in my_callback_func, and call-it-back only once.

Last edited by gomedia (2016-06-20 01:03:30)

Bloke · 2016-05-20 09:36:34

Thanks for the list, Adi. Very helpful.

gomedia wrote #299166:

There’s an arcane method of injecting markup into admin tabs which uses ob_start() and preg_replace_callback()

This is something MLP does in droves. As a technique I can confirm it still works (uhhh, usually), but it’s ugly, error-prone and, as you say, with pluggable_ui() and low-level callbacks in place — especially in functions like inputLabel() — the practice can largely be eliminated.

get_prefs() is now prejudiced

Yes. As a convenience, get_prefs() is called globally by core so you should be able to use global $prefs in plugins and forego the double-dip dance. But note that this might not always be the case in future so moving over to pulling individual prefs as and when you need them is the preferred approach.

I’d like to add an API call one day to return a subset of prefs based on a pattern (e.g. prefix) so you could grab all your plugin pref values in one call.

gomedia · 2016-05-20 12:14:13

Bloke wrote #299170:

… get_prefs() is called globally by core so you should be able to use global $prefs in plugins …

Yes, but the problem comes sometimes when plugins don’t pick up the recently updated pref value – as you mentioned here. The $prefs = get_prefs() trick came from dissecting rss_admin_db_mgr all those years ago, when I was in my plugin authoring infancy.

gomedia · 2016-06-06 12:46:28

Added a note about the new path to jQuery enlightenment.

gomedia · 2016-06-20 01:04:24

Added a note about multiple register_callback.

Textpattern CMS

Textpattern CMS support forum

#1 2016-05-20 05:32:34