[doc] Extensions

Destry · 2015-10-06 13:43:17

ToC
- Administration
  - Extensions

Although the Extensions region and associated plugin panels are not out-of-the-box functionality (the scope of user docs, more ore less), it’s generally an obvious enough feature for most site administrators to clarify a few things about it in docs. For that reason it gets a page.

It’s first introduced in the Administration page in terms of admin-side organization (and as a way to browse to the doc), as well in roles and privileges for the rights of access.

I’m more or less done with this doc, but I’m throwing it up here for a couple of reasons:

First, I’d like some help filling in the missing panel labels in the table, from those of you who can. I don’t have all those plugins in the table installed and I’m not going to install them for this reason. If anyone does have the plugins installed and can just look and shout back here with the panel labels, that would be appreciated. Likewise, if there are plugins missing in the table that provide an Extensions panel, point those out too (along with the panel label), but only if they are supported plugins. Plugins that are orphaned or otherwise abandoned won’t be added (I’m sure there will be better places later, outside of user docs, to list that ‘category’ of plugins).

Second, it’s clear from putting this page together and looking at what plugins I do have installed across three local installs that there two wayward processes happening in plugin developer ranks. I’m sure some of you are aware of them:

1) Plugin panel labels. As you can see from the few panel labels in the table already there is no clear pattern for labeling. Plugin devs may have their own logic for what they do, but multiple competing logics makes things confusing to the end user. It also doesn’t give a good impression to the potential professional user (companies and their employees, for example).

2) Plugin panel positioning. As the page points out at the end, there’s also a lack of convention about where plugin panel links appear in the administration side. Some use the Extensions panel and some don’t. My guess is, sometime subjective determinations about functional context are made for placement over the expected convention. Or to a lesser degree, that maybe people are worried too many panels will appear under the Extensions region? It would never happen in my case, and I can’t imagine for most others either unless, like a tattoo addiction, they keep wanting more and more, which really isn’t good practice is it (could be costly)?

It strikes me that for both situations, there’s simply a lack of accord between core devs and community plugin devs (and perhaps a lack within those camps too) about handling the positioning and presentation of plugin panel elements.

The first issue, labeling, is an easy matter to resolve, or at least should be. A consensus needs made among plugin devs to do it one way and then everyone does. This would then go into the editorial style guide for UI elements and whatever plugin guidelines are written, et voila ! The question, then, is what should be the convention? Based on what we see so far, there are three things going on:

code_case (e.g., arc_meta)
capital-case (e.g., Plugin Composer)
sentence-case (e.g., Bio config)

We can easily rule out “capital-case” because the style guide (which is in a state of revision at the moment) already defines using sentence-case for all titles, headers, labels, etc in the UI and official copy. Just as they are in this forum and the new user docs, for example. So that means any plugin using capital-case should at least be changed to sentence-case. (My recommended direction, but I’m not a dev.)

It would also be good (for the sake of Textpattern’s outward appearance) that developers not use abbreviations in their UI labeling (common acronyms, like “URL”, are okay). For example, “Bio config” would represent itself better as “Bio configuration”. There’s plenty of room for it and it speaks to a wider audience better. (I’m not even sure “config” is a valid abbreviation. One to check in the OED, I guess.)

But that could be a moot direction if the engineering-minded choose for code_case labeling. Here we have another crossroads: Is this done because it ensures a unique label when many plugins might have similar functionality? This is a weak argument, if so. We’re talking about admin-plugins, which narrows the pool down, and it says right in the plugin development docs that new devs should not reinvent the wheel. So maybe we ever have two plugins offering the same functionality at the same time. It’s very easy to come up with two different labels in that case without labels looking like accidental code. For example smd_redirect and arc_redirect… Bloke’s plugin is already “Redirects”, so Andy’s could easily be “URL redirects”, or whatever. It’s not hard. If there were a third redirects plugin we could still do it easily enough (“URL redirect magic”). But such a convention (or any convention) is up to the plugin dev community to finally alight on, which I can write into the style guides afterward. More important than which way it falls is doing it one way or the other, but not four different ways.

