head	1.13;
access;
symbols;
locks; strict;
comment	@# @;


1.13
date	2011.04.14.08.21.22;	author TWikiContributor;	state Exp;
branches;
next	1.12;

1.12
date	2010.05.29.14.44.55;	author TWikiContributor;	state Exp;
branches;
next	1.11;

1.11
date	2009.03.30.09.18.22;	author TWikiContributor;	state Exp;
branches;
next	1.10;

1.10
date	2008.01.22.03.21.31;	author TWikiContributor;	state Exp;
branches;
next	1.9;

1.9
date	2006.04.01.05.55.07;	author TWikiContributor;	state Exp;
branches;
next	1.8;

1.8
date	2006.02.01.12.01.17;	author TWikiContributor;	state Exp;
branches;
next	1.7;

1.7
date	2004.08.15.07.36.37;	author PeterThoeny;	state Exp;
branches;
next	1.6;

1.6
date	2003.02.01.12.26.52;	author PeterThoeny;	state Exp;
branches;
next	1.5;

1.5
date	2003.01.16.07.35.00;	author PeterThoeny;	state Exp;
branches;
next	1.4;

1.4
date	2002.12.11.08.18.06;	author PeterThoeny;	state Exp;
branches;
next	1.3;

1.3
date	2002.11.14.03.12.00;	author PeterThoeny;	state Exp;
branches;
next	1.2;

1.2
date	2002.04.07.10.26.00;	author PeterThoeny;	state Exp;
branches;
next	1.1;

1.1
date	2001.06.26.00.44.57;	author PeterThoeny;	state Exp;
branches;
next	;


desc
@none
@


1.13
log
@buildrelease
@
text
@%META:TOPICINFO{author="TWikiContributor" date="1302769282" format="1.1" version="13"}%
---+!! Include Topics and Web Pages Using =%<nop>INCLUDE{...}%= Variable

Use the =%<nop>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 %WIKIPREFSTOPIC%.

%TOC%

---++ Syntax Example

=%<nop>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 %SYSTEMWEB%.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 %<nop>PARAMETER1% and %<nop>PARAMETER2% being defined within the included topic. A default value can be specified such as %<nop>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 [[ParameterizedVariables][parameterized variables]].

VarINCLUDE explains the other parameters.

__Note:__ All text of a topic is included unless it contains a =%<nop>STARTINCLUDE%= and =%<nop>STOPINCLUDE%=, or you specify a =section= parameter and/or a =pattern= parameter. A pattern will only search between =%<nop>STARTINCLUDE%= and =%<nop>STOPINCLUDE%=.

---++ Usage Examples

---+++ 1. Display regression test results in a TWiki page
<pre>
  &lt;pre&gt;
  %<nop>INCLUDE{"http://domain/~qa/v1.1/REDTest.log.txt"}%
  &lt;/pre&gt;
</pre>

---+++ 2. Display Google's robot.txt file

<pre>
  %<nop>INCLUDE{"http://www.google.com/robots.txt"}%
</pre>

---+++ 3. Display the current time in Tokyo in a TWiki page

   * You type:
      * ==Tokyo: %<nop>INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*&lt;\!--tzdate:date--&gt;(.*?)&lt;\!--/tzdate:date--&gt;.*"}%==
   * You get:
      * Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%

---+++ 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:

<verbatim>
  ---+!! 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" }%
</verbatim>

---+++ 5. Include a topic !MyTopic with two parameters

You include the topic with this line
<verbatim>
  %INCLUDE{ "MyTopic" BETTER="apples" WORSE="Oranges"}%
</verbatim>

An example of a very simple !MyTopic could contain

<verbatim>
   * I like %BETTER% better than %WORSE%.
</verbatim> 

The result would be

   * I like apples better than oranges.

