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.

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" }%

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.

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: Wed, 08 Oct 2008 13:34:09 +0900 (JST)

Related Topics: VarINCLUDE, UserDocumentationCategory

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

Warning: Can't find topic ""."" 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

Warning: Can't find topic ""."" , 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