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

6. Alert Box using Parameterized Include

7. Create a Widget Library

1. Create a Main.WidgetLibrary topic

1. 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!" }%

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

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

	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.

Related Topics: VarINCLUDE, UserDocumentationCategory

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.

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.

Include Topics and Web Pages Using %INCLUDE{...}% Variable

Syntax Example

  %INCLUDE{"http://www.google.com/robots.txt"}%

• • Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%

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

• • Tokyo: %INCLUDE{"http://TWiki.org/cgi-bin/xtra/tzdate?tz=Asia/Tokyo" pattern="^.*<\!--tzdate:date-->(.*?)<\!--/tzdate:date-->.*"}%

• • Tokyo:

Warning

This site does not allow %INCLUDE% of URLs

Include Topics and Web Pages Using %INCLUDE{...}% Variable

• • %INCLUDE{"http://www.yahoo.com/robots.txt"}%

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

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

• • The name of a topic located in the current web, e.g., %INCLUDE{"WebNotify"}%
  • A Web.Topic name specifying a topic in another web, e.g., %INCLUDE{"TWiki.SiteMap"}%
  • A full qualified URL with http protocol, domain name and optional port number, e.g., %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.

• "page":
  

• pattern="reg-exp":
  

• rev="1.x":
  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.

• • A Web.Topic name specifying a topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}%

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.

Syntax

%INCLUDE{"page" pattern="reg-exp"}%

• "page":
  The nameless parameter specifies the page to include. It is
  • The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
  • A Web.Topic name specifying a topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
  • A full qualified URL with http protocol, domain name and optional port number, i.e. %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":
  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, 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.

Note: All text of a topic is included unless you specify %STARTINCLUDE%, %STOPINCLUDE% and/or a pattern parameter.

Usage Examples

1. Display regression test results in a TWiki page

  <pre>
  %INCLUDEURL{"http://domain/~qa/v1.1/REDTest.log.txt"}%
  </pre>

2. Display Yahoo's robot.txt file

• You type:
  • %INCLUDE{"http://www.yahoo.com/robots.txt"}%
    
• You get:

%INCLUDE{"http://www.yahoo.com/robots.txt"}%

3. Display the SUNW stock quote in a TWiki page

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

Warning

This site does not allow %INCLUDE% of URLs

4. Display the temperature in San Francisco

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

Warning

This site does not allow %INCLUDE% of URLs

See also other TWikiVariables.

-- PeterThoeny - 25 Jun 2001