Need a handler to process text before it is included

I have been struggling with making sectional editing work for included topics. This is impossible for anything but named sections, due to the fact that there is no access to the whole included topic to a plugin that does this manipulation.

The problem comes in when only part of the topic is included and it is then impossible to find the section again in the topic when invoking edit.

Of course, requiring that all sections be named is a non-starter (just think of wanting editing of sections indicated by headlines).

The way this can be done is if we had a handler that is invoked on a topic before it is cut down to the portion that is actually included. This handler can the appropriately preprocess the whole text (e.g., identifying sections in a way that allows them to be later found again). This handler must be invoked in TWiki::_INCLUDE right before we start looking for %STARTINCLUDE.

Something like this is a MUST if we want sectional editing to work with included topics.

If have both the code for this handler as well as the updated MultiEditPlugin working (as you can imagine, the changes to core are only a few lines). I want to reaffirm that there is no other way that I can see to get sectional editing working for included topics.

-- Contributors: ThomasWeigert - 12 Nov 2006

Discussion

An alternative to creating a new handler is to apply the beforeCommonTagsHandler to included topics, but before they are included (i.e., at the same place as discussed above). Note that currently this handler is not invoked on included topics at all.

-- ThomasWeigert - 12 Nov 2006

This would also be usefull for implementing relative heading levels, wouldn't it?

-- FranzJosefSilli - 12 Nov 2006

Yes, relative heading levels might be easier if we had this handler, depending on what the spec is, see the discussion at RelativeHeadingLevelsforINCLUDE.

-- ThomasWeigert - 13 Nov 2006

I have convinced myself that it is consistent enough if we apply the beforeCommonTagsHandler to the included topic before it is stripped down.

I have reimplemented the examples using beforeCommonTagsHandler. This is a one-line change to TWiki.pm:

Index: lib/TWiki.pm
===================================================================
--- lib/TWiki.pm   (revision 11965)
+++ lib/TWiki.pm   (working copy)
@@ -2824,6 +2824,9 @@
         return '';
     }
 
+    $this->{plugins}->beforeCommonTagsHandler( $text, $includedTopic,
+                      $includedWeb );
+
     # remove everything before and after the selected include block
     if( !$section ) {
        $text =~ s/.*?%STARTINCLUDE%//s;

-- ThomasWeigert - 13 Nov 2006

Does adding an extra beforeCommonTagsHandler to the included topic affect the evaluation order? Does it impact the rendering? For example, do DashboardWithDynamicTable, DashboardWithDynamicInclude, SpreadSheetRollupTest still work as expected?

With this change, common variables are now evaluated twice (in the included topic and for the whole topic again). No side-effects? What about performance impact?

-- PeterThoeny - 13 Nov 2006

The test cases are not affected by this handler, of course, as it only affects the plugins.

Common variables are not evaluated twice because of this enhancement as the beforeCommonTagsHandler does not evaluate common variables. It does whatever the plugins tell it to do.

Note that commonTagsHandler is called already twice in the existing code, once on the included section, and once on the resultant topic. All we are talking about here is running a handler (either the beforeCommonTagsHandler or a new beforeIncludeHandler over the to be included topic before it is included to make sure the included text will work after inclusion.

-- ThomasWeigert - 13 Nov 2006

Peter, I verified that the examples in DashboardWithDynamicTable, DashboardWithDynamicInclude, SpreadSheetRollupTest still work as expected.

I do think that there are two bugs in DashboardWithDynamicTable, though:

• There is a bar below the "Dashboard example" table. It results from two vertical bars next to each other. This is interesting and may be a bug in the table algorithm, as it is a degenerated case of a merged cell.
• I would have thought that the example demonstrates how the "Dashboard example" is expanded into the list above it, but all it shows is a single cell with the template. Actually, looking at the raw topic it appears that this is an "exercise for the reader" but certainly not finished.

-- ThomasWeigert - 13 Nov 2006