version=pmwiki-2.2.2 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.0.11) Gecko/2009060215 Firefox/3.0.11
author=HansB
charset=ISO-8859-1
csum=added section about using conditionals
host=80.41.216.53
name=PmWiki.IncludeOtherPages
rev=103
targets=PmWiki.Links,PmWiki.WikiGroup,PmWiki.PageTextVariables,PmWiki.ConditionalMarkup,PmWiki.PageVariables,Site.PageListTemplates,PmWiki.WikiStyles,PmWiki.WikiAdministrator,PmWiki.PageLists
text=(:Summary: Include contents from other PmWiki pages:)%0a(:Audience: authors (intermediate) :)%0aThe [@(:include:)@] directive makes it possible to insert (or [[Wikipedia:Transclusion|"transclude"]]) the contents of other pages into the current wiki page.  All of the include directives below perform a straight text inclusion.  In particular, any page [[links]] in the included text are assumed to link to pages in the current [[(wiki) group]] if not otherwise qualified.%0a%0a!! Syntax%0aThe basic syntax is%0a* [=(:=]include PageName:)%0a-> with pagename includes the full page from the same group.%0a* [={Group/PageName$:=][[#includeptv|PTVar]]}%0a-> includes a [[PageTextVariables|named variable]] from a page, [[(Wiki)Group]] and PageName are options%0a%0aThe full syntax is%0a* [=(:=]include%0a  [[#includefullname|FullName]]#[[#includeanchor|fromanchor]]#[[#includeanchor|toanchor]] \%0a  [[#includelines|lines]]=''123'' \%0a  [[#includeself|self]]=''0''  \%0a  [[#includebasepage|basepage]]=''abc'' \%0a  [[#includevariable|variable]]=''value'' \%0a  :)%0a-> includes a page or pages according to the parameters supplied. Parameters are optional.%0a[[#firstanchor]]%0a%0a%0a!! Use with [[conditional markup]]%0aThe [@(:include ...:)@] markup is processed after conditional markup is evaluated.\\%0aTherefor you can include a page or page section as part of a condition, like%0a->[@(:if some condition:)(:include SomePage#section:)(:if:) @] %0aBut [@(:include SomePage#section:)@] doesn't look to see if [@[[#section]]@] is part of a conditional, like %0a->[@(:if some condition:)[[#section]]...[[#sectionend]](:ifend:)@]%0a[@(:include SomePage#section:)@] will ignore such a condition. %0a%0aWhen [[Conditional Markup|testing variables]] in included pages the context of the page (source or target) can be useful.%0aSee [[PmWiki/PageVariables|special references]] for details.%0a%0a%0a!! Parameters%0aName parameters with or without anchors, and [[#includevariable| variable]] parameters, may be repeated.%0a%0a[[#includefullname]]%0a!!! Named pages%0a-%3c [@(:include PageName:)@]%0a-%3c [@(:include Group.PageName:)@]%0a-%3c [@(:include PageName GroupName.Pagename:)@]%0a-> Includes the entire text of another page into the current page.  Multiple pages may be specified, but only the first available is included.%0a%0a[[#includeanchor]]%0a!!! Anchors%0a|| width=*%0a||[@(:include PageName#from#to:)@] ||include lines from ''`PageName'' between the [@[[#from]]@] and [@[[#to]]@] [[Links#anchors|anchors]]%0a||[@(:include PageName#from#:)@]   ||include all lines after [@[[#from]]@] to the end of the page%0a||[@(:include PageName##to:)@]     ||include all lines from the start of the page to [@[[#to]]@]%0a||[@(:include PageName#from:)@]    ||include everything between [@[[#from]]@] and the next anchor%0a||[@(:include PageName#:)@]        ||include everything from the top of the page to the first anchor%0a||[@(:include PageName##:)@]       ||include everything from the top of the page to the bottom of the page%0a-> %25note%25 Note: do not put whitespace between "#from" "#to"%0a%0a-> %25note%25 Note: text on the same line as a closing anchor but preceding the closing anchor will '''NOT''' be included in the text.  Example Below:%0a--> [@[[#start]]some text on the first line@]%0a--> [@some text on the last line [[#end]]@]%0a-> %25note%25The above, when included via [@(:include PageName#start:)@] will have the text on the first line but not the text on the last line.%0a%0a-%3c [@(:include Page1 Page2 #from#to:)@]%0a-> Include from the first available of Page1, Page2 between the [@[[#from]]@] and [@[[#to]]@]  %0a-> %25note%25 Note: put whitespace between "Page2" and "#from#to". The same anchors "#from#to" should be in both pages. If proper anchors are missing in the first available of Page1, Page2 the whole contents of the page is included.%0a-> This does not seem to work in 2.2 betas. See Cookbook:IncludeSection for a fix.%0a%0a-%3c [@(:include Page1#from1#to1 Page2#from2#to2:)@]%0a-> Include the first from the first available of Page1 (between the [@[[#from1]]@] and [@[[#to1]]@]) or Page2 (between the [@[[#from2]]@] and [@[[#to2]]@] ) %0a%0a-%3c %25green%25Note%25%25: Previous versions of PmWiki allowed whitespace between [@#from@] and [@#to@] anchors even though it was not designed to.  Newer versions do not allow whitespace anymore.  To re-enable this "exploited misbehavior" put this into your config.php or farmconfig.php%0a%0a-> [@Markup('includeanchors', '%3cinclude', '/(\\(:include.*?#\\w+)\\s+(#\\w+)/', '$1$2');@]%0a%0a[[#includelines]]%0a!!! Lines=%0a-%3c [@(:include PageName lines=10:)@]%0a-%3c [@(:include PageName lines=5..10:)@]%0a-%3c [@(:include PageName lines=5..:)@]%0a-> Include the first 10 lines, lines 5-10, or lines 5 and up from ''`PageName''. A "line" in this context refers to a line of source. ''Thus a line may be a paragraph that wraps over several lines on the screen, or a completely blank line.''%0a%0a-%3c [@(:include Page1 Page2 Page3 lines=1..5:)@]%0a-> Include the first five lines from the first available of Page1, Page2, or Page3.  (To include lines from a list of pages, use a separate include for each.)%0a%0a[[#includeself]]%0a!!! Self=%0a-%3c [@(:include PageName self=0:)@]%0a-> The parameter @@self@@ can be @@0@@ or @@1@@. It tells the include directive if it is allowed to include the current page. This is useful if PageName is a variable like [@{$Name}@] and you want to prevent the directive from including the current page.%0a%0a[[#includeptv]]%0a!!! [[Page text variables]]%0a-%3c [@{Group/PageName$:Var}@]%0a-> Includes definition list values from an (optional) page as [[page text variables]]. These are defined using a definition list ([@:item:description@]), simple colon delimiter ([@item:description@]), or special markup ([@(:item:description:)@]).%0a%0a[[#includebasepage]]%0a!!!  Basepage=%0a%0a-%3c [@(:include PageName basepage=BasePageName:)@]%0a-> Include PageName, but treat all relative links and page variables on ''PageName`'' as relative to ''BasePageName''.%0aIf @@basepage=@@ is provided all relative links and page variables are interpreted relative %0ato basepage.%0aSo, if one creates [@TemplateName@] as%0a-> [@Name: {$:Name}%0aAddress: {$:Address}@]%0athen the directive%0a-> [@(:include TemplateName basepage=PageName:)@]%0awill retrieve the contents of [@TemplateName@], treating any page variables and links as being relative to [@PageName@].  %0aIn particular, the values for [@{$:Name}@] and [@{$:Address}@] will be taken from [@PageName@], but things like [@{$Title}@] and [@{$LastModifiedBy}@] would also work here.%0a%0a!!!! Basepage usage%0aThe primary purpose of basepage is to allow the include of pages in a way that mimics the 2.1.x behavior where page variables %0aand links are interpreted relative to the currently displayed page.%0aThis is done with:%0a-> [@(:include SomeOtherPage basepage='' :)@]%0a  -or-%0a-> [@(:include SomeOtherPage basepage={*$FullName} :)@]%0a%0aIt also allows [=GroupHeader and GroupFooter=] to have their page variables and links be relative to the currently displayed page %0a(instead of [=GroupHeader and GroupFooter=]):%0a>>pre%3c%3c%0a  ## PmWiki default $GroupHeaderFmt setting%0a  $GroupHeaderFmt = %0a    [='(:include {$Group}.GroupHeader self=0 basepage={*$FullName}:)(:nl:)';=]%0a>>%3c%3c%0a%0aOtherwise, using {$Name} inside of a [=GroupHeader=] would display '[=GroupHeader=]' and not the name of the currently displayed page.%0a%0aAs has been discovered, the basepage= parameter is general enough that it can also be used as a templating engine, so that%0awe can grab a template page containing variables that are then filled in with values from another page:%0a->[@(:include TemplatePage basepage=DataPage :)@]%0a%0aAnd, of course, a single TemplatePage can actually contain multiple templates delimited by anchors, so that we end up with a syntax eerily similar'^[[#footnote|#]]^' to pagelist-templates:%0a>>pre%3c%3c%0a    [@(:include TemplatePage#abc basepage=DataPage :)@]%0a    (:include TemplatePage#def basepage=DataPage :)%0a    (:include TemplatePage#xyz basepage=DataPage :)%0a>>%3c%3c%0a%0aSo then [=TemplatePage=] can use a syntax like:%0a>>pre%3c%3c%0a    [@%0a    [[#abc]]%0a    ...template stuff here...%0a    [[#abcend]]%0a    @]%0a>>%3c%3c%0a%0aand it's possible to display [=TemplatePage=] as a template without it being interpreted... same as we do for [[Site.PageListTemplates]].%0a%0a%0a-%3c [[#footnote]] [- '^[1]^'Okay, maybe it's not so eerie, given that the pagelist template code actually uses the same function as (:include:) to grab its templates.  But it's still a useful parallel. -]%0a%0a[[#includevariable]]%0a!!! Specifying variables as parameters%0aYou can also specify variable values inline with the include statement, and refer to the variables in the template using the [@{$$variable1}@] format:%0a-> [@(:include TemplatePage variable1="value" variable2="value2":)@]%0a%0aThis assumes that a site has $EnableRelativePageVars enabled, which is recommended in PmWiki 2.2.0 -- but disabled by default to help people upgrading from 2.1.x.%0a%0aFor example, on my included page ("template") I might have this:%0a%0a(:markup class=horiz:)%0a[[#ivars]]%0aHi, {$$Name}, how are you today?%0a[[#ivarsend]]%0a(:markupend:)%0a%0aThen, including that section above (that section is available via the section @@[@{$FullName}#ivars)@]@@) you get this type of behavior:%0a%0a(:markup class=horiz:)%0a(:include {$FullName}#ivars Name=Sam:)%0a(:markupend:)%0a%0a(:markup class=horiz:)%0a(:include {$FullName}#ivars Name=Sally:)%0a(:markupend:)%0a%0a!! See Also%0a* [[PmWiki/Page text variables]] {PmWiki/PageTextVariables$:Summary}%0a* [[Cookbook:IncludeUrl]] {Cookbook.IncludeUrl$:Summary}%0a%0a!! Styling Note%0aBy default, Included pages or lines cannot be distinguished from other text on the page. To provide a visual indication that this text is special, you can apply [[PmWiki/Wiki Styles]]. For example:%0a%0a(:markup:)%0a%25define=leftborder border-left="2px solid #88f" margin-left="2px" padding="1px 0 3px 10px"%25%0aWhat is PmWiki?%0a>>leftborder%3c%3c (:include PmWiki.PmWiki lines=1..4:) %0a>>%3c%3c%0a''Have a very nice day!''%0a(:markupend:)%0a%0a!!! Parameter References%0a%0aAny parameters supplied to an include statement (whether they are keywords or not) are accessible inside the included page as a special [@{$$...}@] variable of the same name. This feature can be used to provide extra information to use when displaying the included page.%0a%0a!!! Notes%0a* You can also say [@(:include My/Page#myanchor lines=4:)@] which starts from, and includes, the line with the anchor [@[[#myanchor]]@] for four lines.%0a%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: [[#maxincludes]] What's the maximum number of includes that can exist in a page? %0a-> My site seems to stop including after 48 includes. ($MaxIncludes)%0a%0aA: By default, PmWiki places a limit of 50 include directives for any given page, to prevent runaway infinite loops and other situations that might eat up server resources. (Two of these are GroupHeader and GroupFooter.) The limit can be modified by the [[wiki administrator]] via the $MaxIncludes variable.%0a%0aQ: Is there any way to include from a group of pages without specifying by exact name, e.g. between Anchor X and Y from all pages named IFClass-* ?%0aA: This can be achieved using [[page lists]].%0a%0a%0aQ: There appears to be a viewing issue when the included page contains the [=(:title:)=] directive.%0aA: As of version 2.2.0, the ''last'' title in the page overrides previous ones. In future versions, this may be configurable, but for the moment, best is to place your [=(:title :)=] directive at the bottom of the page, after any includes.%0a
time=1247252067