For the second issue, positioning (e.g., wet_snitch and smd_switch_role come to mind), the same piece of logic applies: do it one way or the other but not every which way but loose. Since you already have the Extensions regions for this purpose, it seems like the obvious direction to take for establishing the convention. It also makes it easier to find plugin functionality rather than hunting through core regions (Content, Presentation, Admin) for it. And it keeps the core panel lists under each region focused on only core panel links. And if it’s technically feasible, auto-alphabetize plugin panel labels in the Extensions panels list.

To be clear, I’m not picking on anyone by way of their plugins or labeling choices. I’m sure the long-tail UX ramifications aren’t at the front of one’s mind when coding plugins. I’m only using the examples I do for demonstration because they are there, which work well. And I apologize in advance if my wording is indelicate. I’ve been spending hours writing and editing (Txp docs and other work) and when these things get in the head, they need to come out. For me that usually means directly.

EDIT: Btw, I’d be more than happy to help plugin devs come up with their plugin panel labels, if they ever want to take me up on it.

Last edited by Destry (2015-10-07 07:18:17)

Bloke · 2015-10-06 20:29:35

Yeah, paw in the air, I’m guilty of inconsistency big time.

I’m not sure a consensus will be reached here, despite it seeming like an obvious thing to do. I do take the point about Plugin composer and Bio config (ummm, technically Biography configuration, right?!) I can fix those. In fact, anyone can fix those: they’re all just Textpack strings nowadays.

Which brings me to the first point: there’s no guarantee the panel labelling will be consistent across languages. I’ll try and use sentence case from now on in the English Textpacks, but grammar rules in other languages aside, I struggled with a plugin like smd_tags. I’m not sure if tru_tags used “Tags” or its own prefix, can’t remember now. Regardless, the plugins can coexist quite happily (in fact, smd_tags has a wizard to migrate data from tru_tags so the two need to be active at the same time, at least for a short while). I went with smd_tags as a panel moniker mainly because I thought that Tags alone might be confusing, given that we use ‘tag’ to refer to <txp:> tags. Tagging seemed a bit vague so I just lumped for the plugin name. Any advances on that for future releases welcome.

As an aside, listing plugins in the docs: is that a good idea from a maintenance perspective?

Regarding positioning, the Extensions area is there for stuff to be extended — i.e. non-core — for sure. But there are plenty of times when putting a plugin in a core area makes sense (and plenty of times when it doesn’t: again, I’m guilty of that). Let’s take a few examples off the top of my head, and yes, most are mine because I’m more familiar with them than others:

smd_macro: for creating new tags that are usually used in Content, hence I stuck it there. Probably should be under Extensions.
adi_matrix: manages content. An uber-mega-super-awesome tool for managing article and custom fields. The configuration of it is under Extensions, but the Content area is absolutely the right place for the actual user interfaces to appear, alongside the Write and Articles panels.
smd_featured: for assigning content to the front page of your site. The Content area is logical here since it’s related to content management and organises / groups articles.
smd_user_manager: completely replaces the Admin->Users panel. Without that you’d have two places to manage user accounts, which I felt was more prone to confusion.
stm_javascript: for managing JS files in the database just like CSS is in core. The Presentation panel makes sense here. Sort of.
jmd_dashboard: adds stuff to core areas to allow enhanced, custom content configuration. Just like…
… smd_tabber that allows you to write dashboards under any panel and even create your own new areas.

In addition to the above, there’s also the Home (a.k.a. Start) area, which appears to the left of Content. adi_matrix can write to this area, as can smd_tabber. It was conceived primarily for dashboard functionality or welcome splash screens. I know jakob regularly uses this area as a jump-off point to other parts of the admin-side system, and has even put together some wonderful content management flows, hiding certain core panels in lieu of a simpler workflow for certain groups of user who don’t need the full power of the Write panel, for instance.

So, yeah, probably a good idea to recommend the Extensions area as the go-to place for most admin-side functionality, but to enforce or strongly suggest its use over the other panels is probably not going to work so well. Ultimately, a plugin should have a very good reason to exist elsewhere (and yes I should probably move a few of mine to Extensions) so if the docs can communicate that sort of ethos, that’d be grand and probably the best we can hope for.

