%INCLUDE{ "OtherTopic" anyname="anyvalue" foo="bar" }%
$n() for new line, $quot() for double quote, $lt() for less-then sign, $gt() for greater-than sign, $nop() for a no operation. Example: table="|*Lunch:*|Sushi|$n()|*Dinner:*|Lobster|"
%PARAM{ "name" default="value" }% variable with parameter name and default value, like: %PARAM{"anyname"}% parameter and %PARAM{"foo"}% parameter
%PARAM{ "lunch" default="Sushi" }%
%PARAM{}% variable gets removed silently when directly looking a topic, e.g. if topic is not included
%URLPARAM{"anyname"}% and %PARAM{"name"}%: %URLPARAM{"anyname"}% as documented in TWiki variable gets renamed to %PARAM{"anyname"}%
%URLPARAM{"anyname"}% variable is deprecated but remains implemented for compatibility.
%INCLUDE{ "http://www.cia.gov/cia/publications/factbook/geos/%PARAM{ "countrycode" default="np" }%.html" }%
<table bgcolor="#FFFF00" border=2 cellpadding=10><tr><td>
%PARAM{"quotedtext" default="(Nothing to say)"}%
</td></tr></table>
Here is Bill said in his email:
%INCLUDE{"QuoteInclude" quotedtext="I like pie."}%
Here is what Jane said:
%INCLUDE{"QuoteInclude" quotedtext="I like cake."}%
Here is what Fred said:
%INCLUDE{"QuoteInclude"}%
* *India*
* CIAFactbook:in
* *Historical Background:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Background:.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Economy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Economy - overview:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Industries:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Industries:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Internet Service Providers:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Internet Service Providers \(ISPs\):.*?<br>\s*(.*?)\s*<\/td>.*"}%
* *Literacy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Literacy:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/table>.*"}%
* *Languages:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/in.html" pattern="^.*?Languages:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Nepal*
* CIAFactbook:np
* *Historical Background:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Background:.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Economy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Economy - overview:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Industries:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Industries:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Internet Service Providers:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Internet Service Providers \(ISPs\):.*?<br>\s*(.*?)\s*<\/td>.*"}%
* *Literacy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Literacy:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/table>.*"}%
* *Languages:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/np.html" pattern="^.*?Languages:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Pakistan*
* CIAFactbook:pk
* *Historical Background:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Background:.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Economy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Economy - overview:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Industries:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Industries:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Internet Service Providers:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Internet Service Providers \(ISPs\):.*?<br>\s*(.*?)\s*<\/td>.*"}%
* *Literacy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Literacy:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/table>.*"}%
* *Languages:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/pk.html" pattern="^.*?Languages:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *India*
<!--
* Set COUNTRYCODE = in
-->
%INCLUDE {"CountryInfo"}%
* *Nepal*
<!--
* Set COUNTRYCODE = np
-->
%INCLUDE {"CountryInfo"}%
* *Pakistan*
<!--
* Set COUNTRYCODE = pk
-->
%INCLUDE {"CountryInfo"}%
* CIAFactbook:%COUNTRYCODE%
* *Historical Background:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Background:.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Economy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Economy - overview:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Industries:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Industries:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *Internet Service Providers:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Internet Service Providers \(ISPs\):.*?<br>\s*(.*?)\s*<\/td>.*"}%
* *Literacy:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Literacy:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/table>.*"}%
* *Languages:* <BR>%INCLUDE{"http://www.cia.gov/cia/publications/factbook/geos/%COUNTRYCODE%.html" pattern="^.*?Languages:<\/div>.*?<br>\s*(\S.*?\S)\s*<\/td>.*"}%
* *India*
%INCLUDE {"CountryInfo" parameter('COUNTRYCODE','in')}%
* *Nepal*
%INCLUDE {"CountryInfo" parameter('COUNTRYCODE','np')}%
* *Pakistan*
%INCLUDE {"CountryInfo" parameter('COUNTRYCODE','pk')}%
#-------------------------------------------------------------------
sub decode_field { my ($field) = @_;
$field ||= '';
$field =~ tr/+/ /;
$field =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex(1ドル))/eg;
$field =~ s/\s*$//; # trim trailing spaces
return $field;
}
---+ %INCLUDE{"%PARAM{"requesttopic" default="ParameterisedIncludes"}%" section="title"}%
%INCLUDE{"%PARAM{"requesttopic" default="ParameterisedIncludes"}%" section="%PARAM{"section" default="synopsis"}%"}%
Which if the twiki here supports INCLUDEs (does it? looks like twiki.org doesn't allow remote includes as of 21/Nov/2003) would be used:
%INCLUDE{"http://chaos.owiki.org/AnySectionAnyTopic?remotetopic=NamedIncludeSections"}%
You get:
%INCLUDE{"http://chaos.owiki.org/AnySectionAnyTopic?remotetopic=NamedIncludeSections"}% (Given this fails here, see http://chaos.owiki.org/ParameterisedIncludes for the working example)
Regarding your code fragment - thanks I'll incorporate that, however it'll probably only get used if there isn't a cgi query available - since the unescaping of URLencoded content is best done by CGI.pm since it's tried & tested, and there' irritating edge cases that can happen in certain scenarios which would need dealing with (normally relating to double encoded things getting passed as parameters).
-- MS - 21 Nov 2003
-- RaymondLutz - 21 Nov 2003
Raymond, nice idea, it fits nicely the TWikiMission and moves TWiki more towards an application platform smile
Added proposed syntax on top. Feedback appreciated.
A simple example is needed. Raymond, your example is good but somewhat complex. Possibly a silly "hello world" example for illustration purposes only.
-- PeterThoeny - 21 Nov 2003
Problems with proposed spec: $n() for newline. I updated proposed spec -- PeterThoeny - 22 Nov 2003
lunch=Sushi present, the including topic specifies a lunch="Dim Sum" parameter, and the included topic has a %PARAM{"lunch"}% variable.
%INCLUDEPARAM{...}% variables if encountered in an included web page. Technically it would be simple to implement.
$lt() and $lt() escapes, useful to escape verbatim if passed to an include. -- PeterThoeny - 25 Nov 2003
%LOCAL{"email" = %BEGIN%
To: Joe Blow
From: Jim Bob
Subject: Did you receive the report?
Hi Joe:
I sent you a report by physical mail. Please let me know when you receive it.
Thanks.
--Jim
%END%}%
%INCLUDE{"QuoteInclude" quotedtext=%PARAM{"email"}%}%
Here, I am also assuming that you can define local variables, that exist only within the current topic, and maintain the value after the time it is defined until it is redefined or the end of the topic is found. In other words, the local variable could be used for different values as the topic is expanded. For example:
%LOCAL{"who"="Jim"}%
The persion was %PARAM{"who"}%. <-- returns Jim
%LOCAL{"who"="Bob"}%
The persion was %PARAM{"who"}%. <-- returns Bob
That is a start. I think there are other cases but I am out of time at the moment.
-- RaymondLutz - 24 Nov 2003
The local variable is an interesting idea, best to follow up in LocalTopicVariables . Could (should?) be implemented as a Plugin. See related $set() and $get() of the SpreadSheetPlugin. See also related TopicVarsPlugin.
-- PeterThoeny - 25 Nov 2003
You are right that the local variable question will not stop us from going ahead with providing parameters, as long as we realize that the functionality of INCLUDE with simple (only literal) parameters will serve only so far. Of course, I guess you could force the existance of one-liner variables by including twice, with the variables then called %PARAM{"variablename"}% by the secondary include. The big problem with variables, that can be addressed separately, is that they can only be simple character strings, and not other data types, such as a file or hash.
After this holiday weekend, I was able to reflect on this situation a bit more, and will propose that we back up a bit more and consider defining a TopicObjectModel, because I see other problems with the way variables are being handled now, as well as the concerns about the (I claim inappropriate) nesting of meta tags in the topic object. The method of development for TWiki, due to the inherent nature of splitting topics into small topics, and encouraging plugins seems to result in a development track that is rapid, but does not necessarily follow a larger architectural structure. As there is no real rush, we may want to wait on adding anything to INCLUDE, but I still am a proponent of splitting the INCLUDE code into a separate code module, Include.pm.
-- RaymondLutz - 01 Dec 2003
I think we can go ahead with the implementation, the spec on top looks now solid.
The changes are not that complex, I suggest not to introduce a new module just for that.
-- PeterThoeny - 10 Dec 2003
FYI I did both parameterised includes and local variables in the FormQueryPlugin (see %CALLMARO and %SET). The only gotcha was getting the scoping of locals right.
I thought there was a move to shift more into plugins, not pile more lard wink into the core. Given that I was able to do it in a plugin, should this really be part of the core?
-- CrawfordCurrie - 10 Dec 2003
I agree that this is ready for implementation, with limited support of variables, i.e. literals only. We can extend that later.
The act of splitting the %INCLUDE% code to a isolated module does not have to do with the complexity of the current request, it is a function of moving distinct features into separate modules that can be managed separately, important for design of any system with multiple contributors. If you wish to maximize progression, there will be general support of moves to segment distinct functions into their own module. On the other hand, if there is a (perhaps unstated) desire to maintain control of the code by an individual as opposed to a group, to make it difficult for others to advance, and make it prone to requiring multiple changes in many modules to support it, then being for a more monolithic design will be supported. Since this is your "baby", PeterThoeny, I assume you will have to work to release your progeny to the world. There are other things that I want to do with the INCLUDE functionality, such as using LWP and page caching. It will be a bit more elegant to do so if I can replace an entire module rather than monkey around with the "core".
Supporting more "lard" as plugins vs. "lard" in core is not necessarily a good design decision. Functions that are very useful and are key to many uses of the system should be integrated into the "core", and not as ad-hoc plugin add-ons. Now, INCLUDE is not a plug-in, so I don't support making it one just to extend its functionality slightly. I am interested to see the concept used for variables in FormQueryPlugin, and the fact that a macro functionality is available there is news to me. That is one drawback to tons of lard as plugins in that you are not sure if they are 1) decent 2) useful 3) well documented and 4) in which plugin the functionality lies. I was told that SpreadSheetPlugin was the answer, but I beg to differ. The syntax and documentation of that plugin, is poor. I can spend only so long trying to figure how how to use it, and they don't span topic boundaries.
I assert that more work is needed on the definition of variables, and I have started an analysis of the situation in TopicObjectModel.
-- RaymondLutz - 10 Dec 2003
The discussion about modularisation has ranged far and wide, but the piece I recall making sense related to the incremental shift to an object model for the core. In my dreams I imagined this meant that the core would be lightened, and functionality moved into code/objects peripheral to the core. These peripheral objects/modules may be plugins.
Of course, in this model not all plugins are equal; some are more equal than others. Some plugins may be indistinguishable from the core to the end installer.
Think of it this way; that there is the TWiki core, a light, extremely fast, functional wiki implementation. Only what is absolutely needed is incorporated in the core (and we've survived without parameterised includes for some time now.... someone please point me at the killer app).
Around this core are ranged the "official plugins", shipped in the standard distribution and coded and supported to the same high standard.
Beyond that is what AndreaSterbini characterised as Dante's inferno - the Plugins web.
There's a bit of learning from TikiWiki here. When you install Tiki, you select the features you want to enable. As the feature set you use grows, performance suffers.
This feature enhancement is a lovely opportunity to demonstrate this model, because as I have shown, parameterised includes don't have to be implemented in the core of the core, but can be done using the existing plugins API. Sticking my neck out, I think everything you characterise as "Directives" in TopicObjectModel can be done this way.
-- CrawfordCurrie - 11 Dec 2003
I think you're preaching to the choir here, at least for me. I would be happy to see more modularization, and identifying minimal features as 'core'. But, I'm also a pragmatist, and I am trying to get sites to work. For the applications I usually encounter, the concerns about keeping an absolute minimal set of functions is not important, and in terms of processing speed, there are other ways to keep everything operating fast other than decreasing functionality. For a community project like TWiki, keeping things organized and partitioned cleanly is perhaps more important than worrying about smidget changes in performance. It turns out that INCLUDE is coded directly in the core module, i.e. TWiki.pm. This is wrong mostly because INCLUDE is simply one of the directives and one that many topics will never use. It should not be included in the core for both reasons:
Include.pm will allow dynamic loading if we want to do it, and as you mention, wholescale replacement by those (like me) who want to dramatically improve it and don't want to have to perform many patches to the "Kernel" to do so.
Include.pm if it addresses the first paragraph of my <rant> above
$quot $bla duplication in the code is reduced, reducing the mindset the user needs to carry with them and the idea behind using standard URL encoding makes testing of applications significantly easier. (It's not perfect granted)
Opinions offered in the hope they're useful - far from implementing in haste I had been thinking about parameterised includes for a month or two before initially mentioning the idea to Raymond. These might sounds like small differences, but the implications are quite large. If they not considered useful, please ignore - everyone has different needs. If anyone's interested in the patch for an implementation that avoids these issues, I can post it here.
-- MS - 19 Dec 2003
I think you make some good points, Michael. However, I think the use of URL encoding is not that great of a way to handle the problems you mention. Have you ever had to do this in any programming language? No.. it is just too much trouble to force this within a single programming environment where you have the luxury of passing more than just a single string variable. Personally I stand by the view that passing things as url encoded resolves enough problems for it to be useful - and makes like easier for the average user testing things out - since they can build a form front end, using a get method until they get something they want - which also simplifies generalised application testing..
Should it exclusively replace other things? Probably not. However the namespace issues need thinking about and syntactic measures to help prevent namespace clobbering make sense. URL encoding is just one method. Conventions break, often obligatorily so. -- MS - 05 Jan 2004
_thing,
_thing2 as thing and thing2 - the leading underscore creates you an implicit namespace.
-- MS - 12 Jan 2004
Raymond,
Whilst the params method I suggested is useful, yours definitely is as well. Mine might be easier for user testing, however in certain programmer friendly scenarios your approach is definitely easier. I stand by the namespace issues detailed above, and suggest that the syntax for your parameters to be passed through be the leading underscore approach. This could be suggested to indicate that the namespace for those parameters is private to the application.
Specific use for this: %INCLUDE{"%\FORMFIELD{'SomeField'}\%" section="%\FORMFIELD{'SomeOtherField'}\%" _user="%\FORMFIELD{'FirstName'}\%" _email="%\FORMFIELD{'EmailAddress'}\%"}%
SomeField in the section specified in SomeOtherField , the values of %PARAM{"user"}%, %PARAM{"email"}% would take the values specified in the form fields on the source topic.
Example relies upon NamedIncludeSections and FormattedTWikiFormDataInTopicText . (The latter needs to be modified to remove the rendering step) Clearly neither feature is in TWiki, but the examples hold - since there's other ways of achieving similar goals.
-- MS - 19 Jan 2004
I need this for work - So i'll probaly integrate it when it works for me
-- SvenDowideit - 12 May 2004
See MacrosPlugin for an implementation of parameterized includes.
-- CrawfordCurrie - 08 Jul 2004
I guess if I implement something I can dictate the syntax. And since I wrote MacrosPlugin I guess I have more experience with this sort of thing. So I'm going to implement this, and see what reaction we get. It's been sitting in the queue for far too long.
My preferred approach is to treat param values (both URLPARAMs and include parameters) equally, and treat them as implicit * Set operations. Of course, a mechanism is required to provide a default, but because default values are the exception rather than the rule, here's what I'm going to do:
In IncludedTopic
:
%UNLESS{"param" default="the default value"}%%param%
In IncludingTopic
%INCLUDE{"topic" param="Sausages"}%
%INCLUDE{"topic"}% -- in this case param will default to "the default value"
Big note %UNLESS does not mean the same as unless in perl, it means the same as #IFNDEF in cpp. Setting a null (or zero) value is not the same as not setting a value. The empty string is a valid value, and will not trigger UNLESS.
To rationalise the URLPARAM syntax, %urlparam% is synonymous with %URLPARAM{"urlparam"}%
%UNLESS{"urlparam" default="Chips"}%%urlparam% is synonymous with %URLPARAM{"urlparam" default="Chips"}%
%param% syntax is already supported by the CommentPlugin and the MacrosPlugin. The concept of using the parameters to the %INCLUDE tag as values in the included topic is already supported by the MacrosPlugin.
Further,
%UNLESS{"EDITBOXWIDTH" default="125"}%
can be used to provide a default value for a variable that would otherwise be * Set.
Obviously existing parameters to INCLUDE cannot be used as parameter names: pattern, rev and warn are therefore reserved names.
The CommentPlugin already supports a shorter syntax for parameter default values:
cols="%cols|3%"which specifies the default value "3" for the
cols parameters. However I don't like this, so I'm not going to implement it.
Support for this syntax would permit the retirement of the MacrosPlugin.
It may be possible to easily support this same syntax in the context of TWiki Templates:
%TMPL:DEF{"sausage"}%
%UNLESS{"message" default="mistake"}%Oops, you made a %message%
%TMPL:END%
%TMPL:P("sausage" message="mistake"}%
%TMPL:P{"sausage" message="bit of a mess"}%
The scoping rules are very simple: the closest enclosing definition is the only definition visible, and parameters always override automatic variables.
So if you were to say:
%INCLUDE{"OtherTopic" INCLUDINGTOPIC="Battenburg" DATE="Fruitcake"}%
then INCLUDINGTOPIC would be Battenburg (parameter overrides automatic variable INCLUDINGTOPIC) and DATE would be Fruitcake (parameter overrides static definition).
Of course you'd be rather silly to do this, but it's better to have rules.
Note that
%UNLESS{"MAINWEB" default="Main"}%
will never fire, because %MAINWEB% always has an value, provided by the system
Note also that parameter seetings will be appended to included URLs, so
%INCLUDE{"http://a.url.com//fleegle?param=floon" param="snot"}%
will expand to the url: http://a.url.com//fleegle?param=floon¶m=snot. The interpretation of this URL is up to HTTP.
If you really object to this spec, shout and we can talk about it.
-- CrawfordCurrie - 26 Oct 2004
i like smile
-- SvenDowideit - 26 Oct 2004
I like. In fact, I coded a very similiar thing in the TWikiReleaseTrackerPlugin. This allows overriding by a cgi parameter, then a parameter passed to a plugin, then a preference.
sub getParam {
my ( $inlineParamString, $paramName ) = @_;
my $ans = untaint( $cgiQuery->param($paramName) );
if ( $ans eq "" ) {
$ans = TWiki::Func::extractNameValuePair( $inlineParamString, $paramName );
}
if ( $ans eq "" ) {
$ans = TWiki::Prefs::getPreferencesValue("\U$pluginName\E_\U$paramName\E");
}
return $ans;
}
-- MartinCleaver - 26 Oct 2004
I like the Idea of parametrized includes. There is another feature to consider: ParameterizedVariables to include text of a (user defined) TWikiVariable with parameters.
-- StefanSteinegger - 04 Nov 2004
BTW: What about ParameterizedLinks? (This would all result in a complete TWiki parameterization :-).
-- StefanSteinegger - 09 Nov 2004
In the interests of consistency with ParameterizedVariables, here's a revised spec suitable for inclusion in documentation. The revision supports the idea of formal declaration of parameters, which I think is a good idea (thanks StefanSteinegger!). Note that the use of STARTINCLUDE is quite deliberate; I am anticipated NamedIncludeSections using the _DEFAULT parameter to %STARTINCLUDE to name the section at some point in the future.
Note also that this spec, when combined with ParameterizedVariables, is much cleaner than the current %TMPL mechanism and could be a drop-in replacement for that syntax as well.
%INCLUDEd topic can also be used to define a macro. A macro is a piece of text with placeholders. These placeholders are filled in with text you supply when the topic is included.
For example, you might write in the included topic:
My uncle's name is %name%, his age is %age%, and he's usually %mood%and then in the including topic:
%INCLUDE{"MyUncle" name="Fred" age="75" mood="introspective"}%
The named placeholders will be substituted when the including topic is viewed, so the %INCLUDE will expand to
My uncle's name is Fred, his age is 75, and he's usually introspectiveIn order to use named placeholders you have to declare them in the included topic. You do this using the %STARTINCLUDE% TWiki tag in the included topic.
%STARTINCLUDE{name="Aloysius" age="19" mood="bouyant"}%
My uncle's name is %name%, his age is %age%, and he's usually %mood%
%ENDINCLUDE%
The %STARTINCLUDE statement declares the names of the placeholders name, age and mood that can be set from the including topic, and their default values. If values for these placeholders are not given in the %INCLUDE statement, then the default values will be used i.e. =Aloysius for name, 19 for age, and buoyant for mood. For example:
%INCLUDE{"MyUncle" name="Solomon"}%
will expand to
<My uncle's name is Solomon, his age is 19, and he's usually buoyant.Note the use of lower case names for parameters to the include. This isn't compulsory, but it's a good idea to avoid conflicts with TWikiVariables . See also: Using variables as macros for another way to define macros, more suitable for smaller amounts of text. -- CrawfordCurrie - 09 Nov 2004 I need this sometime soon, so I'm proposing the above spec for Dakar. -- CrawfordCurrie - 15 Feb 2005 OK, the most basic implementation is in (i.e. PARAM="xxx" results in %PARAM% being defined in the inncluded topic) - Developbranch, r3661 -- CrawfordCurrie - 19 Feb 2005 Crawford, I think you should at least expand four parameters as this is what TWiki allows in other places (parameters passed through URL). I don't know what is special about four, but let's be consistent at least.... By the way, in my own installation I have patched
lib/TWiki/UI/View.pm as follows to take in parameters also, as I often want to call pages with some parameters substituted...
Index: lib/TWiki/UI/View.pm
===================================================================
RCS file: /e/www/CVS/twiki-cairo/lib/TWiki/UI/View.pm,v
retrieving revision 1.1
diff -c -r1.1 View.pm
*** lib/TWiki/UI/View.pm 7 Sep 2004 17:16:58 -0000 1.1
--- lib/TWiki/UI/View.pm 19 Feb 2005 22:38:45 -0000
***************
*** 153,158 ****
--- 153,179 ----
TWiki::UI::writeDebugTimes( "view - get rev info" );
if( ! $viewRaw ) {
+ # Substitute for parameters that have been passed in.
+ # For performance reasons, do not remove parameter references
+ # when no parameter was passed, as with
+ # $param = $query->param( 'param1' ) || "";
+ # $text =~ s/%PARAM1%/$param/go;
+ # etc.
+
+ my $param;
+ if ( defined ($param = $query->param( 'param1' )) ) {
+ $text =~ s/%PARAM1%/$param/go;
+ }
+ if ( defined ($param = $query->param( 'param2' )) ) {
+ $text =~ s/%PARAM2%/$param/go;
+ }
+ if ( defined ($param = $query->param( 'param3' )) ) {
+ $text =~ s/%PARAM3%/$param/go;
+ }
+ if ( defined ($param = $query->param( 'param4' )) ) {
+ $text =~ s/%PARAM4%/$param/go;
+ }
+
$text = &TWiki::handleCommonTags( $text, $topic );
TWiki::UI::writeDebugTimes( "view - handleCommonTags done" );
$text = &TWiki::Render::getRenderedVersion( $text );
Note that this text would leave the %PARAMx% string in the topic if no parameter was passed, i.e., the assumption is that the user passes all arguments (I need to test performance to see whether this really matters).
-- ThomasWeigert - 19 Feb 2005
Sorry, I was clearer in the documentation:
%INCLUDE{"page" ...}%
| Parameter: | Description: | Default: |
|---|---|---|
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"TWiki06x01.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}% Note if the URL resolves to an attachment file on the server this will automatically translate to a server-side include. | |
pattern="..." | A RegularExpression pattern to include a subset of a topic or page | none |
rev="1.2" | Include a previous topic revision; N/A for URLs | top revision |
warn="off" | Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) | %INCLUDE- WARNING% preferences setting |
%INCLUDE{"AnotherTopic" PONE="val 1" PTWO="val 2"}%
will result in %PONE% and %PTWO% being defined within the included topic.
| ChangeProposalForm | |
|---|---|
| TopicClassification | FeatureRequest |
| TopicSummary | Allow topic INCLUDEs to pass parameters to the included topics |
| CurrentState | MergedToCore |
| CommittedDeveloper | |
| ReasonForDecision | None |
| DateOfCommitment | |
| ConcernRaisedBy | |
| BugTracking | |
| OutstandingIssues | |
| RelatedTopics | TWikiVariables, EncodeParamsForFormFields ParameterizedLinks |
| InterestedParties | RaymondLutz, PeterThoeny, WillNorris, StefanSteinegger |
| ProposedFor | DakarRelease |
| TWikiContributors | CrawfordCurrie |