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 a 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.

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:

Warning

This site does not allow %INCLUDE% of URLs

4. 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.

5. 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% </b></td>
</tr>
<tr bgcolor="#FFCC66">
<td>&nbsp;</td>
<td> %MESSAGE% </td>
</tr>
</table>
</div>
%STOPINCLUDE%
-----

Now you can write %INCLUDE{ "AlertBox" TITLE="Alert" MESSAGE="This a test message" }% to get this:

	Alert
	This a test message

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.

6. Create a Widget Library

You can create a library of GUI widgets using a topic with named sections:

1. Create a Main.WidgetLibrary topic
2. 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%)
3. 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, UserDocumentationCategory

-- Contributors: TWiki:Main/PeterThoeny, TWiki:Main/KennethLavrsen