tl;dr Let’s make two recommendations:

Sentence case for panel names wherever possible;
Extensions area for admin-side plugin / configuration screens unless there’s a very good reason to house them elsewhere.

That alright?

Destry · 2015-10-07 10:36:45

Bloke wrote #295436:

I’m not sure a consensus will be reached here

I kind of figured. But I’ve never seen this subject talked about before, not center table like now. I’m Frodo putting The Ring on the stump. Will the fellowship form? Not for Frodo to say.

(ummm, technically Biography configuration, right?!)

Good point. And another opportunity to whittle it further for the sake of guidelines, should it ever get that far. And your plugin would make a good reference in the guidelines, if you didn’t mind. For example:

Provide “human-friendly” Extension panel labels in sentence-case (not capital-case or code_case). For example, use “Plugin composer”, not “Plugin Composer”, “ied_plugin_composer”, or “plugin_composer”.
Common acronyms are okay (e.g., “URL”), but avoid them if possible, and only use one in a given label when used.
Common abbreviations are okay (e.g., “bio”) when the context is clear. But only use one abbreviation in a given label. Pick the most commonly understood across a broader audience base (i.e, pick the less geeky). For example, “Bio config”, two abbreviations, would ideally be “Bio configuration” as “Bio” is commonly used across industries, many having nothing to do with technology.

there’s no guarantee the panel labelling will be consistent across languages.

Another good point. I overlooked internationalization. But anyone who works in translation will tell you that “plain language” translates much easier than mixed or complex terms, and I would assume that goes for code_case too.

(in fact, smd_tags has a wizard to migrate data from tru_tags so the two need to be active at the same time, at least for a short while)

Good to know that two similar plugins can (or should be able to) reside together in an install, which emphasizes the importance of distinctive labels. Though code_case may not be the solution for reasons we’re starting to pinpoint now: 1) not “user-friendly, 2) not “plain language”, 3) doesn’t translate well (i18n), and especially with the plugin dev prefix tacked onto it…

I went with smd_tags as a panel moniker mainly because I thought that Tags alone might be confusing, given that we use ‘tag’ to refer to <txp:> tags. Tagging seemed a bit vague so I just lumped for the plugin name. Any advances on that for future releases welcome.

Understood. At least you thought about it. I think this provides more opportunity for guidelines to help other plugin devs making similar choices. We can, and likely should, be a little more flexible in this case (Extensions panel labels) about “grammar” consistency since the nature of plugins are wide-ranging in terms of what they provide or do. So, adding this guide to our list above…

4. You may structure your labels as nouns or verb forms (e.g., transitive, phrasal, etc.)

Which would mean any of these, as examples, are fair game:

Tagging
Content tags
Content tagging
Tags manager

listing plugins in the docs: is that a good idea from a maintenance perspective?

Maybe. Maybe not. I just carried it over from the old doc and didn’t edit it out yet. But it did offer a good opportunity to address what is an obvious problem, and since the labels do become UI elements when the plugins are installed, it’s not entirely out of scope if we’re going to talk about the Extensions region at all. In fact, it might be more important to have it because of the inconsistent labeling.

Maintenance is probably a small issue in this case. No more difficult than general copy maintenance of any other doc, and especially if the community helps by submitting issues when they see an update opportunity somewhere, which is expected of them. Then anyone on the GitHub docs team can make the change (not just me). Should we add a couple more people? Any native-English writers/editors in our ranks?

And it has the side benefit of being at least one curated list of plugins somewhere, if but a certain type. Maybe I should add descriptions to the table, in fact? I was at least trying to keep it simple. ;)

there are plenty of times when putting a plugin in a core area makes sense…

Yeah, I touched on the fact that “context” might be a reason plugin devs put panels in core regions; i.e., if it’s content-related, it would go in the Content list of panels, and so forth. And there’s nothing wrong with that in principle. Context is a good thing, generally speaking. The problem is that there’s no consistency in how it’s done.

