[docs] Plugin development main page content

Destry · 2015-08-30 21:30:57

1) Is pluggable_ui() specifically a “function” or a “callback”? I see it called a “callback” in docs, but wouldn’t it be more correct to call it a function? Albeit one that has a special purpose for the admin-side?

In the Core callbacks reference there are things like this which are also called callbacks, and they don’t look remotely the same:

include/txp_section.php
include/txp_article.php
etc

In fact those look like file paths to me.

Having waded through the docs a bit, I’ll take a wild guess and say that callbacks are a “transaction” of sorts that happens when a given function is “triggered”. A given function is composed of arguments that vary depending on public-side or admin-side aims.

That guess ventured:

2) What is a callback?
3) Why are they called “callbacks”?
4) How to those file paths relate to callbacks?

I’m asking these questions because the docs aren’t as clear about that as they could be, and I want to edit them to be clear, and to use consistent/accurate nomenclature.

I’ll have some other questions with regard to this stuff, probably, but let’s start with that.

Anyone?

etc · 2015-08-31 11:42:24

I’d say, callbacks in Textpattern are orders (functions) that you (plugin) can place to be executed when some event/step happens during the code processing. Plugins generally register these orders with

register_callback('my_function', 'some_event', 'some_step');

So, my_function is a function that plays the role of callback that will be executed when some_event and some_step happen. These “happenings” are mainly materialized by callback_event() and pluggable_ui() function calls in include/txp_section.php and other places (files) of code. Formally, they are not callbacks themselves, but functions executing callbacks. Now, an action of callback execution is often called callback too, so go see…

Destry · 2015-08-31 12:33:41

etc,

That’s very helpful. Thanks. I’ve just made another pass through the main plugin development page before seeing this, but I’ll make another with this in mind and fix it where I can.

~~So what would you call register_callback(), if not a function? Or is it still a function and callbacks are just functions within functions?~~

Let me try again…

I’m assuming register_callback() is a function and callbacks are formed by functions within functions in this case.

In this example, register_callback('my_function' ...), would my_function also be an argument (argument 1), taxonomically speaking?

I haven’t seen the callback_event() in docs yet, but I’ve been calling both register_callback() and pluggable_ui “functions” (as you’ll see in the in-page ToC). Let me know if that’s not exactly correct.

Last edited by Destry (2015-08-31 13:04:19)

Destry · 2015-08-31 12:44:41

A word about the new plugin development docs so it’s clear what I’m trying to do there. The old wiki plugin dev page was basically a bunch of links, roughly organized. We can do better in the new version — with a little reorganization, consolidation, and editing — by making the main page the principle learning page (instead of a link farm).

The in-page ToC there aims to follow this flow of organisation:

Stuff to know if you’re thinking of building plugins (expectations, plugin types, etc)
How to build plugins (nomenclature, anatomy¹, examples…)
Reference and tools

Some stuff will still be links (external resources, tools, in-house references²), but it will have more context in this case from the main page. I’ve already been able to eliminate a few needless pages by putting the content directly in the main page. There still might be some shuffling of content around for a while, so I would advise against linking to individual sections just yet. Wait until the dust settles.

What I need is for someone to serve as a technical editor, following my IA and copy edits and making sure the technical parts are sound (using the right PHP vocabulary, ensuring descriptions are accurate, etc). A lot of you should be able to do that. Just read through what’s there and make a suggestion about code/nomenclature accuracy. Generally once I understand, I can then make the universal edits needed. So you don’t have to actually list every instance of a problem. You might just point something out if I happen to miss it later.

¹ There used to be a “plugin anatomy” doc at zem’s site, but his site has long since been taken offline. I’m sure that would have been a helpful doc for me and anyone else to use. If anyone would like to write a plugin anatomy doc, we’ll put it into the lineup. If it’s not too long (a few paragraphs with code examples), we’ll put it directly in flow of the main page, probably somewhere between the ‘stuff to know’ and ‘how to build’ info.

² Examples of “in-house references” are Core callback reference, Admin-side events and steps, etc.

Last edited by Destry (2015-08-31 12:51:12)

etc · 2015-08-31 13:23:02

Destry wrote #294444:

I’m assuming register_callback() is a function and callbacks are formed by functions within functions in this case.

In this example, register_callback('my_function' ...), would my_function also be an argument (argument 1) in this case, taxonomically speaking?

Exactly, though there is no strict definition. Simply put, callbacks are functions passed as arguments to other functions, in view to be executed, but it’s just a role. Take an example:

function add($x, $y) { return $x+$y; }

function apply_add($x, $y) { return add($x, $y); }

function apply($callback, $x, $y) { return $callback($x, $y); }

We can call add(3, 5) just like any normal function. If we call apply_add(3, 5), it will execute add(3, 5), but in both cases add is not a callback. But in apply('add', 3, 5) it acts as a callback, i.e. passed to apply() from outside and then called back.

I haven’t seen the callback_event() in docs yet, but I’ve been calling both register_callback() and pluggable_ui functions. Let me know if that’s not exactly correct.

They are all functions, but play different roles. register_callback() takes orders, callback_event() and pluggable_ui() trigger their execution. Actually, pluggable_ui sub-treats the work to callback_event.

Edit: I wouldn’t insist on pluggable_ui() (nor callback_event()) in the docs too much, they are not called within plugins, unless the author wishes to add new events to textpattern.

Last edited by etc (2015-08-31 16:39:44)

Destry · 2015-08-31 15:59:20

