Feature Proposals » INCLUDE to be able to include a topic in the raw

Motivation

There are cases where you want to include a topic in the raw, without variables in the included topic expanded in the included topic's context. Those variables are expanded in in the including topic's context instead.

Description and Documentation

This is an extension of raw="on" parameter, which currently takes effect only when you include from outside TWiki via HTTP. With this enhancement, when a topic is included, if raw="on" is specified, the specified topic is included as is without variables in the included topic are not expanded in the included topic's context.

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

Examples

One use case is in a template topic having %EOTC__INCLUDE{... raw="on"}%.

When a new topic is created based on a template topic, variable expansion doesn't happen for the most part. But by prefixing a variable name with EOTC__ (EOTC stands for "expand only in topic creation". FinerControlVariableExpansionInTopicCreation), you can force the variable expanded.

When a topic is INCLUDE'd, usually, variables in the included topic are expanded in the INCLUDE'd topic's context. You may not want it to happen. This happens e.g. when a topic template consists of three three parts managed separately. Let's call them TmplPartA, TmplPartB, and TmplPartC. And the topic template topic is as follows.

%EOTC__INCLUDE{"TmplPartA" raw="on"}%
%EOTC__INCLUDE{"TmplPartB" raw="on"}%
%EOTC__INCLUDE{"TmplPartC" raw="on"}%

If raw="on" is not specified in %EOTC__INCLUDE{...}%, variables in TmplPartA, TmplPartB, and TmplPartC are expanded in the context of TmplPartA, TmplPartB, and TmplPartC. You cannot put variables in a new topic created based on the template topic.

Impact

Implementation

-- Contributors: Hideyo Imazu - 2013-06-25

Discussion

Sensible incremental enhancement.

-- Peter Thoeny - 2013-06-25