INCLUDE a topic in the raw

When a topic is included, normally TWiki variables in the included topic are expanded in the context of the inlcluded topic. But if raw="on" is specified, that variable expansion does not happen.

This topic explains what it is for and what it really means.

When a new topic is created based on a template topic

You can specify a template topic when you create a new topic. Variable expansion during topic creation is different from usual. It's explained here. Basically, variables are not expanded for the most part but you can force variable expansion by prepending EOTC__ to a variable name.

Leveraging INCLUDE with raw="on", a template topic can be composed of multiple topics. Let's say there is a topic named ThreePartTemplate as follows. 

%EOTC__INCLUDE{"TmplPartA" raw="on"}%
%EOTC__INCLUDE{"TmplPartB" raw="on"}%
Thanks to raw="on", TWiki variables in TmplPartA and TmplPartB are not expanded when those topics are included. Since most variables are not expanded in topic creation, most variables in TmplPartA and TmplPartB are put as they are in the new topic.

Let's assume TmplPartA contains %CALENDAR%. It will show up as is in a topic created based on ThreePartTemplate.

  1. When TmplPartA is included, no variable expansion happens.
  2. %CALENDAR% is not subject to expansion in topic creation, so it's left as is in the created topic.

If raw="on' wasn't present,

  1. When TmplPartA was included, %CALENDAR% would be expanded in the context of TmplPartA.
  2. As a result, the created topic would have an HTML table of a calendar rather than %CALENDAR% on it.

When a topic is viewed

In viewing a topic, variable expansion always happen.

Let's say there is a topic named IncludedTopic whose content is %TOPIC%.

IncludedTopic: %TOPIC%

If that's included by another topic IncludingTopic with raw="on" parameter and this enhancement is in effect, IncludingTopic shows IncludedTopic.

IncludingTopic: %INCLUDE{"IncludedTopic" raw="on"}% -> IncludingTopic

This is because when IncludedTopic is included by IncludingTopic, the variable %TOPIC% is not expanded and the processing of %INCLUDE{"IncludedTopic" raw="on"}% ends there. Then, %TOPIC% is expanded in the IncludingTopic's context.

On the other hand, if you don't have raw="on", %TOPIC% is expanded in IncludedTopic's context.

IncludingTopic: %INCLUDE{"IncludedTopic"}% -> IncludedTopic

Related Topics: VarINCLUDE, TWikiTemplates#Variable_Expansion