Tags:
create new tag
view all tags
ALERT! 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 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>&nbsp;</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 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>&nbsp;</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:

  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, 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

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.

ALERT! 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.
Edit | Attach | Watch | Print version | History: r48 < r47 < r46 < r45 < r44 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r48 - 2014-12-16 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.