TranscludeEarlier

Transclude earlier?

This is a long way from an actual feature proposal, but I thought I'd see what thoughts people might have on this topic.

Currently in Foswiki, our macros, including INCLUDE, are evaluated at the time of topic rendering. After working a bit with Mediawiki, the question I'm putting forward is, should we consider an alternate form of transclusion that works "earlier"? That makes it appear to existing plug-ins and macros like SEARCH that the transcluded content is actually within the stored topic text - not just the rendered topic text?

Advantages

More power and flexibility.

Searches would be able to find all topics that contain certain text - even if that text has been transcluded into the topic instead of put there directly.

Provides for macro expansion relative to the including topic - rather than the included topic - since macro expansion would still take place at the time of rendering. Only the transcluding would be earlier.

Others? I have the feeling there may be more, but I haven't thought them all through yet.

Disadvantages

More power and flexibility Yet another potential syntax and feature to learn. Do we need it? How handy would it really be? Would it be confusing in combination with the macros, sections and includes that we already have?

Alternatives

Alternatively, I guess we could make a forms of SEARCH and plug-ins that work "later" - on the rendered content instead of the stored content.

"Do nothing" is obviously an option.

Background

For those unfamiliar, Mediawiki has a concept called "Templates". A template is an article in a special Template namespace (a namespace can be thought of as roughly equivalent to a Web) that is designed to be "transcluded" into other articles. Templates have names and can optionally have arguments. Templates can be nested. In other words, one Template can transclude another template.

In Foswiki, we have a few ways of doing similar things. One way is to use MACROS - simple preference variables or Plug-in type MACROS, which, during the page rendering process, get translated into some other text, and after all the MACROS have been substituted, the page is rendered.

Another way is to use the INCLUDE macro to include another topic or portion of a topic (using sections). Parameterized includes on the surface sound just like Templates. The topic or section that you are including can include other topics or sections and you can pass arguments/parameters.

I've just moved a number of Mediawiki articles to a Foswiki installation, using a Contrib developed by MichaelDaum. That contrib (MediaWikiToFoswikiContrib - thanks Michael, it's been very helpful) tries to use parameterized INCLUDEs to replace Mediawiki Templates - but it doesn't work right. This is not because of any coding error, but because they really aren't equivalent, as Michael mentions quite prominently in his code comments.

Example

Mediawiki

In Mediawiki I have a "Template:To Do" article that contains the following

[[Category:To Do]] {{{1}}}

The text between the double square brackets assigns the article to a Category called "To Do". What does it mean? Essentially it simply means that a link to the article will appear on an automatically generated list on a Category:To Do article (a special page in the Category namespace).

The triple curly braces with the 1 inside mean "substitute this with the first argument".

In some other article, I invoke the template like this (note the simple syntax by the way):

{{To Do|My simple To Do example.}}

On rendering, you'll see something like:

[[Category: To Do]] My simple To Do example.

So far, as expected.

The thing I found interesting though is that the page that uses the Template actually gets added to Category: To Do. In other words, if you go to the Category: To Do page, you'll see the page that uses the Template is listed there. (The template page itself does too in my example, though this can be prevented with the addition of the includeonly tag in the template). It seems that Mediawiki transclusion is a lot more than just about rendering.

Foswiki

A simple but incorrect translation of this example into Foswiki would be:

Create a "template" topic called ToDo with the following content:

[[Category.ToDo]] %TODOTEXT%

Create a category topic called CategoryToDo that does a search for all topics that contain CategoryToDo:

---+ !CategoryToDo
This is an automatically generated list of all topics assigned to CategoryToDo.
| *Topic* | *Last Modified* | *Last Editor* |
%SEARCH{
"text~'*CategoryToDo*'" 
type="query"
nonoise="on"
excludetopic="%TOPIC%"
format="| $topic | $date | $wikiusername |"
}%

Use your "template" in some other topic (note the comparatively verbose syntax):

%INCLUDE{"ToDo" TODOTEXT="My simple To Do example."}%

On rendering, you'll see something like:

[[CategoryToDo]] My simple To Do example.

So far it looks pretty much like the Mediawiki example.

The difference is, when you go to the CategoryToDo topic, no topics are listed. The search doesn't find the topic

Since we all know how SEACH and INCLUDE work, this behavior is totally expected and correct. Furthermore, you can easily work around this issue by making your category page search for pages that use the template in addition to any that might use the category directly.

The question I'm raising here is, might it be handy to have some alternative to INCLUDE that actually works more the Mediawiki template way?

Implementation

I deliberately don't want to give this too much thought yet. The first question to ask is "Is it useful?". If so, we can dive into "Can it be be implemented in a reasonable way?" next.

Discussion

Commenting is disabled while not logged in