NOTE: This is a
DistributionDocument.
- Please help maintain high quality documentation:
This is a wiki, please
fix the documentation if you find errors or incomplete content.
Put questions and suggestions concerning the documentation of this topic in the comments section below.
Use the Support web for problems you are having using TWiki.
Use the Sandbox web to evaluate & test TWiki.
Include Topics and Web Pages Using %INCLUDE{...}%
Variable
Use the
%INCLUDE{...}%
variable to embed the content of another topic or web page inside a TWiki topic. The whole content or only parts of a page can be included. If needed, set a proxy server in
TWikiPreferences.
Syntax Example
%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" PARAMETER1="value" PARAMETER2="Some value"}%
The
pattern
parameter is optional and allows you to extract some parts of a web page. Specify a
RegularExpression that scans from start (
'^'
) to end and contains the text you want to keep in parenthesis, e.g.,
pattern="^.*?(from here.*?to here).*"
. You need to make sure that the integrity of a web page is not compromised; for example, if you include an HTML table, make sure to include everything including the table end tag.
The example parameters PARAMETER1 and PARAMETER2 will be defined as a variable within the scope of the included topic. The example parameters shown will result in %PARAMETER1% and %PARAMETER2% being defined within the included topic. A default value can be specified such as %PARAMETER1{ default="..." }% in case the INCLUDE does not specify the parameter. Parametrized includes can be used to define and use macros, which is an alternative to
parameterized variables.
VarINCLUDE explains the other parameters.
Note: All text of a topic is included unless it contains a
%STARTINCLUDE%
and
%STOPINCLUDE%
, or you specify a
section
parameter and/or a
pattern
parameter. A pattern will only search between
%STARTINCLUDE%
and
%STOPINCLUDE%
.
Usage Examples
1. Display regression test results in a TWiki page
<pre>
%INCLUDE{"http://domain/~qa/v1.1/REDTest.log.txt"}%
</pre>
2. Display Google's robot.txt file
%INCLUDE{"http://www.google.com/robots.txt"}%
3. Display the current time in Tokyo in a TWiki page
- You type:
-
Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%
- You get:
- Tokyo: Sat, 24 Feb 2024 00:24:43 +0900 (JST)
4. Create a big document of many included topics
If you create a big document (such as a manual or book) it is better to split up content into topics. You can do that by chapter or sub-section. If needed you can adjust the heading level when you include the chapters into the master document. For example, in the master document you might want to show chapter's H1 heading as H2. Example:
---+!! Breadslicer Users Guide
%TOC{ depth="3" }%
%INCLUDE{ "UsersGuidePreface" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter1" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter2" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter3" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter4" headingoffset="1" }%
%INCLUDE{ "UsersGuideAppendix" headingoffset="1" }%
%INCLUDE{ "UsersGuideIndex" headingoffset="1" }%
5. Include a topic MyTopic with two parameters
You include the topic with this line
%INCLUDE{ "MyTopic" BETTER="apples" WORSE="Oranges"}%
An example of a very simple MyTopic could contain
* I like %BETTER% better than %WORSE%.
The result would be
- I like apples better than oranges.
Tip: Parameterized variables are a somewhat easier to use alternative to parametrized includes.
6. Alert Box using Parameterized Include
Create a topic called AlertBox with the following content:
-----
%STARTINCLUDE%
<div style="border-color:#FF9933; border-style:solid; border-width:thin; width:85%; margin: 0 auto">
<table cellpadding="5" width="100%" cellspacing="0" cellpadding="12" border="0">
<tr bgcolor="#FFBB55">
<td valign="top" width="16"><img src="%ICONURL{warning}%" width="16" height="16" align="absmiddle" alt="" border="0"></td>
<td><b> %TITLE{ default="Alert!" }% </b></td>
</tr>
<tr bgcolor="#FFCC66">
<td> </td>
<td> %MESSAGE{ default="Please specify a MESSAGE parameter." }% </td>
</tr>
</table>
</div>
%STOPINCLUDE%
-----
Now you can write
%INCLUDE{ "AlertBox" TITLE="Alert" MESSAGE="This a test message" }%
to get this:
Include Topics and Web Pages Using %INCLUDE{...}%
Variable
Use the
%INCLUDE{...}%
variable to embed the content of another topic or web page inside a TWiki topic. The whole content or only parts of a page can be included. If needed, set a proxy server in
TWikiPreferences.
Syntax Example
%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" PARAMETER1="value" PARAMETER2="Some value"}%
The
pattern
parameter is optional and allows you to extract some parts of a web page. Specify a
RegularExpression that scans from start (
'^'
) to end and contains the text you want to keep in parenthesis, e.g.,
pattern="^.*?(from here.*?to here).*"
. You need to make sure that the integrity of a web page is not compromised; for example, if you include an HTML table, make sure to include everything including the table end tag.
The example parameters PARAMETER1 and PARAMETER2 will be defined as a variable within the scope of the included topic. The example parameters shown will result in %PARAMETER1% and %PARAMETER2% being defined within the included topic. A default value can be specified such as %PARAMETER1{ default="..." }% in case the INCLUDE does not specify the parameter. Parametrized includes can be used to define and use macros, which is an alternative to
parameterized variables.
VarINCLUDE explains the other parameters.
Note: All text of a topic is included unless it contains a
%STARTINCLUDE%
and
%STOPINCLUDE%
, or you specify a
section
parameter and/or a
pattern
parameter. A pattern will only search between
%STARTINCLUDE%
and
%STOPINCLUDE%
.
Usage Examples
1. Display regression test results in a TWiki page
<pre>
%INCLUDE{"http://domain/~qa/v1.1/REDTest.log.txt"}%
</pre>
2. Display Google's robot.txt file
%INCLUDE{"http://www.google.com/robots.txt"}%
3. Display the current time in Tokyo in a TWiki page
- You type:
-
Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%
- You get:
- Tokyo: Sat, 24 Feb 2024 00:24:43 +0900 (JST)
4. Create a big document of many included topics
If you create a big document (such as a manual or book) it is better to split up content into topics. You can do that by chapter or sub-section. If needed you can adjust the heading level when you include the chapters into the master document. For example, in the master document you might want to show chapter's H1 heading as H2. Example:
---+!! Breadslicer Users Guide
%INCLUDE{ "UsersGuidePreface" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter1" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter2" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter3" headingoffset="1" }%
%INCLUDE{ "UsersGuideChapter4" headingoffset="1" }%
%INCLUDE{ "UsersGuideAppendix" headingoffset="1" }%
%INCLUDE{ "UsersGuideIndex" headingoffset="1" }%
5. Include a topic MyTopic with two parameters
You include the topic with this line
%INCLUDE{ "MyTopic" BETTER="apples" WORSE="Oranges"}%
An example of a very simple MyTopic could contain
* I like %BETTER% better than %WORSE%.
The result would be
- I like apples better than oranges.
Tip: Parameterized variables are a somewhat easier to use alternative to parametrized includes.
6. Alert Box using Parameterized Include
Create a topic called AlertBox with the following content:
-----
%STARTINCLUDE%
<div style="border-color:#FF9933; border-style:solid; border-width:thin; width:85%; margin: 0 auto">
<table cellpadding="5" width="100%" cellspacing="0" cellpadding="12" border="0">
<tr bgcolor="#FFBB55">
<td valign="top" width="16"><img src="%ICONURL{warning}%" width="16" height="16" align="absmiddle" alt="" border="0"></td>
<td><b> %TITLE{ default="Alert!" }% </b></td>
</tr>
<tr bgcolor="#FFCC66">
<td> </td>
<td> %MESSAGE{ default="Please specify a MESSAGE parameter." }% </td>
</tr>
</table>
</div>
The
TITLE=""
and
MESSAGE=""
parameters are passed into the include. Using this approach, you can create a library of boxes in the Main web, such as Main.NoteBox, Main.InfoBox.
7. Create a Widget Library
You can create a library of
GUI widgets using a topic with named sections:
- Create a Main.WidgetLibrary topic
- Create widgets in that topic, such as alert boxes, submit forms, queries, etc. Widgets are defined as named sections and may process parameters. For example, above alert box can be a widget enclosed in
%STARTSECTION{AlertBox}%
... %ENDSECTION{AlertBox}%
(instead of the %STOPINCLUDE%
... %STOPINCLUDE%
)
- Place a widget in any topic. For example, to use the alert box widget write:
%INCLUDE{ "Main.WidgetLibrary" section="AlertBox" TITLE="Alert" MESSAGE="The sky is the limit!" }%
In essence, you are building a library of functions with parameters that people can use. Use your imagination, the sky is the limit!
Related Topics: VarINCLUDE,
VarSTARTSECTION,
VarENDSECTION,
IncludeTopicRaw,
UserDocumentationCategory,
ParameterizedVariables
--
Contributors: TWiki:Main.PeterThoeny,
TWiki:Main.KennethLavrsen
Comments & Questions about this Distribution Document Topic
Yahoo! seems to be blocking connections from TWiki.org. Also, they modified their weather page, adding extra junk around the temerature in order to throw off the pattern. I changed the pattern to one that works now, however it doesn't work on this site. Perhaps it would be best to scrap the Yahoo! examples, and use
http://www.nws.noaa.gov/ instead, as suggested in the comment at the top of the weather page.
--
ChristopherRued - 15 Jul 2004
Limitations of INCLUDE
At the moment %INCLUDE% can only inline content from
http:
URLs. The
https:
protocol is currently not supported. The exception of the rule is the case, where the given https: URL can be translated to a TWiki pub URL (in this case, the URL will be translated into a local path f for server side inclusion).
If you are interested in
https:
support of %INCLUDE%, please see the
IncludeUrlWithHttpsProtocol feature request and provide ideas, code/patches and/or test willingness.
Background: HTTPS makes a lot of sence, even in an intranet scenario, because always if you have to transfer passwords with HTTP, you will want send them encrypted, so HTTPS is the only browser compatible solution.
--
TobiasRoeser - 15 Feb 2006
Does INCLUDE use another user to include a topic? I ask because I have a username which is given permission to view a topic and can successfully do so but when that topic is included in another, the INCLUDE throws a "No permission to view" message in place of the expected content. Other users may view both the topic and the include and including the text using a bookview Formatted search also works.
--
SethTownsend - 16 Mar 2006
Guest user is used if you include a TWiki topic as a URL; authenticated user is used if you include a Web.TopicName.
--
PeterThoeny - 16 Mar 2006
Does INCLUDE do its view access check against the included Topic Preferences or the Web Preferences for that user?
--
SethTownsend - 16 Mar 2006
Check is against the permission on the included topic when including a Web.TopicName. Please ask support questions in the
Support web.
--
PeterThoeny - 16 Mar 2006
Is there functionality for using Include inside a table cell? I can't seem to find anything to suggest one way or the other. Is it just not possible?
--
JamesKnevitt - 25 Jul 2006
You can, but only if the included text has no newlines. Newlines break TWiki tables apart.
--
PeterThoeny - 25 Jul 2006
I have a couple problems which are resulting in me not being able to %INCLUDE% a FORM page. First if I do an INCLUDE with the Web.topic (form applied) I only get the content NOT in the form which in my case is nothing but the signiture
" --CraigTobias - 10 Jul 2006 " (all information is in the form). If I try to use the full URL which I believe will solve the problem I can't pass credentials because LDAP authentication is used and in my case there are no Guest users. The
TwikiGuest is still in the userlist but since everyone must login with LDAP first it is not possible to be
TwikiGuest. If I needed this for one or two pages it wouldn't matter I would figure something else out. However, I plan on using this (INCLUDE) for product and technology support pages: 100s of pages. Any ideas?
--
CraigTobias - 10 Sep 2006
Please ask support questions in the
Support web.
--
PeterThoeny - 11 Sep 2006
The documentation should say that 'Set' does not work in an included topic, not even for references that occur within the same included topic. An explanation of why this is so might be nice but should not hold up adding the simple statement that it does not work.
It would also be a good idea to say something about %IF in the included topic; my reading of bug reports suggests that it is textually substituted and so eventually evaluated in the context of the base topic. One obvious catch is that if you use the '$' operator in the condition to obtain the value of TOPIC you get the base topic, not the included topic as the value.
--
OwenRees - 31 Jul 2008
--
MoustafaNabil - 2011-10-13
I would like to add the ability to use variables in the URL of INCLUDE.
For example, if I have a variable called STATUS_DATE that is set to the value "111009", then I would like to include a page similar to this URL:
%INCLUDE{"http://engweb.intr.com/~moustafa/%STATUS_DATE%StatusPage.twiki"}%
which resolves to the path:
http://engweb.intr.com/~moustafa/111009StatusPage.twiki
Currently when I do something like that, I got the following message:
Failed to include URL <url path> Bad Request
--
MoustafaNabil - 2011-10-13
This is a cross-post handled in
Support.SID-01294. This comment section is about the
documentation of this topic, not support.
--
PeterThoeny - 2011-10-13
Note: This comment box is for questions and suggestions concerning the
documentation of this topic. Please use the
Support web for problems you are having
using TWiki.