Include Topics and Web Pages Using %INCLUDE{...}%
Macro
Embed topics, or subsections of topics, or other web pages.
The
%INCLUDE{...}% macro embeds the content of the specified topic at the place where the
INCLUDE is used. The whole content or only parts of of a page can be included.
If permitted in
configure, content from any arbitrary URL may be included also. This is disabled by default because it may be used for malicious purposes, especially on public installations.
See:
Security and Authentication > Environment > {INCLUDE}{AllowURLs}
.
If your web server connects to the internet via a proxy server, Proxy settings should be set in
configure. See:
Security and Authentication > Proxies > {PROXY}{HOST}
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 contains the text you want to keep in parenthesis. It may be helpful for the pattern to match more than just the text you wish to keep, e.g.
pattern="Some prefix(Start here.*?to here)"
. If needed, the pattern may even scan from start (
'^'
) to end and match the whole topic, 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 macros 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.
All text of a topic is included unless it contains a
%STARTINCLUDE% and
%STOPINCLUDE%, or you specify a
section
parameter (see
STARTSECTION and
ENDSECTION) and/or a
pattern
parameter. A pattern will only search between
%STARTINCLUDE%
and
%STOPINCLUDE%
or within the
section
specified.
Usage notes
Preference settings in included topics
- Bullet and Meta style preferences are not evaluated.
-
%SET
preferences are evaluated whe macros are expanded, but in a new "context".
- Values set in the included topic will be used when expanded in the included topic, but not outside of the included topic..
- Preferences FINALIZED in the including base topic will not be set in the included topic.
Links and WikiWords
- Links and WikiWords that do not specify a web will be adjusted to point to the web that contains the included topic.
-
TopicName
is changed to Web.TopicName
- ACRONYM is changed to Web.ACRONYM but only if it exists as a topic.
- [[Topicname]] links are changed to [[Web.Topicname]]
Usage Examples
1. Display regression test results
<pre>
%INCLUDE{"http://domain/~qa/v1.1/REDTest.log.txt"}%
</pre>
2. Display foswiki.org's frequently asked questions
%INCLUDE{"https://foswiki.org/Support/FrequentlyAskedQuestion?skin=text"}%
- Warning
- This site does not allow %INCLUDE% of URLs
Including URLs is disabled by default as it presents a security risk. It may be enabled via
configure.
Only enable this if you understand the risk.
3. Include a topic
%INCLUDE{"%SYSTEMWEB%.TipsOfTheDayInclude"}%
Use the verbatim tag to surround code excerpts and other formatted text with = verbatim = and = /ver...
Read on
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.
Related Topics: VarINCLUDE,
UserDocumentationCategory