dakar1Add my vote for this tag edinburgh1Add my vote for this tag create new tag
, view all tags

Feature Proposal: %INCLUDE% : Default Parameter Values (with documentation)


Using %INCLUDE% as macro
  • Do not wish to submit all values every time I call a fancy macro
  • Wish to have simple help on how to submit parameters the correct way

I have previously (in my Cairo days which ended last month) made similar solution for MacrosPlugin and can't live without something like this.

Description and Documentation

New variable %INCLUDEPARAMS% is introduced.

Suggestion for new VarINCLUDEPARAMS topic included below.

INCLUDEPARAMS{<list of parameter definitions>} - used in macro topics

  • Syntax: %INCLUDEPARAMS{<list of parameter names with default values and documentations string>}%
  • What happens:
    1. When viewed directly:
      • The defined paramters are shown in a table listed with default values and short description.
    2. When used as macro (i.e. shown via %INCLUDE{...}% in another topic)
      • The defined paramters are (again) shown in a table, now the actual value for the paramers are also shown.
      • The paramers will be used with default value if the parameter is not submitted by the %INCLUDE{...}%
  • Supported paramters: None (no fixed name parameters are supported).
  • Syntax for <list of parameter names with default values and documentations string> is shown by example:
             debug = "no      ::doc:: =yes= or =no="                    - Show debug information in =%INCLUDINGTOPIC%="
             size  = "medium  ::doc:: =small= , =medium= or =large=     - Size of brunch"
             egg   = "boiled  ::doc:: =boiled=, =srambled= or =porched= - How do you want your egg?"
    • ::doc:: is used as delimeter between default value on the left side and documentation on the right side (initial and trailing blanks are removed)
    • You cannot have a lineshift in the middle of a parameter definition
    • You must escape ", i.e. write \" to put a " inside a parameter definition
    • You cannot have an }% inside, use }<nop>% if you need to display }% as part of documentation
  • Examples:
    • See IncludeTopicsAndWebPages#UseAsMacro
      Disclaimer: The above link does not function until some changes have been made to TWiki docs, please read Changes to be made to TWiki doc
    • Output is put inside a <div class='twikiDefaultIncludeParamTable'> ...</div> , to disable output in %INCLUDINGTOPIC% you may...
      1. either Dynamically set css style div.twikiDefaultIncludeParamTable {display: none} (for instance based on %debug% parameter and %IF{...}% )
      2. or Place %INCLUDEPARAMS{...}% before your %STARTINCLUDE%

Changes to be made to TWiki doc

This requests comes with 5 additional files


No additional examples are supplied (se previous section).

Impact and Available Solutions

TWiki.pm is affected.

Patch Text TWiki-4-04.diff supplied.


-- Contributors: NielsKoldso


Hi Niels, could you add a use case how this would be used?

-- ArthurClemens - 27 Oct 2006

Hi Arthur

