Twisty includes: how to toggle page elements on and off

This functionality has been implemented in TwistyPlugin.

Development

Having fiddled about with Twisties on the configure page, it occurs to me that a twisty include would be cool. This would be a standard %INCLUDE but with a switch to tell it to twist:

%INCLUDE{"OtherTopic" twist="5"}%

-- CrawfordCurrie - 12 Aug 2005

Oh, [Show details...] and [Hide details...] buttons like in dialog boxes. Sounds useful.

-- PeterThoeny - 12 Aug 2005

Might be interesting trying to untangle what happens when someone clicks on a link in the TOC of the including page.....

-- CrawfordCurrie - 12 Aug 2005

what if you did something like twist="5,10" so the click on the button would expand the 5 line summary to 10 lines instead of the whole thing, where it would default to the whole page if the second number were absent or 0. just a though.

I would also like to have something like

%INCLUDE{"OtherTopic" from="#ThisAnchor" to="#AnotherOne"}%

that way you could include different but possibly overlapping content from a single page to multiple pages without having to resort to some esoteric regex or

 %STARTINCLUDE{}% 

-- TravisBarker - 12 Aug 2005

This is great! I've been thinking of several applications of this exact feature recently. Being as different applications may call for different "toggle labels," how about having an attribute like show="This is the test for opening twisty" and hide="This is text for hiding twisty". Or could the same effect be achived with parameterized includes?

-- LynnwoodBrown - 12 Aug 2005

Whoa, let's apply the KISS principle. There may be synergies with MichaelSparks' sectional includes that I hadn't considered.

   %INCLUDE{"OtherTopic" section="#PaintingPigs"}%
   %INCLUDE{"OtherTopic" from="#PaintingPigs" to="#GildingLilys"}%

   %INCLUDE{"OtherTopic" twisty="10" from="#PaintingPigs" to="#GildingLilys"}%

I can't say I like Travis' idea of multiple twisty levels. I can't see any applications for that. Keep it simple, I say. The proposal is to support Javascript twisty buttons, using a new parameter on %INCLUDE as follows:

%INCLUDE{"ProperFootball" twisty="50"}%

Playing football has a long tradition in England and football had probably been played........

click the button and get:

Playing football has a long tradition in England and football had probably been played at Rugby School for two hundred years before three boys published the first set of written rules in 1845. The rules had always been determined by the pupils and not the masters and they were frequently modified with each new intake. Rules changes, such as the legality of carrying or running with the ball, were often often agreed shortly before the commencement of a game. There were thus no formal rules for football during the time. William Webb Ellis was at the school (1816-1825) and the legendary story of the boy "who with a fine disregard for the rules as played in his time, first took the ball in his arms and ran with it" in 1823 is apocryphal.

-- CrawfordCurrie - 13 Aug 2005

This would be easy to do, but probably might be better in a plugin?

-- ThomasWeigert - 13 Aug 2005

come to think of it, i cant think of any applications of the multi level thing either but i do like the "from=" / "to=" thing. The problem i see with that is in a situation where, such as in the example:

%INCLUDE{"OtherTopic" twisty="10" from="#PaintingPigs" to="#GildingLilys"}%

a way to eliminate this conflict would be to say *do not use "to=" if you are using "twisty="

ie {twisty="50" from="#SomePlace"} would be ok, or {from="#SomePlace" to="#SomewhereElse"}. So long as you don't try to use all three params in the same arg.

I don't know if the conflict would be a problem but I thought I might mention it.

-- TravisBarker - 14 Aug 2005

Thomas, you are right, a plugin probably would be more appropriate.

-- CrawfordCurrie - 15 Aug 2005

A plugin for this would need an additional hook (like beforeIncludeHandler and/or afterIncludeHandler)? Or would a little hack using preRenderingHandler or beforeCommonTagsHandler do?

-- RafaelAlvarez - 15 Aug 2005

I'm a bit confused by the mixing together in this discussion of TwistyIncludes and MultiStartStopIncludes (aka MultipleCustomIncludes & NamedIncludeSections). These seems like completely separate (though complimentary) features. Afterall, they both simply extend the syntax for the INCLUDE variable and could be used independently of each other. Which of these are you (Crawford & Thomas) suggesting should be a plugin?

Regarding MultipleCustomIncludes, I'd like to propose refactoring that part of this discussion to one of those earlier topics (which I think had better ideas than those proposed here anyway).

Regarding TwistyIncludes, I have several thoughts. First, I think we may want to use it in other ways than just includes. For example, MediaWiki has as standard the ability to show/hide a topic's table of contents. I can think of many topics with giant TOC's where this would be useful. Another application would be to show/hide a comment box. Therefore, I think it would be a more flexible syntax to have something like More... Close where "foo bar" might be INCLUDE, TOC, COMMENT, etc. Also, I'd like to reiterate my case that being able to designate text for the toggle button (in both states) would be important for using this feature in different applications - and more widely useful than designating how many lines to reveal.