On one hand the Extensions region exists for the very reason of extending the admin-side — a perfectly logical and sensible convention, if followed. On the other hand, there’s no “mandate” (read “Textpattern UI guidelines”) to encourage following that convention, so people easily don’t.

This situation is like the labeling problem… More important than which way it’s done (arguably) is doing it one way instead of multiple ways. When it comes to usability, consistency trumps variability every time. That’s how human brains are wired, to adjust to patterns first. It doesn’t matter, as much, what that pattern is, so long as it’s consistent. After that, of course, is the fact some patterns are simpler to deal with than others (e.g., context positioning vs. single-source positioning), but being consistent is the first step.

So instead of doing it however a dev wants to, all devs should either use the Extensions region or not. And if not, then maybe you need to get rid of the Extensions region. Outward appearances (and communication/docs) is that admin-side plugin controls/functionality will be found in the Extensions region when such a plugin is loaded. But that’s not always the case, thus not as clear as it could be. In fact, there’s a gap in there — in user experience — where users must hunt in the dark for a bit to get oriented under certain plugin contexts. Their only help is what a given plugin developer chooses to write (itself a hit or miss situation). The only thing we can say in official docs, as I somewhat attempted in the “Extensions” doc, is that not all plugins follow the convention. Sorry!

Your list of plugins provides helpful discussion. I’ll skip the ones that are example of the basic “context” logic and reply to the other interesting situations…

adi_matrix: manages content … The configuration of it is under Extensions, but the Content area is absolutely the right place for the actual user interfaces to appear, alongside the Write and Articles panels.

I have never used this plugin, yet, but it sounds like what should define the rule, and gives a real reason for having the Extensions region, while clarifying why you would add plugin panels to other core regions (the “context”).

In other words, this might be the positioning part of the admin-side plugin guidelines:

If your plugin only provides one panel, it goes in Extensions. (That’s what the region is for and helps users because they always know where to look without question.)
If your plugin provides multiple panels, put the configuration panel in Extensions and your panels relevant to core functionality in context to those core regions (make those associated core locations clear in the configuration panel).
Avoid breaking guidelines 1 and 2.

smd_user_manager: completely replaces the Admin->Users panel.

I would consider this an obvious exception for the reason it’s not adding to a core region, but replacing a core panel. It hasn’t changed the pattern or mental model of there being a “Users” panel in that location. Situations like this would be okay. So we could add this to the positioning guidelines, perhaps:

4. The exception to guidelines 1 and 2 is if your plugin replaces a core panel. (Any additional configuration panel would still go in the Extensions region.)

jmd_dashboard: adds stuff to core areas to allow enhanced, custom content configuration. Just like… smd_tabber that allows you to write dashboards under any panel and even create your own new areas.

Okay, so maybe there’s going to be a few outlier situations that need to happen because core simply doesn’t make it easier otherwise. But these should be the exceptions to the rule, when there’s no other way possible. It should not be that plugin devs just do it however they want. But again, I’m just Frodo.

there’s also the Home (a.k.a. Start) area, which appears to the left of Content. adi_matrix can write to this area, as can smd_tabber. It was conceived primarily for dashboard functionality or welcome splash screens. I know jakob regularly uses this area as a jump-off point to other parts of the admin-side system, and has even put together some wonderful content management flows, hiding certain core panels in lieu of a simpler workflow for certain groups of user who don’t need the full power of the Write panel, for instance.

I wasn’t aware of this, but it sounds like another non-core docs exception is needed for this region, like the Extensions doc? And maybe these should be organized under /development docs instead of /administration (just a link thing, not a content change).

So, yeah, probably a good idea to recommend the Extensions area as the go-to place for most admin-side functionality, but to enforce or strongly suggest its use over the other panels is probably not going to work so well. …

Who knows. We’ve obviously arrived at the pub first, but maybe others will follow your lead.

if the docs can communicate that sort of ethos, that’d be grand

Certainly.

Bloke · 2015-10-07 12:54:59

Destry wrote #295449:

your plugin would make a good reference in the guidelines, if you didn’t mind

Fine by me.

