Textpattern 4.5: Admin-side plugins with plugin types 4 and 5

wet · 2012-08-07 05:31:56

Textpattern 4.5 adds two new plugin types ‘4’ and ‘5’ to express additional conditions on how plugins are loaded. This has a chance to affect any plugin which runs in the context of the Content > Write tab.

A little background: With Textpattern 4.5 we introduce AJAX into the admin-side Content > Write and Admin > Plugins panels. While “regular” synchronous requests usually result in a whole page refresh in HTML format, AJAX requests only change tiny elements of an admin panel, often through direct DOM manipulation via JavaScript.

To stop legacy admin-side plugins for Textpattern 4.4.1 and below from interfering with AJAX requests, the core does not load plugins with types 1 and 3 when it detects an AJAX request.

Plugins must use one of the two new additional plugin types to indicate their ability for handling AJAX requests.

Here’s the whole quagmire in an easily digestible matrix:

plugin type	public	admin (synchronous)	library	admin (ajax)
0	yes
1	yes	yes
2			yes
3		yes
4		yes		yes
5	yes	yes		yes

The global $app_mode is set to ‘async’ when an AJAX request is processed. Dual-mode admin plugins of type 4 or ubiquitous plugins of type 5 can use this variable to discern between synchronous and asynchronous requests (sample code).

gomedia · 2012-08-07 23:11:32

Hi Robert,

Thanks for the info, but can I check something with you? Let’s take a certain plugin as an example.

At the moment it’s type 1 – there’re tags for use on the public side as well as its own tab on the admin side. It also has an ability to tweak the Write tab, specifically, to modify the section popup list markup.

It doesn’t do any Ajax cleverness. Am I right in thinking it should stay as type 1.

Adi

wet · 2012-08-10 14:41:04

Adi,

your plugin modifies a panel which is rendered by both synchronous and AJAX responses, i.e. the “Write” tab. So it is a potential candidate for one of the new plugin types.

As far as I can see, adi_menu renders its own section drop-down and replaces the core’s own select element. It does so by looking for a pattern-match in the original markup and replacing this with your own HTML creation.

In Textpattern 4.5, the write tab is broken into individual elements we call “partials”. Each partial contains the user elements for one particular aspect of an article (title, body, categories, et cetera), and of course there’s also one partial for the ‘section’ drop-down user interface.

On partials

Partials can be either static or volatile.

Static partials do not change after the write tab has been rendered initially. Example: The section drop down. There’s no chance that the contents of this drop down changes as long as the user stays on the write tab and saves happily every other minute.

Static partials are not refreshed when an AJAX request is processed.

If a plugin modifies only static partials it can continue to use the ‘old’ plugin types. Use ‘3’ if you do not add to the public functionality, use ‘1’ otherwise (e.g. tags).

Volatile partials potentially change with every subsequent save operation: Example: The recent article list in the left column shows the current article on top after it has been saved at least once while this article might not even have been on the list at the initial page load.

Volatile partials are refreshed when an AJAX request is processed.

If a plugin modifies a volatile partial it has to use one of the new plugin types so it gets loaded on the admin-side for AJAX request. Use ‘4’ if you do not add to the public functionality, use ‘5’ otherwise (e.g. tags).

There’s one central table in txp_article.php which defines all partials. As you can see, we have an entry for the ‘section’ user interface:

'section => array('mode' => PARTIAL_STATIC,  'selector' => 'p.section', 'cb' => 'article_partial_section'),

This entry defines that we render the section user interface only once as it is static. We do so by invoking a callback named ‘article_partial_section’ which is a core function further down.

Conclusion

As far as I can see, adi_menu is of plugin type 1. It adds public functionality (tags) and admin-side functionality in synchronous mode.

Suggestion

You chose a rather indirect method to inject your own markup instead of the core’s section drop-down. I think you could adapt adi_menu_article_section_popup() to respond to the associated pluggable UI event ($event = ‘article_ui’; $step = ‘section’) to get rid of adi_menu_article_inject.

gomedia · 2012-08-10 23:29:30

Robert,

Thanks for the very detailed & clear explanation. Much appreciated.

adi_menu was written a long time ago, in the days before pluggable_ui, hence the archaic inject method. Spotted it during my 4.5-ifying exercise and it will be sorted out!

Textpattern CMS

Textpattern CMS support forum

#1 2012-08-07 05:31:56