%T% __Tip:__ [[ParameterizedVariables][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:

<verbatim>
-----
%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%
-----
</verbatim>

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

%INCLUDE{ "%TOPIC%" TITLE="Alert" MESSAGE="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 %USERSWEB% web, such as <nop>%USERSWEB%.NoteBox, <nop>%USERSWEB%.InfoBox.

---+++ 7. Create a Widget Library

You can create a library of [[http://en.wikipedia.org/wiki/GUI_widget][GUI widgets]] using a topic with named sections:

   1. Create a <nop>%USERSWEB%.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 =%<nop>STARTSECTION{AlertBox}%= ... =%<nop>ENDSECTION{AlertBox}%= (instead of the =%<nop>STOPINCLUDE%= ... =%<nop>STOPINCLUDE%=)
   3. Place a widget in any topic. For example, to use the alert box widget write:%BR% =%<nop>INCLUDE{ "%USERSWEB%.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, ParameterizedVariables

-- __Contributors:__ TWiki:Main.PeterThoeny, TWiki:Main.KennethLavrsen
@


1.12
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1273005047" format="1.1" version="12"}%
d12 1
a12 1
The =pattern= parameter is optional and allows you to extract some parts of a web page. Specify a %SYSTEMWEB%.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.
d14 1
a14 1
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.
d42 17
a58 1
---+++ 4. Include a topic !MyTopic with two parameters
d75 3
a77 1
---+++ 5. Alert Box using Parameterized Include
d88 1
a88 1
<td><b> %TITLE% </b></td>
d92 1
a92 1
<td> %MESSAGE% </td>
d106 1
a106 1
---+++ 6. Create a Widget Library
d110 1
a110 1
   1. Create a !Main.WidgetLibrary topic
d112 1
a112 1
   3. Place a widget in any topic. For example, to use the alert box widget write:%BR% =%<nop>INCLUDE{ "Main.WidgetLibrary" section="AlertBox" TITLE="Alert" MESSAGE="The sky is the limit!" }%=
d116 1
a116 1
__Related Topics:__ VarINCLUDE, VarSTARTSECTION, VarENDSECTION, UserDocumentationCategory
d118 1
a118 1
-- __Contributors:__ TWiki:Main/PeterThoeny, TWiki:Main/KennethLavrsen
@


1.11
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1236757609" format="1.1" version="11"}%
d88 13
a100 1
__Related Topics:__ VarINCLUDE, UserDocumentationCategory
@


1.10
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="10"}%
d59 29
a88 1

@


1.9
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="9"}%
d10 1
a10 1
=%<nop>INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" }%=
d12 3
a14 1
The =pattern= parameter is optional and allows you to extract some parts of a web page. Specify a %TWIKIWEB%.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.
d42 17
@


1.8
log
@buildrelease
@
text
@d1 1
a1 1
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="8"}%
d14 1
a14 1
TWikiVariables#VarINCLUDE explains the other parameters.
d35 4
a38 4
	* You type:
		* ==Tokyo: %<nop>INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*&lt;\!--tzdate:date--&gt;(.*?)&lt;\!--/tzdate:date--&gt;.*"}%==
	* You get:
		* Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%
d40 1
a40 1
__Related Topics:__ TWikiVariables#VarINCLUDE, UserDocumentationCategory
@


1.7
log
@none
@
text
@d1 2
a2 2
%META:TOPICINFO{author="PeterThoeny" date="1092555397" format="1.0" version="1.7"}%
---+!! Include Topics and Web Pages Using ==%<nop>INCLUDE{...}%== Variable
d4 1
a4 1
Use the ==%<nop>INCLUDE{...}%== variable to embed the content of another topic or web page inside a %WIKITOOLNAME% topic. The whole content or only parts of a page can be included. If needed, set a proxy server in %WIKIPREFSTOPIC%.
d8 1
d10 1
a10 1
---++ Syntax
d12 1
a12 1
==%<nop>INCLUDE{ "page" pattern="reg-exp" rev="1.2" }%==
d14 1
a14 5
	* =="page"==: %BR%
	  The nameless parameter specifies the page to include. It is
		* The name of a topic located in the current web, e.g., ==%<nop>INCLUDE{"WebNotify"}%==
		* A =Web.Topic= name specifying a topic in another web, e.g., ==%<nop>INCLUDE{"%TWIKIWEB%.SiteMap"}%==
		* A full qualified URL with ==http== protocol, domain name and optional port number, e.g., ==%<nop>INCLUDE{"http://twiki.org:80/index.html"}%==. Supported content types are ==text/html== and ==text/plain==. The full page is included by default, but the HTML header and scripts are stripped in case it is a web page.
d16 1
a16 7
	* ==pattern="reg-exp"==: %BR%
	  The *pattern* parameter is optional and allows you to extract some parts of a web page. Specify a %TWIKIWEB%.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.

	* ==rev="1.x"==: %BR%
	  The *rev* parameter is optional and allows you to include an earlier revision of a topic. This can be used to include an official version of a topic, e.g. one that has been signed of by management. This parameter does not apply to URLs.

__Note:__ All text of a topic is included unless you specify ==%<nop>STARTINCLUDE%==, ==%<nop>STOPINCLUDE%== and/or a *pattern* parameter. A pattern will only search between ==%<nop>STARTINCLUDE%== and ==%<nop>STOPINCLUDE%==.
d29 3
a31 2
	* You type:
		* ==%<nop>INCLUDE{"http://www.google.com/robots.txt"}%==
d36 1
a36 1
		* ==Tokyo: %<nop>INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%==
d40 1
a40 3
See also other TWikiVariables.

-- TWiki:Main.PeterThoeny - 15 Aug 2004
@


1.6
log
@none
@
text
@d1 51
a51 58
%META:TOPICINFO{author="PeterThoeny" date="1044102412" format="1.0" version="1.6"}%
---+!! Include Topics and Web Pages Using ==%<nop>INCLUDE{...}%== Variable

Use the ==%<nop>INCLUDE{...}%== variable to embed the content of another topic or web page inside a %WIKITOOLNAME% topic. The whole content or only parts of a page can be included. If needed, set a proxy server in %WIKIPREFSTOPIC%.

%TOC%


---++ Syntax

==%<nop>INCLUDE{ "page" pattern="reg-exp" rev="1.2" }%==

	* =="page"==: %BR%
	  The nameless parameter specifies the page to include. It is
		* The name of a topic located in the current web, e.g., ==%<nop>INCLUDE{"WebNotify"}%==
		* A =Web.Topic= name specifying a topic in another web, e.g., ==%<nop>INCLUDE{"%TWIKIWEB%.SiteMap"}%==
		* A full qualified URL with ==http== protocol, domain name and optional port number, e.g., ==%<nop>INCLUDE{"http://twiki.org:80/index.html"}%==. Supported content types are ==text/html== and ==text/plain==. The full page is included by default, but the HTML header and scripts are stripped in case it is a web page.

	* ==pattern="reg-exp"==: %BR%
	  The *pattern* parameter is optional and allows you to extract some parts of a web page. Specify a %TWIKIWEB%.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.

	* ==rev="1.x"==: %BR%
	  The *rev* parameter is optional and allows you to include an earlier revision of a topic. This can be used to include an official version of a topic, e.g. one that has been signed of by management. This parameter does not apply to URLs.

__Note:__ All text of a topic is included unless you specify ==%<nop>STARTINCLUDE%==, ==%<nop>STOPINCLUDE%== and/or a *pattern* parameter.


---++ Usage Examples

---+++ 1. Display regression test results in a TWiki page
<pre>
  &lt;pre&gt;
  %<nop>INCLUDE{"http://domain/~qa/v1.1/REDTest.log.txt"}%
  &lt;/pre&gt;
</pre>

---+++ 2. Display Yahoo's robot.txt file

	* You type:
		* ==%<nop>INCLUDE{"http://www.yahoo.com/robots.txt"}%==

---+++ 3. Display the SUNW stock quote in a TWiki page

	* You type:
		* ==SUNW: %<nop>INCLUDE{"http://finance.yahoo.com/q?s=SUNW&d=v1&o=t" pattern="^.*?&gt;SUNW&lt;/a&gt;[^&lt;]+(.*?)\s+\S+\s+&lt;small.*"}%==
	* You get:
		* SUNW: %INCLUDE{"http://finance.yahoo.com/q?s=SUNW&d=v1&o=t" pattern="^.*?>SUNW</a>[^<]+(.*?)\s+\S+\s+<small.*"}%

---+++ 4. Display the temperature in San Francisco

	* You type:
		* ==San Francisco: %<nop>INCLUDE{"http://weather.yahoo.com/forecast/San_Francisco_CA_US_f.html" pattern="^.*?([0-9]+\&amp;ordm\;F).*"}%==
	* You get:
		* San Francisco: %INCLUDE{"http://weather.yahoo.com/forecast/San_Francisco_CA_US_f.html" pattern="^.*?([0-9]+\&ordm\;F).*"}%

See also other TWikiVariables.

-- Main.PeterThoeny - 15 Jan 2003
@


1.5
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="PeterThoeny" date="1042702500" format="1.0" version="1.5"}%
d4 1
a4 1
Use the ==%<nop>INCLUDE{...}%== variable to embed the content of another topic or web page inside a %WIKITOOLNAME% topic. The whole content or only parts of a page can be included.
@


1.4
log
@none
@
text
@d1 2
a2 2
%META:TOPICINFO{author="PeterThoeny" date="1039594686" format="1.0" version="1.4"}%
*Include Topics and Web Pages Using ==%<nop>INCLUDE{...}%== Variable*
d33 1
a33 1
  %<nop>INCLUDEURL{"http://domain/~qa/v1.1/REDTest.log.txt"}%
d40 1
a40 5
		* ==%<nop>INCLUDE{"http://www.yahoo.com/robots.txt"}%== <br>
	* You get:
<verbatim>
%INCLUDE{"http://www.yahoo.com/robots.txt"}%
</verbatim>
d45 1
a45 1
		* ==SUNW: %<nop>INCLUDE{"http://finance.yahoo.com/q?s=SUNW&d=v1&o=t" pattern="^.*?&gt;SUNW&lt;/a&gt;[^&lt;]+(.*?)\s+\S+\s+&lt;small.*"}%== <br>
d52 1
a52 1
		* ==San Francisco: %<nop>INCLUDE{"http://weather.yahoo.com/forecast/San_Francisco_CA_US_f.html" pattern="^.*?([0-9]+\&amp;ordm\;F).*"}%== <br>
d58 1
a58 1
-- Main.PeterThoeny - 25 Jun 2001 <br>
@


1.3
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="PeterThoeny" date="1037243520" format="1.0" version="1.3"}%
d15 3
a17 3
		* The name of a topic located in the current web, i.e. ==%<nop>INCLUDE{"WebNotify"}%==
		* A =Web.Topic= name specifying a topic in another web, i.e. ==%<nop>INCLUDE{"%TWIKIWEB%.SiteMap"}%==
		* A full qualified URL with ==http== protocol, domain name and optional port number, i.e. ==%<nop>INCLUDE{"http://twiki.org:80/index.html"}%==. Supported content types are ==text/html== and ==text/plain==. The full page is included by default, but the HTML header and scripts are stripped in case it is a web page.
d20 1
a20 1
	  The *pattern* parameter is optional and allows you to extract some parts of a web page. Specify a %TWIKIWEB%.RegularExpression that scans from start (='^'=) to end and contains the text you want to keep in parenthesis, i.e. ==pattern="^.*?(from here.*?to here).*"==. You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
d23 1
a23 1
	  The *rev* parameter is optional and allows you to include an earlier revision of a topic. This can be used to include an official version of a topic, e.g. one that has been signed of by management.
@


1.2
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="PeterThoeny" date="1018175160" format="1.0" version="1.2"}%
d11 1
a11 1
==%<nop>INCLUDE{"page" pattern="reg-exp"}%==
d13 1
a13 1
	* =="page"==: <br>
d19 1
a19 1
	* ==pattern="reg-exp"==: <br>
d21 3
@


1.1
log
@none
@
text
@d1 1
d16 1
a16 1
		* A =Web.Topic= name specifying a topic in another web, i.e. ==%<nop>INCLUDE{"%TWIKIWEB%.TWikiWebsTable"}%==
@
