Feature Proposal: Add a hide option to STARTSECTION

Motivation

Sometimes you create a section on the same page as you want to display it. To hide it, you must put it inside html comments, or inside a hidden verbatim block (class="foswikiHidden"). But it is not satisfactory, because the content is duplicated on the page.

This proposal is to optionally remove the INCLUDE definition from the generated text.

Description and Documentation

  • Add an option definition="hidden" to remove the section contents from view. The section will not be shown when the base topic is viewed or INCLUDEd; the intent is that the section will be hidden unless explicitly called for.

Examples

%STARTSECTION{"blo" definition="hidden"}%
contents
%ENDSECTION{"blo"}%

Impact

%WHATDOESITAFFECT%
edit

Implementation

-- Contributors: ArthurClemens - 27 Nov 2009, PaulHarvey - 04 Apr 2011

Discussion

Can't be UnderConstruction yet, because it hasn't been accepted, so changed state to UnderInvestigation.

I've wanted this in the past myself. I'm struggling to find a reason not to do it.

See VarSTARTSECTION for other parameters to SECTION.

-- CrawfordCurrie - 27 Nov 2009

As with HereDocumentSyntaxForMacros, InlineTopicContentAsMeta, ContentAccessSyntax and SearchBySection, it would be great if we could unify all these things into a common markup, that:
  • Provides the needs demanded by each proposal.
  • Allows sections to be addressable parts of a topic.
  • Would hopefully be possible to use special named section markup instead of/as well as META:FIELDs - sections should be searchable/extractable/comparable.
  • More thoughts ... I will revisit this proposal later.
I have no objection and I would use this feature myself, but it would be highly desirable to solve all these requirements into a more elegant solution.

-- PaulHarvey - 28 Nov 2009

Thinking over the uses that I have seen - I would like to change the syntax, and add another option.

%STARTSECTION{"blo" show="hide"}%
contents
%ENDSECTION{"blo"}%

and the verbatim use for function Sections:

%STARTSECTION{"blo" show="verbatim"}%
contents
%ENDSECTION{"blo"}%

-- SvenDowideit - 30 Nov 2009

How about display=hidden and display=verbatim.

-- MichaelDaum - 30 Nov 2009

My first thought as well, but there's a danger of "display" being misinterpreted as meaning the same as "display" in CSS - which it very much doesn't.

I confess I don't find show very intention-revealing. You are trying to control the presentation of the content, but only in the topic where it is defined. It's not a general "show" control, which would reasonably be expected to control how it is shown when the section is included. Perhaps a more intention-revealing name would be wheredefined, so you have wheredefined="shown" (a NOP), wheredefined="hidden" and wheredefined="verbatim"?

-- CrawfordCurrie - 30 Nov 2009

yes. I really don't care what the parameter is called, I just want more than just hidden=on, and like Crawford points out, its a darned difficult setting to name usefully - wheredefined isn't more intention revealing - but i've got nothing better

Where defined suggests the value is more of a declarative meta datum, not an instruction

still, as we're arguing about naming details, does that mean the feature i suggest has aggreement?

-- SvenDowideit - 01 Dec 2009

To have a display as verbatim, do you mean to have it styled inside a pre like verbatim does?

On naming, I suggest:
  • displaydefinition="hidden"
  • displaydefinition="verbatim"
-- ArthurClemens - 01 Dec 2009

yup, styled inside a pre

happy with your suggestion wrt naming too smile

-- SvenDowideit - 01 Dec 2009

Yes, I'm happy with the concept and yes, I'm happy with Arthur's suggestion for a name.

-- CrawfordCurrie - 04 Dec 2009

What about render for the parameter name? (on,off,0,1,verbatim,etc.)

  • We must distinguish between the section contents and the macro contents. This request is to hide or change how you see the macro, not the section contents (that may be displayed in a different topic). render seems to be about the section contents. -- ArthurClemens - 15 Jan 2010
-- WillNorris - 15 Jan 2010

I have been looking at the code. In Foswiki.pm we have parseSections, but that is only called with an INCLUDE in the topic, which we may not have.

Then we might 'fill in' macro STARTSECTION in a new pm Macros/STARTSECTION.pm. But for a large part this would duplicate the code in parseSections, because we still need to deal with nested and unnamed and improperly closed sections.

Could be perhaps unify this by move the parsing to Macros/STARTSECTION.pm and add the sections to the topic object?

-- ArthurClemens - 16 Jan 2010

Unfortunately I got stuck in the code. A second pair of eyes would help.

-- ArthurClemens - 05 Apr 2010

It would be terrific if sections were addressable via the TOM. One day they could even be queried, perhaps? Anyway, I think incorporating sections into the TOM would be the best path forward. I'm new to TOM internals but will keep sections in mind.

-- PaulHarvey - 05 Apr 2010

Reading the proposal again I don't see a clear spec, and that what has been proposed may be ambiguous. First displaydefinition is quite long for a parameter name. how about display only. Next, does display=hidden mean it is still delivered to the client with only a display:none css property? Or does it mean "remove from markup completeley", which would be a lot more useful than just hiding the fragment.

-- MichaelDaum - 03 Feb 2011

This is no CSS hack. I guess the very first intro paragraph could have made this more clear.