Excellent details! Thank you. I’ll roll that back in on another editing pass. I think that pretty much covers the gaps/gotchas I had about how to talk about stuff.

etc · 2015-08-31 16:36:29

You are welcome! I’m bad at writing, but let us know when you need an extra couple of eyes again.

Edit: The last sentence Note there’s no third argument (the empty single-quotes, '') for this function because there’s no default content to alter of Adding new elements, as well as abc_add_text() function definition are erroneous, it should be

function abc_add_text($event, $step, $data, $rs) ...

Last edited by etc (2015-08-31 17:33:14)

Destry · 2015-09-01 08:02:05

Thanks again. I didn’t write any of the code. I just worked around what was already there. But now that you point that out, it cleared up some other issues too. Mainly the function definitions earlier on. It should be better now, but keep me honest.

Destry · 2015-09-01 09:28:30

A couple new questions…

I’ve poked around the forum a bit, for example, and it seems you can use either pluggable_ui() or register_callback() for making admin-side UI changes.

1) What distinguishes pluggable_ui() from register_callback() for making admin-side UI changes?

I think there should be at least one example for pluggable_ui() in the plugin dev docs (there isn’t one currently), but there should also be a brief explanation about how it’s different (besides the function signature); i.e., why you would use it over register_callback() in a given case.

2) How do you add a new plugin panel under Extensions? Is that done with pluggable_ui()?

If so, that would be a good example for the docs, but I’d still need some clarification on why someone would use one over the other for admin-side UI changes.

Anyone?

etc · 2015-09-01 10:57:48

The docs are getting better, thank you for the effort.

Destry wrote #294458:

1) What distinguishes pluggable_ui() from register_callback() for making admin-side UI changes?

I think there should be at least one example for pluggable_ui() in the plugin dev docs (there isn’t one currently), but there should also be a brief explanation about how it’s different (besides the function signature); i.e., why you would use it over register_callback() in a given case.

These are two completely different functions:

with register_callback() you say to Textpattern “do this when something happens”, for example “replace the default section selector with mine while you are at it”. Plugins use this function quite often, to alter Textpattern behavior/interface.
with pluggable_ui() Textpattern says “something is happening, I’m executing your orders”, for example “I’m outputting the section selector, ok, let it be yours”. Unless you are writing a plugin that wants to let other plugins alter its output, you will never use pluggable_ui().

So, the short answer: forget about pluggable_ui() (but see below), it’s Textpatterns kitchen.

2) How do you add a new plugin panel under Extensions? Is that done with pluggable_ui()?

If so, that would be a good example for the docs, but I’d still need some clarification on why someone would use one over the other for admin-side UI changes.

No, but you could need pluggable_ui() on your own panel, though I don’t know if any plugin uses it (Stef?) New panels is another story, I postpone it atm.

Destry · 2015-09-01 12:18:17

Your function descriptions/distinctions are a little too abstract for my non-dev brain, unfortunately, but I certainly take your point to keep away from pluggable_ui() in the plugin development docs.

etc wrote #294461:

Unless you are writing a plugin that wants to let other plugins alter its output, you will never use pluggable_ui().

So, the short answer: forget about pluggable_ui() … it’s Textpatterns kitchen.

I wonder why pluggable_ui() was ever mentioned in plugin dev docs to begin with…? (rhetorical)

This is what I’ll do… I’ll excise all mention of pluggable_ui() in the plugin dev docs except as a footnote in the register_callback section with something along the lines of what you explained. The footnote will provide the only link to a separate small page on pluggable_ui() where it’s history and possible value is poked. I’ll make it clear it’s not necessary for plugin-dev, but it does exist in core and could do something for those with nothing better to do, or whatever.

I guess I don’t understand why it came about if it doesn’t have any value (for plugins).

For the sake of argument — but not because I’m arguing ;) — Redbot quotes Stef back in 2009 (I guess when pluggable_ui() was first introduced) as saying:

…a good use of pluggable_ui() could be to initially ‘rewrite’ the custom field area so that the custom fields appeared in a specific order…

And Redbot replies:

Yes, that would be another good use of pluggable_ui(), I already do this with an homemade plugin using jquery but, again, taking advantage of pluggable_ui(), the end result would be a lot faster and cleaner.

So if Redbot thinks that’s a good use of the function in a plugin, and you’re saying forget it, then how would you do that — rewrite the custom fields order — using register_callback(), or would it be more complicated than that?

Edit: That was a silly question, I guess, now that we know Stef is working on new core functionality to do that very thing. So, no further question, actually. ;)

Last edited by Destry (2015-09-01 12:22:20)

etc · 2015-09-01 12:34:17

This is a basic abc_hello admin-side plugin that creates a new “ABC Hello” tab accessible to admins (i.e. privs 1,2 users) under “Extensions”:

add_privs('abc_hello', '1,2');
register_tab('extensions', 'abc_hello', 'ABC Hello'); //parent, event, title
register_callback('abc_hello_world', 'abc_hello'); //callback, event

function abc_hello_world($event, $step) {
	pagetop('ABC Hello', '<strong>ABC Hello</strong> preferences');
	echo '<p>Hello, World!</p>';

If we want to allow other plugins to alter the output, we can replace echo '<p>Hello, World!</p>'; with

echo pluggable_ui('abc_hello', '', '<p>Hello, World!</p>');

Other plugins can then step in with

register_callback('xyz_hello_world', 'abc_hello', '');

Textpattern CMS

Textpattern CMS support forum

#1 2015-08-30 21:30:57