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.

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

Will wrap with jqDialog

Twisty

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

Will wrap with twisty

Impact

%WHATDOESITAFFECT%
edit

Implementation

TBD

-- Contributors: KipLubliner - 19 Mar 2012

Discussion

Topic revision: r1 - 19 Mar 2012, KipLubliner
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy