Feature Proposal: allow a list of topics to be specified so that we can use INCLUDE to allow customisation of shipped topic elements.

Motivation

UpgradeSafeCustomisationsOfSystemTopics for one, WidgetsSkin and many user customisable wiki applications.

Description and Documentation

extend the existing topic specification (_DEFAULT) parameter to allow the INCLUDE macro to have a list of fallback topics to use if the previous one is inaccessible to the current user.

lack of access includes (in order of processing):

1. topic or web does not exist
2. user does not have view permission
3. if a section is specified and it does not exist in the topic.

the list of topics is specified in the same way as the topic param in SEARCH - do we want to include wildcard too?

• atm, i think SEARCH's topic lists are comma and/or whitespace separated - it'd be interesting to see if linefeeds work just as well (for readability)

If no accessible topic is found, it falls through to the current behaviour of INCLUDE on a missing topic.

Examples

%INCLUDE{"Topic1, Topic2, %SYSTEMWEB%.Topic3"}%

Or a more dynamic version:

%INCLUDE{"
%BASEWEB%.%WIKINAME%leftbar,
%MAINWEB%.%WIKINAME%leftbar,
%MAINWEB%.%WIKINAME%leftbar %BASEWEB%.leftbar,
%MAINWEB%.defaultleftbar, %SYSTEMWEB%.defaultleftbar
"
section="testcase"
}

Impact

speed, and simplicity

Implementation

-- Contributors: SvenDowideit - 10 Mar 2010

Discussion

It occurs to me that we do not need to add a new parameter default, we can just allow the existing topic specification parameter to be a list.

-- SvenDowideit - 10 Mar 2010

Technically default is not needed, right.

But from a user perspective, something like "include this, that" suggests all topics are included together, which is not what it is intended to mean. So I think making it an "include this, default to that" is easier to understand imho, and probably more in line with what other macros do.

-- MichaelDaum - 10 Mar 2010

Michael has a very good point here. I also prefer the default= syntax. It is more clear to the enduser

-- KennethLavrsen - 10 Mar 2010

What does default="topic1,topic2" imply? Include both, or topic1 and if that does not exist topic2? Or should it be "topic1|topic2"?

-- ArthurClemens - 10 Mar 2010

Is this shorthand for %INCLUDE{"%IF{"exists BlahBlah" then="BlahBlah" else="BleatBleat"}%"}% ? Or does it imply something more e.g. access control checks on the topics? i.e. the spec is incomplete, so raising a concern.

You are trying to say "include the first topic from this list that I can actually access", right? This solution seems very specific to this fairly narrow requirement. I'm just wondering if there might be a more general way to do the same thing using embedded macros e.g.