Finally, I suspect that this will be such a useful feature, that if it's done as a plugin, we'll very soon after want to put it into the core.

-- LynnwoodBrown - 15 Aug 2005

Good point, Lynnwood. %TWISTY sounds like a very sensible approach. The very idea suggests an implementation (try clicking the image):

Twisted text... Twisted text that can be expanded out to a glorious profusion of colours, sights, sounds and smells matched only by the burger van at the 2005 Kilmore Highland Games.

-- CrawfordCurrie - 16 Aug 2005

It works with %INCLUDE{}% as well...

TWiki Tip of the Day

Raw View link
At the bottom of the page next to Edit and Attach , there is a Raw View link that allows... Read on 

-- AntonAylward - 16 Aug 2005

Hmmm. This emerges as a potentially rather useful feature. Useful enough to make me want to consider a more general approach: Option 1

%TWISTY{"Some text to twist"}%

%TWISTED% (or <twisted>?)
Text to go in a twisty
%UNTWISTED% (or </twisted>?)

Should you be able to nest them? Should this be done in the core, or a plugin? And how about

%TOC{twisted="on"}%

-- CrawfordCurrie - 17 Aug 2005

so, you're telling me that you can do this all my defining 2 TWikiVariables, TWISTED and UNTWISTED

and you don't need any change to the code?

in that case...

-- SvenDowideit - 17 Aug 2005

... limited only by your imagination.

Personally I prefer the javascript because I can see a situation where the twisty presents two very different "chunks" rather than just expanding detail.

Right now, the TWikiVariables approach is something like a format\="$summary(10, noheader)" in a %SEARCH statement. You get it all you get the first few charecters. (Yes, I know, for TOC it will be different.)

No, I definitely prefer the javascript and two DIVs.

-- AntonAylward - 17 Aug 2005

The 'official' way to show/hide is now to change the classname element: changing the className is faster than changing the style in all browsers but Safari

-- ArthurClemens - 17 Aug 2005

How would that work in practice; can you give us an example?

-- CrawfordCurrie - 18 Aug 2005

An example with changing the class name (could be optimized further - when I have actually read Optimizing JavaScript for Execution Speed ):

• toggle.html: Toggle test /example

The placeholder text is optional of course.

-- ArthurClemens - 18 Aug 2005

• toggle-optm.html: an optimized version of the toggle test/example

-- ArthurClemens - 19 Aug 2005

Looks good; now, all we need to do is package that as an INCLUDE.....

-- CrawfordCurrie - 19 Aug 2005

Minor corrections:

• the link onclick should return false
• the initial index value in indexOf was out of array bounds

I've updated the toggle-optm example

-- ArthurClemens - 20 Aug 2005

What should be the default behaviour when javascript is off? Just show the hidden content?

Or should we cater for javascript off?

-- ArthurClemens - 20 Aug 2005

I suggest to show hidden content if JavaScript is turned off.

TWiki's mission is to run on a variety of platforms. JavaScript can be used and it should degrade gracefully if not available or turned off.

-- PeterThoeny - 20 Aug 2005

I've created a version that shows the hidden content when javascript is off, and hides the toggle links. It requires that initTwist is called in window.onload.

• toggle-optm-jsoff.html: optimized version with fallback if javascript is off

This works with the following classes:

• the show control item (links/buttons) gets the class twikiTwistMakeVisible
• the hide control item gets the classes twikiTwistHidden twikiTwistMakeVisible
• the toggle item gets the class twikiTwistMakeHidden

(Each item can have more classes by adding them as a space separated list.)

-- ArthurClemens - 20 Aug 2005

Discussion on where to put JavaScript moved to UseIncludedFilesForJavaScript

Michael Sparks suggested some good ideas on IRC w.r.t including sections of other topics, which boil down to:

%TWIST{from="here" to="there"}%
This is some text, the twisted version would run from here to there
%UNTWIST%

%TWIST{regex="here.*?there"}%
This is some text, the twisted version would run from here to there
%UNTWIST%

-- CrawfordCurrie - 22 Aug 2005

I see some similarities with FilterPlugin.

-- ArthurClemens - 23 Aug 2005

For those who are interested in expanding the functionality of INCLUDE (see discussion near the top of this page) I have build an early example plugin which demonstrates the features I would like to see included. for now I will put that Plugin and discussion at ShowTopicSectionPluginDev.

-- TravisBarker - 23 Aug 2005

I've moved all the javascript out of the content so that it can all be put in it's own script. This means that as long as the classes can stay the same we can change how we implement the javascript behaviour without having to change the content throughout the wiki.

• toggle-optm-jsoff-sep.html: optimised+fallback+separation of behaviour from presentation and content

Note that it assumes that the element with the class twikiTwistTrigger will have a direct parent with an ID that can be twisted.

