[pmwiki-users] Feature request: Action lists in skins

[Joachim Durchholz]

Patrick R. Michaud wrote:

> On Thu, Apr 07, 2005 at 10:48:43AM +0200, Joachim Durchholz wrote:
> 
>>I simply don't get it. What the heck is complicated about
>>
>>  <!--ActionList-->
> 
> To a skin designer who simply wants to display the actions (and assumes
> that they're set properly), I agree this is not complicated.  But for a 
> wiki admin who wants to change the set of actions that appear at this point,
> it's not at all obvious where they're stored or how to do it.  And if
> those actions are held in an array, the admin has to know a fair amount
> about the internals of <!--ActionList--> to make it work.  Contrasted
> with the version that has the HTML directly in the skin template,
> this is definitely more complex for the wiki admin.

I don't think that the wiki admin will deal directly with that part of 
the skin, at least not directly.

>>>> And just to compare:
>>>>
>>>> <a href='$PageUrl?action=print'>$[Printable View]</a>
>>>> <a href='$PageUrl?action=diff'>$[Page History]</a>
>>>> <a href='$PageUrl?action=edit'>$[Edit Page]</a>
>>>
>>> This is definitely more straightforward.
>>
>> What? Three lines of HTML interspersed with PHP conventions, with two 
>> different syntactic conventions that must be followed to a single 
>> character, is "more straightforward" than a single 
>> <!--function:ActionList-->???
> 
> Yes, because anyone designing a skin (or customizing the actions)
> must already be aware of these syntactic conventions in order to be
> able to work with other non-action portions of the skin.
> <!--function:ActionList--> doesn't totally eliminate the need for 
> $-substitutions from the skin (think of $Group, $Title, $SkinDirUrl, 
> and $WikiTitle), so a skin designer still has to know how they work.
> What <!--function:ActionList--> does do is add another place to have
> to look for the link information; i.e., complexity has gone up.

Only if the skin designer wants to interfere with the order of the 
actions, or their selection.

> Consider our two examples:
> 
>     <a href='$PageUrl?action=print'>$[Printable View]</a>
>     <a href='$PageUrl?action=diff'>$[Page History]</a>
>     <a href='$PageUrl?action=edit'>$[Edit Page]</a>
> 
> versus
> 
>     <!--function:ActionList-->
> 
> Remembering that a skin designer already must know about HTML and 
> $-substitutions to work with other parts of skin, which of the 
> above is more straightforward (obvious) for achieving:
>    - change the sequence in which actions are displayed
>    - remove the "Page History Link"
>    - add an "Upload" link
>    - add a link to a non-wiki page

None of these are a skin designer's business.

The first three are the domain of the wiki administrator. If you force 
the wiki admin into editing the skin, he'll have to learn the skin 
syntax along with HTML, CSS, and PHP. It's forcing him up the learning 
curve, at a time when his mind is on functionality, not design.

The last one is unrelated to the ActionList markup, it's part of the 
question what's the right kind of granularity for specifying what goes 
into the action links. Maybe it's better to set the action array up as a 
simple list of HTML à la

   $ActionList = array (
     '<a href="$PageUrl?action=edit">$[Edit Page]"</a>',
     '<a href="$PageUrl?action=print" target="_blank">
                                     $[Printable View]"</a>',
     ...
   );

Maybe it would be better to code each entry with the action's internal 
name as in

   $ActionList = array (
     'edit' =>
       '<a href="$PageUrl?action=edit">$[Edit Page]"</a>',
     'print' =>
       '<a href="$PageUrl?action=print" target="_blank">
                                       $[Printable View]"</a>',
     ...
   );

that would allow PmWiki to wrap different HTML markup around each action 
item, or leave out action items that are disabled.

Maybe it's better to put the visible text into a separate field so that 
translation can be enforced, as in

   $ActionList = array (
     'edit' => array (
       'htmlattributes' => 'href="$PageUrl?action=edit"',
       'text' => 'Edit Page'),
     'print' => array (
       'htmlattributes' => 'href="$PageUrl?action=edit" target="_blank"',
       'text' => 'Printable View'),

though that may already be too rigid, it's conceivable that somebody 
wants to do stuff like <a href=...>``edit''</a>.

 >    - change the separator between the links

That's covered. Either as

   <!--function:ActionSeparator * -->
   <!--function:ActionList-->

or as

   <!--function:ActionList separator=*-->

(I fear that the latter is too inflexible - separators may span multiple 
lines or contain equals signs, and I'm not sure that the skin markup can 
handle that.)

> Nearly anyone who knows HTML and CSS--a prerequisite for skin design--
> can figure out how to do it in the first case (or at least make a very
> good guess), but almost nobody can say how to do it in the second case
> without a lot of additional study or details.  Now then, which is 
> "more straightforward"?

It's the wrong target audience. Skin designers don't (well, shouldn't) 
care what goes into the action lists. All they need to know is that they 
have to place that "ActionList" thing somewhere (just as they should 
place the SideBar somewhere, which 90% no doubt do by copying the code 
from pmwiki.tmpl - I did so myself when I did my first experiments with 
skins).

Skin designers don't care (and don't need to care) how the various 
action URLs are encoded. (That's also something that I don't like about 
having the action links in the skins. If I'm a skin designer, I have to 
learn about all the ?action= conventions. I'm also constantly worried 
that I may have put too many or too few links into the action list.)

>>*Skin writers* live in the skin syntax. They already know about 
>><!--wiki:...--> and <!--function:...-->, dealing with 
>><!--function:ActionList...--> should be no news to them.
> 
> They also know about $-substitutions, that's not news to them either.
> And <!--function:--> is indeed news to many skin designers, it's a FAQ.

OK.

>> *Recipe writers* deal with the contents for the action list. They live 
>> in the PHP world, so it's no great deal for them to provide an array like
>>   'action' => 'print',
>>   'name' => 'Printable View',
>>   'attributes' => 'target='_blank'
>> so that the ActionList function can apply i18n to the 'name' attribute 
>> and generate the proper action list HTML.
> 
> Unfortunately you've skipped/overlooked the biggest audience
> and PmWiki's primary target: wiki admins.  Wiki admins are usually neither
> skin designers (i.e., creating skins for others to use) nor recipe writers, 
> but just want to get a wiki running and customized to appear how they
> want it.

Agreed.

But these need to know enough about PHP to set up config.php.

In the vast majority of the cases, i.e. if the various recipes and the 
standard configuration "do the right thing", there's no need to ever 
touch the actionlist machinery for them.

 > And as a group wiki admins are far less comfortable with PHP than
> with HTML/CSS.  By moving the action list out of the skin and 
> into a structured PHP array, we're moving farther away from the world
> that most wiki admins live in (HTML), and we're removing control of the
> output from the audience that needs and demands it most.

Do they indeed need that control?

When settin up my wikis, the one thing that I wanted was the standard 
set of actions, plus any actions included via recipes.
I specifically did *not* want to delve into the intricacies of the 
action lists in the skins. I didn't even want to bother with the skins 
at all. Yet I was forced to deal with them.
When I started, I met a bewildering array of action links. Some of them 
had a target=_blank in them, some didn't - well, I could make sense of 
that, but only after some serious looking through all that syntax. 
Anyway, I had no clue whether that target=_blank should go into any new 
action links - I had to experiment. The recipe author didn't tell me - 
he just provided the ?action link and handed me the obligation to decide 
what to do with it.
Checking out the special attributes on the other action links was 
painful for me.

Then I met the beeblebrox-gila2 template. It had a "read" action. Huh?? 
It also had a bewildering array of additional action; some of them I 
liked and would have wanted them in the other skins (particularly in the 
phase when I was trying out several skins to see which worked best for 
me); some of them couldn't have been lest interesting to me so I had to 
remove them.

I would have thought that checking all the skins would have been a 
simple matter of downloading them, then in turn configuring PmWiki to 
use that skin and try it out. (No, I didn't know about ?action=setskin 
at that time. I was trying to get around PmWiki, and hadn't had the time 
to look into all the recipes that might have interested me.)

Note that all this is an experience report from a PmWiki newbie admin. 
(That phase is just one or two months in the past, so the memories are 
quite fresh.) I know I'm technically a bit too far from the average so 
that all my ideas can be useful, but the above report should convince 
anybody that the current state of action handling in skins leaves many 
things to be desired.

I'm not yet convinced see that the wikipage approach solves the issues. 
It nicely decouples the action list from the skins, but it still burdens 
the administrator with writing the actions down. If the admin mistypes 
something, he'll get into trouble (he may even lose all actions and not 
know how to get back into the edit page - if he's new, he may not know 
that simply adding ?action=edit will get him the edit page no matter 
what the action list is).

However, there's a place where all the information on actions is 
available. It's wherever the various actions are defined and 
implemented: in the wiki core and in the PHP recipes. It's *these* that 
should update the action list. Why should the wiki admin bother with 
these clerical tasks? He has selected the recipe that implements that 
?action=foo, then why doesn't the recipe also install the item in the 
action list?

> And when wiki admins feel out of control, or that the "learning
> curve" for customizing the output is too steep, they'll start looking
> for other packages altogether.

Agreed.

It's just a question what kind of control they need in what 
circumstances. The common case should be easy - and in my experience, 
the common case is "not very much control at all".

As a wiki admin, I want the recipes do their magic. I don't want to 
bother going into separate pieces of the software (be it config.php, or 
a wiki page, or even a couple of group-specific wiki pages - horror!) 
just to see those links.

If actions aren't for the general public, I want them hidden from view 
until I log in with the proper admin or group password. If actions are 
just for a specific group, then I do have to delve into group-specific 
stuff - but then setting up group-specific configuration is something 
that can be done in config.php, via

   if ($Group == 'specialgroup') {
     include_once('cookbook/specialaction1');
     include_once('cookbook/specialaction2');
   }

Do I want control over action order? Not really. Well, maybe. It's not 
something that I think about often. Given the way that many skins look, 
not many skin designers think about that more often. Just letting the 
actions come out in the order in which they were defined would probably 
suffice. (OK, that rules out PHP arrays with action names as keys. Not a 
serious problem though.)

>> Well... now that I'm thinking about it...
>> It seems as if I'm quite unsuccessful at communicating here. I've
>> been trying to contribute that way, but I'm obviously a miserable
>> failure in this regard.
> 
> Not at all, I think that the discussion is very fruitful.  I'm sorry
> that this is being so frustrating to you, I'm just trying to keep
> the needs and capabilities of the various audiences in play.  

It's good if you do that.

It's just that I'm at an 80% solution right now, with bits and pieces 
hanging around. I get ample feedback on those missing 20%, but I haven't 
gotten anything about the 80% part - yet I need the latter to do the 20%.
What frustrates me isn't that nobody seems to agree with it instantly. 
The situation is that I'm exploring a quite lonely part of design space, 
and instead of helping me find a way to better places from where I am, 
everybody insists on restarting from someplace entirely different. 
That's frustrating for me and ineffective for both sides of the exchange.

Regards,
Jo