You already proposed display over displaydefinition in 2009. I don't like either (but as the proposal has already been accepted without objection, I would prefer to implement displaydefinition unless a better idea comes along and we reset the clock).

-- PaulHarvey - 03 Feb 2011

I have updated the first paragraph: "This proposal is to optionally remove the INCLUDE definition from the generated text."

-- ArthurClemens - 03 Feb 2011

Well I do prefer display over displaydefinition, and I am sure that other users prefer to keep it short as well. Not sure why the extra ...definition makes it any better.

I can't see the reason why we shouldn't change this. The code isn't even written. Once this is out into the wild we can't change it back.

-- MichaelDaum - 03 Feb 2011

I am not hung up on displaydefinition, I am fine with display. People savvy enough with CSS will be able to work this out.

-- ArthurClemens - 03 Feb 2011

Why not use something completely different like expose as synonym for display/show. Just my 2c. -- Happy implementing!

-- FranzJosefGigler - 03 Feb 2011

expose is an interesting idea. But I'd like to have one more go at agreeing to a 'display'-named param smile The whole reason we didn't go with display (apparently) is that we didn't want it to be confused with CSS property.

I am honestly indifferent to what the parameter name is, I am more concerned with the quality of the code behind it. But I don't like short-circuiting the feature proposal process, we should have sorted this out in 2010.

Let's pick a new name and reset the clock. I had favoured something like inhibit="on" but perhaps display="remove" would please Michael for having a sensible parameter name, and Crawford to make it different enough from the CSS property of the same name.

-- PaulHarvey - 03 Feb 2011

Short circuiting is okay sometimes as long as the orignial intend of the proppsal that was accepted remains the same.

-- MichaelDaum - 04 Feb 2011

I am not indifferent to the name, as we have inherited far too many macros parameters that are badly thought out, and have ended up requiring ugly workarounds such as nonoise to try and make them useable.

Consider what we are trying to say. The goal is to control the TML rendering of the section, such that it is rendered where the section is explicitly included, but not where it is defined. Five points to consider:
  1. There may be other operations which you may want to perform only at the site of the definition.
  2. Whatever parameter name is used should be re-usable for other macros that also require the concept of elision when the topic containing the definition is rendered.
  3. The parameter should ideally be reflexive; instead of just thinking "how do we hide this in the base topic", think also about "how do we show this in a non-base topic".
  4. This is a difficult and rarely used concept. A parameter name that conflicts with more obvious concepts should be avoided, and a wordy name is not such a big problem.
  5. Double negation is bad ( noshow="off" )
Some ideas that come from this train of thought:

elide="basedefinition"
render="included"
hidewhen="inbase"
renderwhen="defined,included"
show="definitiononly"
show="exportedonly"
-- CrawfordCurrie - 04 Feb 2011

Please, KISS. Most of these proposals are hard to understand for non-native english speakers, also conceptually. Something like display="off/verbatim/inline" should be just fine.

-- MichaelDaum - 04 Feb 2011

Think harder, Michael. display is not fine. Anyone would immediately assume that would suppress the display of the section anywhere it is used - exactly like it would mean in CSS. The whole point of this discussion is for us - the experts - to think about these sorts of problems so the end users don't have to. Consistency and clarity.

-- CrawfordCurrie - 04 Feb 2011

I had a bogus commit date. That's been reset to today. I've also changed the proposal. I'm not interested in providing decoration function at this point, because a simple "verbatim" isn't enough of a spec (we need class="tml" to be useful), so somebody else can address that in the near future. Arthur's original proposal was for displaydefinition="hidden" and I didn't really have a problem with that.

It's been changed to definition="hidden". Michael, is this okay for you? Crawford, is this okay with you?

I'm running out of ideas on how to make everybody happy. Which is interesting, because this proposal was already accepted smile

-- PaulHarvey - 05 Feb 2011

Paul, I can live with it. No beauty, not quite intuitive but what can I say more.

Crawford, display=off is fine because it is intention reveling and short. Users don't care how a piece of information is hidden from them. Most don't know css. Most never were aware that a verbatim-hidden section was still delivered to them.

-- MichaelDaum - 05 Feb 2011

definition=hidden is fine. display=off is not, as it says the wrong things to me, and I am at least slightly representative of users.

-- CrawfordCurrie - 06 Feb 2011

Item10316 is probably not the task for this proposal - it is multi purposed, probably 2.0 features.

-- GeorgeClark - 23 Feb 2012

See SectionalTransforms.

-- KipLubliner - 19 Mar 2012

I'd like to see this get implemented. (I just got bitten by using HTML comments. :-/) BTW, please make sure that %TOC% (etc) honor the hiding.

-- RichMorin - 27 Feb 2013

This seems to be stalled for 1.2. I've removed the Item10316 reference, as that is focused on performance of of the %INCLUDE macro.

I'd really like to see this get done though, but I guess it needs to get deferred to 2.0.

-- GeorgeClark - 02 Apr 2014

Changed to Parked, needs a developer to adopt.

-- GeorgeClark - 19 Nov 2015
 
Topic revision: r38 - 19 Nov 2015, GeorgeClark - This page was cached on 30 May 2017 - 09:17.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License