Feature Proposal: Enhance STARTSECTION - improve common usages for defining re-usable markup snippets

Motivation

STARTSECTION is frequently used to define small snippets of Foswiki markup, which is re-used with parameterized INCLUDEs. If the section is defined on the same page in which it is used, then it should be suppressed from the output. If the section is defined on a different page dedicated to such re-usable sections, then it should be wrapped with <verbatim class="tml"> (and probably <sticky> too).

This is a generalization of the motivation for AddHideOptionToSTARTSECTION, and accomplishing that goal in a different way.

SvenDowideit proposed that this mechanism could also be used for more general purposes (see examples below).

Description and Documentation

Add two attributes to STARTSECTION: wrap and transform.

• transform will use a mechanism similar to "IncludeHandlers". The package to handle transform="hide" would be Foswiki::SectionalTransformHandlers::hide
• wrap will use macro-based injection to add content before and after the sectional text. wrap="function" would pre-prend %SECTIONWRAPPER_function_before% and append %SECTIONWRAPPER_function_after%. These could be defined using the preferences mechanism.

Note that these two attributes must be given different names, so that it is possible to add additional sectional transformers in the future and not changing semantics of existing markup.

Examples

Hiding a section

%STARTSECTION{"InLineFunction" transform="hide"}%

Defining a 'function' on a Function Topic

%STARTSECTION{"TwistedTml" wrap="function"}%

Will wrap with <verbatim class="tml">

Changing header indent level

%STARTSECTION{"Content" transform="indentheader" level="2"}%

The API for transformers should include passing the Foswiki::Attrs object.

Popup Dialog

%STARTSECTION{"Content" wrap="jqDialogLink"}%

Will wrap with jqDialog

Twisty

%STARTSECTION{"Content" wrap="twisty"}%

Will wrap with twisty

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

TBD

-- Contributors: KipLubliner - 19 Mar 2012

Discussion