Good to know that two similar plugins can (or should be able to) reside together in an install

It’s only possible because of the three-letter prefixes. Both tru_tags and smd_tags register their Extensions panel callbacks under the plugin name, which is unique. Both authors could utilise the same Textpack string though, which might be confusing.

Tagging, Content tags, Content tagging, Tags manager

All good ideas, thanks.

When it comes to usability, consistency trumps variability every time. That’s how human brains are wired, to adjust to patterns first. It doesn’t matter, as much, what that pattern is, so long as it’s consistent.

Aside: this is precisely the reason I despised Microsoft’s decision to use fold-up menus in Word/Excel/PowerPoint that showed the most recently used options at the top and hid the rest behind a twisty. Argh! Talk about slowing me down. I turned that “feature” off straight away. Similar sort of thing in Thunderbird e-mail actually. Select a message and right-click to bring up the context menu and Mark -> as Junk is halfway downish. Select two or more messages and that menu item is third from top, so I always glossed over it then had to hunt back up the list to find it. Luckily there’s a shortcut key ‘j’ which alleviates this nonsense.

1) If your plugin only provides one panel [snip]

The four guidelines sound fair to me.

Destry · 2015-10-07 13:56:38

Another nice thing about putting plugin panels under Extensions is that it’s easy to address the privileges aspect of them by presence of the Extensions region itself, as I’ve done in the roles and privs doc table. Otherwise it’s a shadow that can’t be documented easily/clearly. You’d have to pinpoint where each plugin panel is, like whack-a-mole.

Bloke wrote #295452:

Select two or more messages and that menu item is third from top, so I always glossed over it then had to hunt back up the list to find it.

That’s exactly why I suggested alphabetizing the Extensions panel menu, as it ensures a consistent position of items. And it’s also why you would want to keep plugin panels out of the core lists, so their patterns remain undisturbed. They could be alphabetized too, for that matter, to help improve the position pattern (against a logical convention).

This would mean thinking about plugin label options with respect to the alphabetization. For example “Tags manager” or “Tags management” might be better choices than “Content tags” because it puts the ordering on the priority term.

Bloke · 2015-10-07 14:04:44

Destry wrote #295457:

That’s exactly why I suggested alphabetizing the Extensions panel menu

The menu is ordered by plugin load order, as far as I’m aware. Try tinkering with the values and see if it affects the order.

We might be able to use alpha as a secondary sort order though, since that’d help with all the plugins that have the same load order 5.

Destry · 2015-10-07 14:31:07

Bloke wrote #295459:

We might be able to use alpha as a secondary sort order though, since that’d help with all the plugins that have the same load order 5.

+1

After nearly ten years I still seem to click about and double-scan the core region lists to find that one panel I’m rushing for because my mind is in alphabetical mode. Silliness on my part, I guess. Good thing there are not a lot of panel options in those lists or it would be more annoying. ;)

How would that secondary application order things for the Content region now, for example?

Last edited by Destry (2015-10-07 14:33:58)

Bloke · 2015-10-07 14:39:55

Destry wrote #295461:

How would that secondary application order things for the Content region now, for example?

Oh, I meant for the Extensions only. At the moment the core panels are in a fixed order, hard-coded. That also has the by-product that any additional functionality that plugins add to core areas always go below core panels, and are then ordered by load order.

Textpattern CMS

Textpattern CMS support forum

#1 2015-10-06 13:43:17

[doc] Extensions

#2 2015-10-06 20:29:35

Re: [doc] Extensions

#3 2015-10-07 10:36:45

Re: [doc] Extensions

Bloke wrote #295436:

#4 2015-10-07 12:54:59

Re: [doc] Extensions

Destry wrote #295449:

#5 2015-10-07 13:56:38

Re: [doc] Extensions

Bloke wrote #295452:

#6 2015-10-07 14:04:44

Re: [doc] Extensions

Destry wrote #295457:

#7 2015-10-07 14:31:07

Re: [doc] Extensions

Bloke wrote #295459:

#8 2015-10-07 14:39:55

Re: [doc] Extensions

Destry wrote #295461:

Board footer