Textpattern CMS

#1 2015-09-03 08:41:20

Destry

Member

From: Haut-Rhin

Registered: 2004-08-04

Posts: 4,909

Website

[docs] Core callbacks reference

• ToC
  • Plugin development
    • Core callbacks reference

(The old core callback list for comparison.)

This has the potential to be more useful/helpful than it already is (thus the title change), but community help is needed because I’m not a dev and can’t really do it. It’s up to you.

What I’ve done so far is convert the long vertical lists to more space-saving tables, which also makes it easier to see the relevant details. The tables also allowed removing a lot of repetitive words in each callback instance (via table headers). Once Phil has rolled in better table styling (e.g., zebra rows and cell padding) that will really start to shine through (and throughout all docs where tables are used).

But there’s a couple of things I’m going to leave open for others (namely you dev people) to help with while I move on other pages:

1) Introductory copy. After each new section and most sub-sections of the page, there are [todo] placeholders (I may have missed a few) where introductory copy is needed to briefly point out what the reader is learning at that point — what the nature of the information is. One to three sentences should be enough in each case. Not only does this make the information more usable, but it’s considered bad form in technical information (look at any TC style guide) to go from one heading to another with no explanatory paragraph between them, or to go from a heading directly to a table or list with no leading statement about what the block elements will communicate.

As an example, see the main Admin-side callbacks section (the h2 header). I’ve added the intro copy under this one, two short paragraphs. (If there are other suggestions about what should be said there, point them out.) The second para is copy I relocated from another page in old docs, which fits in better context here. Maybe it’s not exactly right for all admin-side callbacks, but we can fix it or move it to the right sub-section(s). Whatever. In any case, it gives you the idea of what I mean by intro copy. Not all intro copy needs to be as long, or detailed, or even of the same pattern (as you’ll see in the next examples), but anything useful that can be said in each case should be. We do this for the sub-sections too.

2) Callback examples. As this is a reference, and not just a long bulleted list, we could make it more useful by adding code examples under the tables to demonstrate a representative callback function for that table set — maybe two examples when tables are larger (having more event/step possibilities). Two, max, is enough in each case, we don’t need to make it like the Tag reference and create examples for every callback.

As example for this one, see the sub-section, Admin-side user-interface callbacks (an h3 heading). Again I’ve added the missing intro copy for this sub-section, but look down further to the first h4 heading — Write panel. Again, there’s enough intro copy there to suffice (and note the pattern is different), but look at the Examples area under the table. In this case I’ve pulled two of the three examples from the Callbacks section in the main plugin dev page, which happen to fit in context with this table’s callbacks, so we’ll use these example again (they’re good ones). In this location, I’ve made the example less explanatory, because presumably devs looking at this level of reference know what’s going on and don’t need the extra detail. So the idea, then is to do this for every callbacks table in the reference — one or two examples of possible callback functions, or whatever you think would be helpful and relevant to the table.

3) Page organization. (A bonus.) Somewhat coming back to the first point, and something I’m still tinkering with. When first working on this page, it seemed a little odd to me to organize the page by the file locations where callbacks are made to (if I understand that right). In other words, headings like this: include/txp_category.php. I’m not sure I have the full answer yet for all main sections, but look again at the Admin-side user-interface callbacks section. You see I’ve changed the first sub-heading there from include/txp_article.php to Write panel, and moved the file path into the intro copy lines where it’s still easily referenced.

In other words, instead of this organization:

• Callbacks
  • Admin-side callbacks
    • Admin-side user-interface callbacks
      • include/txp_article.php
      • include/txp_category.php
      • include/txp_image.php
      • etc

It will be this:

• Callbacks
  • Admin-side callbacks
    • Admin-side user-interface callbacks
      • Write panel
      • Categories panel
      • Images panel
      • etc

It’s easier to see where the callbacks apply this way, which is probably how most people would think to research them, as opposed to where in Txp the callbacks are made to. And as long as the file locations are part of the introductory copy in each case, it’s a win-win. Again, I’m not really developer-minded yet, so before I edit further, someone should pipe in about this organization and let me know if it’s working or not.

Ideas welcome.

Last edited by Destry (2015-09-30 14:44:57)