IncludedTopicUsedAsMacroFakeIt (one of the additional 5 topics) contains two simple usages:

  1. where you just call the macro (and don't bother to submit any arguments)
  2. one where you submit some arguments

The example is not a real one... I tend to make very generic macros with 20+ arguments governing all kinds of various behaviour.

In a typical macro invocation I only wish to submit a few of these 20 parameters, the remaining take their default values.

Also, for obvious reasons I wish to document how to use all these parameters - that is also relativively simple by means of %INCLUDEPARAMS%

Use case:

  1. I wish to make a fancy parameterised search over, parameters will govern
    • search criteria
    • conditionally
    • in- or exclusion of certain form-attributes
    • display of debug information
  2. I construct the macro topic using %this% or %that% or %jegskagidigskajeg% when ever i need at parameter to govern something
  3. I put this into the topic:
            this = "34  ::doc:: Use =this= for specifying bla bla bla..."
            that = "yes ::doc:: Use =that= for ..."
    Default value for this is 34 and for that default value is yes.
  4. Now I get a nicely rendered table displaying parameters (e.g. see SampleMacroDemonstratingIncludeParamsFakeIt) their default values and simple parameter documentation.
  5. When i call the macro using %INCLUDE{...}% I only need to submit parameters where default values needs to be changed.

Another use case:

  • This is also a way for me to maintain the interface to a macro if I late in life decides to extend it. E.g. the usecase is, I have used a macro 10.000 times, now I need to extend it with one parameter breaking the interface... eek!
    ohhh no I can add a default argument and I am saved from changing the 10.000 invocations of the macro smile

Hope this is sufficient, if not feel free to mail me at niels@slogPLEASENOSPAM.dk - I may not check in here daily.

-- NielsKoldso - 27 Oct 2006

I see some issues putting this in the core.

  • The syntax is a bit complex for normal users and does not look like anything we have in TWiki already. Having default values as such may make sense but the whole documentation part and the syntax for it seems to be a little but complicated - something that would more belong in a plugin. It should be possible for normal users to use the TWikiVariables and the features they represent without being total geeks.
  • The proposal does not address the fact that INCLUDE feature now supports several named sections within same topic. How will INCLUDEPARAMS work if a topic has 3 named sections?
  • MacrosPlugin still works in TWiki4 so it is possible maybe to extend this even further than this proposal suggests if very complexe macro features are desired.

There is no link to this from WhatIsIn04x01 so I am not treating this as a TWikiRelease04x01Process proposal but as a normal Codev discussion topic. We cannot start emailing proposers. It takes enough time to keep up with the normal proposals the normal way as it is already.

You are welcome to add your proposal to WhatIsIn04x01 but you will have to come back to your topic almost daily until a decision is made. However it is a good idea to let a new idea mature before going very official. Read TWikiRelease04x01Process to understand the current release process.

-- KennethLavrsen - 28 Oct 2006

Topic is now added to WhatIsIn04x01 and is an official proposal for 4.1. The concern I raised above means that it needs decision at release meeting. Niels. Can you comment on my concerns? Especially on the complexe syntax and the interaction with multiple named sections.

-- KennethLavrsen - 30 Oct 2006

Hi Kenneth

Thanx for feedback... I shall check in here untill decision has been made.

I have added the topic to WhatIsIn04x01

Regarding your issues:

  • Complex syntax:
    1. The variable is clearly for advanced TWiki users and TWiki application developers
    2. Maybe it could be "hidden" in a doing advanced includes section and not be listed in the TWiki variable overview.
    3. Given what it does, I find the syntax fairly simple.... okay - call me a total geek wink
  • INCLUDE supports several named sections:
    1. The INCLUDEPARAMS will be stripped and parsed and default values will be prettyprinted where the INCLUDEPARAMS appeared
    2. Parameters may be applied in any section... I could elaborate on this in documentation?
  • MacrosPlugin:
    1. Variable scope (e.g.=%TOPIC%=) is different from %INCLUDE%
    2. I don't agree that default parameters is a very advanced feature - eventhough the syntax is geeky

Another syntax suggestion:

In the macro topic write:

|*Parameter*|*Default Value*|*Documentation*|
| foo       | bar           | =foo= is a dummy parameter which should bee either =bar= or =zoo= |
I could rewrite the patch if the above syntax is less geeky.

Eventually one could skip %INCLUDEPARARAMS% entirely and just match on the table headder.

-- NielsKoldso - 30 Oct 2006

I like the feature of having defaults of TWiki Variables on an included topic. And I do not mind the INCLUDEPARAMS feature as such.

There is no other way that I know to set variables in a topic and have those settings work when you include the topic.

It is the syntax that I find odd and the main reason is that you also want to build in the documentation part. Is that really needed? When would you really need this in a TWiki Application? And would people actually want it shown as a table with some fixed format?

It would make more sense that IF you need to document the parameters you do so in the topic outside the included section.

If the feature is implemented without the doc part then the syntax

%INCLUDEPARAMS{this="34" that="yes"}%

seems so much more simple and easy to understand. When we start adding some documentation of the variables feature to it then it seems more like a plugin type feature than a core feature.

If people accept this at release meeting then a few more words of causion. We have to make sure that any values cannot override for example ALLOWTOPICREAD or ALLOWTOPICCHANGE in both including and included topic.

-- KennethLavrsen - 05 Nov 2006

So the only difference to MacrosPlugin is that one can specify defaults to the parameters, right? -- Hm. Could be useful, although I'm not sure if that this isn't already possible by some clever combination of INCLUDE and CALLMACRO.

-- FranzJosefSilli - 06 Nov 2006


  • I guess you could hack your way and get default parameters using %CALC{...}% as follows
    and when you need foo write:
    but that would be quite painfull dead!
  • Shouldn't CALLMACRO be made superfluous by INCLUDE? I.e. why having something implemented 83% in core and then reimplemented slightly different in plugin in order to add the remaining 17%?


  • Regarding need for documentation
    • We have had the need...
      before this patch we simply did it by doing a seperate handwritten table documenting the parameters and showing default and actual values.... quite a job
  • Regarding the ugly documentation syntax:
    • I would really like it - but I could live without
    • Notice: You don't need to document anything... %INCLUDEPARAMS{this="34" that="yes"}% would work fine
    • I think documentation should be as close to code as possible, i.e. right next to the argument definitions
    • I think the TWiki table syntax I proposed 30 Oct is far better syntax - it also reminds me of doing TWiki Form
      I could probably rewrite patch if you think this would remedy the syntax hurdle
  • Regarding dumping arguments in fixed format table
    • This is nice for documenting your macro (but would clearly be superfluous if TWiki table syntax is used)
    • It is also quite nice for debugging your macro at INCLUDE time
    • The dumping could be governed by seperate variable say %DUMPPARAMS% so default dumping did not occur. Could maybe also be parameter to INCLUDE.
  • Regarding values override
    • I am by far TWiki core expert, but the default arguments are handled the same way as normal arguments explicit specified at INCLUDE time - so I think if normal arguments are OK this proposal should also be

-- NielsKoldso - 09 Nov 2006

I am confused for several reasons:

  1. sounds like it can and should be delveloped as a plugin
  2. the docco is really not clear as to what it does
  3. why are you limiting yourself to doccoing just INCLUDE - shouldn't all TML tags be doccoed in the same way?

-- SvenDowideit - 13 Nov 2006

From EdinburghReleaseMeeting2006x11x13.

Proposal as originally put forward is rejected. Does not belong in core as proposed. And new proposal is for 4.2 in this case because of lack of time before 4.1 release.

Note that some had a problem fully understanding this feature and Sven had a work around. See a very advanced use Bugs:Tabulator using standard features to set default.

-- KennethLavrsen - 13 Nov 2006

OK - thanx.

I think the defaults Sven uses are for a CGI call not a macro (i.e. INCLUDE) - so it isn´t really a solution to the problem.

I thinke the motivation (at the top) very clearly state what this is about, eventhough the proposed documentation and implementation may be clumsy.

I don't know why it did not pass, so it will be difficult to put forward a new proposal.

-- NielsKoldso - 16 Nov 2006

There is nothing wrong with your description. If people just spent more than 10 seconds reading they will understand what you wanted to do. But it shows that if people propose something they should also spend the two hour showing up at a release meeting defending it.

And even if your proposal is rejected as is there is still a good chance for getting a feature resolving the essential problem implemented. Ie. the ability to set default values for twiki vars in included topics.

Sven. I am trying to make a simple example of the Bugs:Tabulator method working. And I cannot. Please tell us how this is supposed to solve the problem Niels is trying to resolve.

See IncludeSectionTestMaster and IncludeSectionTest and make the example work.

Ie. the example should be able to set the VALUE4 to Delta without having VALUE4 defined in IncludeSectionTestMaster.

If it is not possible then we rejected this proposal on a false assumption.

-- KennethLavrsen - 16 Nov 2006

mmm, I just played around with your example Kenneth, and these are my observations

  1. yep, I was wrong. if you look at IncludeSectionTestMaster you see something that is both bizzare, and non-sensical.
  2. I see this as a bug in TWiki, in the way it processes preferences from INCLUDEd topics
  3. I still stand by my opinion that the fix to this does not require any new syntax
  4. combining a proposal of TWikiVariable defaulting in INCLUDEs and documentation funtionality makes it hard for me to figure out what is important in the proposal, and from the meeting it seemed others had similar issues.

and no, I don't understand what you really want to do, but worse, I can't fathom from the proposed docco what the tag does, nor why its needed, rather than fixing TWiki.

I'm rather puzzeled, why the rendered output contains a table of parameters every time, both view topic, and when INCLUDEd, but thats a trivial fix.

so, in conclusion:

  1. this seems to me to be several new features rolled into one
  2. the docco that would be distributed need to be much more clear - in fact, without that, the feature should be rejected, as the docco is the hardest, and most important part.
  3. your motivation sounds good, the problem is the reasoning behind why you're choosing this implementation, and the mixing of concerns that i'm unclear on.

-- SvenDowideit - 16 Nov 2006

Sven and community.

We all agreed at the release meeting that the proposal here was too complicated to be a core code candidate. So I think we should agree not to discuss the exact proposed syntax and focus on WHY the proposal came up in the first place.

When one topic includes another topic, any settings in the included topic have no effect. This is not new. It was like that in Cairo also.

  • Is this an old bug?
  • Is there a working work around?
  • Do we need a new feature added - which is simpler and "core code like" which addressed this? I have personally many TWiki applications that I could make more efficient if included topic settings would work somehow without duplicating the settings in the including topic. And as I write this someone on IRC is asking the same.

-- KennethLavrsen - 16 Nov 2006

Just FYI, if you need to have variables persist across included topics you can use SpreadSheetPlugin variables, as demonstrated in SpreadSheetRollupTest.

-- PeterThoeny - 16 Nov 2006

That may be a working way of setting variable persistantly. But it is a horrible hack and very difficult to understand and use.

TWikiVariables from plugins etc are expanded in an including/calling topic even when they are in included topics.

It is the * Set MYVAR = Value that is not working. What is the reason for not having this working? It seems that it is in noones interest to see the raw unexpanded variables in the including (calling) topic.

And I have a hard time imagining which TWiki Applications that could be negatively affected if we decide to change the behavour.

I see myself adding variables only used in ONE topic to WebPreferences again and again because of this problem because that is the only sensible way to make things work.

It is only a few weeks ago I ran into the issue here on TWiki.org. In TWikiRelease04x00x05 I had defined the release version as a TWikiVariable and then use the variable 20 places in the topic text. That worked great for my hotfix releases. When I had to make a new release topic I could just copy the text and change the Set statement one place. But then I had to make a real release, and since DownloadTWiki includes the latest release topic, this did not work in DownloadTWiki, where you ended up seeing an unexpanded TWiki var. And using the SpreadSheetPlugin hack never came to my mind and it is an awful hack in the first place. We have a nice simple feature of defining TWiki variable in topics with the * Set statement and then using it in the topics and if this worked when you include a topic many worries would be over.

In my view the *set statements should simply work as if they were defined in the calling topic.

The only issue I can see is that ALLOW and DISALLOW and vars should not be persistant accross.

The advantage of this is that is would be

  • Logical
  • Intuitive
  • No new syntax needed
  • This issue that triggered this proposal in the first place would be eliminated.

An important detail for the INCLUDE with parameters is that the parameters in the INCLUDE statement should overwrite any * set statements in the included topic. Otherwise we will still not be able to define defaults.'

This may have significant code implications. But to me it seems like the right thing to do instead of inventing new exotic syntax and features to mend a basic problem.

-- KennethLavrsen - 16 Nov 2006

Kenneth, this is a good analysis and is customer focused.

-- PeterThoeny - 17 Nov 2006

Heads-up: I will support this feature as part of the EditSectionPlugin. I will add other bell's and whistle's to %INCLUDE% to make sections more useful and am looking for suggestions.

-- ThomasWeigert - 17 Nov 2006

TopicClassification FeatureRequest
TopicSummary %INCLUDE% : Default Parameter Values (with documentation)
CurrentState UnderInvestigation

  1. Agree on feature
  2. Agree on spec for syntax
  3. Apply patch
  4. review code
  5. test
  6. Put documentation into place.

InterestedParties NielsKoldso
ProposedFor EdinburghRelease
TWikiContributors NielsKoldso
Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatdiff TWiki-4-04.diff r2 r1 manage 4.4 K 2006-10-27 - 23:29 NielsKoldso Patch against TWiki 4.04 implementing %INCLUDEPARAMS{...}% (minor rendering bugfix)
Edit | Attach | Watch | Print version | History: r21 < r20 < r19 < r18 < r17 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r21 - 2006-11-17 - ThomasWeigert
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.