I also noticed that the array indexing assumes that there will be twisties on the page, the code I added doesn't (although it's indexing is a bit screwball).

-- SamHasler - 26 Aug 2005

Could TWisties be used in the (pattern) skin, e.g. for hiding long forms or attachment tables untill the user accesses them specifically?

-- JosMaccabiani - 26 Aug 2005

Sure, that's the idea. But to make a distinction between attachment tables and long attachment tables could be difficult...

Now we need to reach consensus how to add the javascript to the templates AND make it available on other places.

-- ArthurClemens - 26 Aug 2005

All the javascript should be in a single .js file so that it is completely independent of anything else, and have it linked/imported after all other javascript (including user javascript if we allow that in the future) so that it can make sure when it adds it's onload function it doesn't remove any existing one.

I'm working on this and should have it all packaged up soon. I'm also to see if I can't separate the styles into their own css file so that their definitions are outside the javascript.

-- SamHasler - 29 Aug 2005

Here it is:

• toggle-optm-jsoff-sep.html: optimised+fallback+separation of behaviour from presentation and content
• twist.css: CSS for toggle-optm-jsoff-sep.html
• twist.js: JavaScript for toggle-optm-jsoff-sep.html

As I said before, it's safest if twist.js is the last javascript file linked in any template it is added to as it won't overwrite any previously set onload handler so the other files don't overwrite twist.js' onload function. (correction -- ArthurClemens - 02 Sep 2005)

-- SamHasler - 01 Sep 2005

Blast, I forgot about the indexing, I'll look at that tomorrow morning. Need sleep....

-- SamHasler - 01 Sep 2005

I've fixed the indexing in the loops so it won't cause a javascript error if there is no twisty on the page. It also makes the loops more readable.

-- SamHasler - 02 Sep 2005

Nice. I made a small text correction above.

1. Where should be js file be put? It should be possible to use the script in templates and in topics (like personal left bar topics).
2. The twikiTwistPlaceholder style should be configurable per skin. I think its best if twist.css doesn't set a color, so you get an empty 'declaration'. Then the skin can define a style, regardless if that is loaded before or after twisty.js.

-- ArthurClemens - 02 Sep 2005

1. Put it in the view and preview templates, same as I did the old toggle.js script.
2. Sure. There's so little css there you could even write it in from the javascript. It's wouldn't really be breaking the separation of style and behaviour that much, and it means it's packaged in one neat file then.

I'm still trying to think my way through all the hiding logic. I'm not convinced there isn't a simpler way of doing it.

-- SamHasler - 02 Sep 2005

you could even write it in from the javascript Except when javascript is off.

-- ArthurClemens - 02 Sep 2005

Would TWiki.TWikiJavascript be a good topic name for the twisty script attachment?

-- ArthurClemens - 05 Sep 2005

That sounds good to me.

-- RafaelAlvarez - 05 Sep 2005

I just had a little discussion with WillNorris on IRC. It comes down to:

• Do we collect multiple javascripts inside one TWiki topic (so multiple attachments)
• Do we attach each javascript to its own TWiki topic with its own documentation and examples

The jury is still out.

-- ArthurClemens - 05 Sep 2005

Crawford proposed on IRC (http://koala.ilog.fr/twikiirc/bin/irclogger_log/twiki?date=2005-09-05,Mon&sel=207#l203) to put the javascript files in /lib/TWiki/Contrib.

-- ArthurClemens - 08 Sep 2005

No I didn't! That's a terrible idea! I meant to put them in pub/TWiki/XXXContrib, where XXX is the name of the contrib package that includes the JS files (compare this with JSCalendarContrib)

-- CrawfordCurrie - 08 Sep 2005

TWiki.TwistyInclude ( oops, i accidentally typed TWiki.TWistyInclude the first time )

-- WillNorris - 08 Sep 2005

I have packaged the css, the js and the demo page as a Contrib. Check out TwistyContrib.

-- RafaelAlvarez - 12 Sep 2005

Further development

Should we be removing the event listeners at onunload to avoid the IE memory leak problem? See Quirksmode - addEvent() considered harmful for details of the problem and why it's not easy to solve and watch Quirksmode - addEvent() recoding contest for a solution.

-- SamHasler - 17 Sep 2005

The recoding contest closes on 22 September. We better wait for the conclusion.

-- ArthurClemens - 17 Sep 2005

Here's an example of a script that automatically generates 'show' links (for a weblog).

-- ArthurClemens - 18 Sep 2005

The utility of the way the current TwistyIncludes is written is that by leaving out the hide anchors in the html we can get the same functionality as that site.

-- SamHasler - 22 Sep 2005

But still we would need somw calculation, like the number of paragraphs or the number of characters. And TWiki topics are not well structured. Perhaps count <p>s.

-- ArthurClemens - 22 Sep 2005