%INCLUDE{"%QUERY{"first('BlahBlah,BleatBleat' allows 'VIEW')"}%

(This is not an alternative proposal, just a discussion point)

-- CrawfordCurrie - 10 Mar 2010

awesome! can I really do

%INCLUDE{"%QUERY{"first('BlahBlah,BleatBleat' (topicexists AND allows 'VIEW'))"}%

cos um, yes, its include the first topic from this list that i can actually access.

and then I also need

%INCLUDE{"%QUERY{"first('BlahBlah[section=banana],BleatBleat[section=defaultbanana]' (sectionexists AND allows 'VIEW'))"}%

this is like the HERE docs - I don't really care what the syntax is, i want it.

(there is something screwy with allows VIEW or maybe it was allows CHANGE if the topic does not exist, making it necessary to specify.)

-- SvenDowideit - 10 Mar 2010

Wow, where does first() come from? I hope I will be able to learn all of the QUERY syntax one day and remember it

-- MichaelDaum - 10 Mar 2010

I invented first for purposes of discussion; and auto-conversion of a scalar var to a list type, too. The point was not to show an implementation, but to suggest a different way of thinking about the problem.

-- CrawfordCurrie - 10 Mar 2010

I think the original spec is clear and simple. The topic is included if it exists and you can read it. Otherwise you get the default.

And I prefer the real simple with INCLUDE that takes ONE value and ONE default. No lists.

Simple solutions for simple normal non-programmer people. I do not like the geek thing you just started discussing. It is programmer talk.

-- KennethLavrsen - 10 Mar 2010

I agree with Kenneth. We should make it "as simple as possible, but not simpler". If advanced users want to use IF and QUERY inside INCLUDE they can do as they like, but it should not be the default API.

I am raising my concern about the ambiguity of the list approach and the complexity it introduces for users.

-- ArthurClemens - 10 Mar 2010

Just as I was going to suggest car and cdr (programmer joke)

No worries, I understand the concerns. Just trying to make people think out of the box.

Spec remains vague (though somewhat clarified in the discussion) so concern remains.

-- CrawfordCurrie - 11 Mar 2010

Just for the records. There's a macro in NatSkinPlugin called WEBCOMPONENT. This works like this: %WEBCOMPONENT{"SideBar"}% will look up topics in the following hardcoded order and INCLUDE the first one that was found:

1. WebSideBar in the current web
2. SiteSideBar in the Main
3. SiteSideBar in the System

This covers the use case for customizing webs though there might be some creative use that I havent thought of. It obviously is a lot less generic than anything proposed here, but very easy to use.

I'd really like to replace this custom macro with some kind of include mechanism that still is easy to use.

While I am stunnedl by the possibilities of extending the QUERY language in various directions in a clearly superior way from the perskective of parsing and combining these kind of expressions, I really hope to be able to use INCLUDE with a list of defaults as an exactly fitting replacement for %WEBCOMPONETS.

I am a bit concerned about the raised concerns though. Users are not that dumb not to understand a list of defaults used in a left-to-right preference order.

-- MichaelDaum - 12 Mar 2010

The ambiguity is the combination of the list and the default parameter. Why have a list if you also have a default parameter? Why would only the default parameter take a list?

The way I see it we either:

1. Have a list of possible includes: %INCLUDE{"topic,orelsetopic,ifallfailstopic"}%
2. Have a default parameter: %INCLUDE{"topic" default="orelsetopic"}%

-- ArthurClemens - 12 Mar 2010

Why not %INCLUDE{"topic" default="orthis, orthis, orthat"}% ?

-- MichaelDaum - 12 Mar 2010

personally I need a list - ie, 3 or more topics that will be tested for existence. originally, I thought, bingo, add a 'default param sounds good, why not make that a list.

then I slept on it, and decided that was pretty redundant, when all we really need to do is make the original topic specifier a list.

so, yes, I listed 2 possible candidates in the proposal to see which was preferred.

I'd much rather not add another parameter - so I would vote for making it %INCLUDE{"topic,orelsetopic,ifallfailstopic"}%

It seems that to me that both concerns are because I provided a choice for us to make before implemention.

and so, I've changed the spec to remove that choice.

-- SvenDowideit - 12 Mar 2010

I am ok with the updated spec, so I have removed my concern.

I have also added a simpler example.

-- ArthurClemens - 12 Mar 2010

Yes. With just extending the current spec to accept a list the feature becomes less confusing.

Naturally there is the small question: Does the list of 3 include all 3? But that we cannot do anything against no matter what syntax. And it is very simple to document with one line in VarINCLUDE.

In topics where it is used like %INCLUDE{ "Main.UserRegistration, DefaultUserRegistration" }% it becomes very obvious what is going on.

I like this and it will be very useful in many contexts where we have to do cryptic IF constructions today.

-- KennethLavrsen - 14 Mar 2010

Crawford. With the simplified spec where INCLUDE takes a list of topics instead of one topic and includes the first topic it can find and is allowed to display - can you lift your concern?

We are many that would like this feature in 1.1 for many reasons. And the original concern most of us had was the confusing spec. The final proposal above is simple and compatible.

-- KennethLavrsen - 15 Mar 2010

Assuming fall-through to the current behaviour of INCLUDE with a missing topic, then it's OK.

-- CrawfordCurrie - 16 Mar 2010

The 14-days are over. The proposal has developed during the period. Concern was raised but with the spec change the concern was lifted. Spec in the proposal is updated and stable.

So I call this accepted by consensus.

Sven. You can check in the code. It must be before 1st of April to meet the deadline for feature freeze.

-- KennethLavrsen - 24 Mar 2010

two years later, and implementation is commited for 1.2.0.

-- SvenDowideit - 23 Apr 2012