RevealWidget

21st November 2020 at 10:09am

Introduction

The reveal widget hides or shows its content depending upon the value of a state tiddler. The type of the widget determines the condition for the content being displayed:

type=match: the content is displayed if the state tiddler matches the text attribute value
type=nomatch: the content is displayed if the state tiddler doesn't match the text attribute value
type=popup: the content is displayed as a popup as described in the PopupMechanism
type=lt: the content is displayed if the state tiddler contains an integer with a value less than the text attribute value
type=gt: the content is displayed if the state tiddler contains an integer with a value greater than the text attribute value
type=lteq: the content is displayed if the state tiddler contains an integer with a value less than or equal to the text attribute value
type=gteq: the content is displayed if the state tiddler contains an integer with a value greater than or equal to the text attribute value

Content and Attributes

The content of the <$reveal> widget is displayed according to the rules given above.

Attribute	Description
state	A TextReference containing the state
stateTitle	A title containing the state, without TextReference. Gets preferred over the `state` attribute
stateField	A field name which is used to look for the state, if the attribute `stateTitle` is present
stateIndex	An index which is used to look for the state, if the attribute `stateTitle` is present
tag	Overrides the default HTML element tag (`<div>` in block mode or `<span>` in inline mode)
type	The type of matching performed: match, nomatch, popup, lt, gt, lteq or gteq
text	The text to match when the type is match, nomatch, lt, gt, lteq or gteq
class	An optional CSS class name to be assigned to the HTML element » Set to `tc-popup-keep` to make a popup "sticky", so it won't close when you click inside of it
style	An optional CSS style attribute to be assigned to the HTML element
position	The position used for the popup when the type is popup. Can be left, above, aboveleft, aboveright, right, belowleft, belowright or below
positionAllowNegative	Set to "yes" to prevent computed popup positions from being clamped to be above zero
default	Default value to use when the state tiddler is missing
animate	Set to "yes" to animate opening and closure (defaults to "no"; requires "retain" to be set to "yes")
retain	Set to "yes" to force the content to be retained even when hidden (defaults to "no")
updatePopupPosition	Introduced in v5.1.23Set to "yes" to update the popup position when the state tiddler is updated (defaults to "no")

Tip

Introduced in v5.1.18 stateTitle, stateField and stateIndex attributes allow specifying Tiddler states directly, without interpreting them as TextReferences. This is useful for edge-cases where titles may contain characters that are used to denote Tiddler fields or indices (!!, ##)

Tip

Retaining the content when hidden can give poor performance since the hidden content requires refresh processing even though it is not displayed. On the other hand, the content can be revealed much more quickly. Note that setting animate="yes" will also require retain="yes"

Examples

Simple content reveal

Here's a simple example of showing and hiding content with buttons:

<$button set="$:/state/SampleReveal1" setTo="show">Show me</$button>
<$button set="$:/state/SampleReveal1" setTo="hide">Hide me</$button>

<$reveal type="match" state="$:/state/SampleReveal1" text="show">

! This is the revealed content
And this is some text

</$reveal>

That renders as:

Accordion or Slider

An "accordion" or "slider" is a button that can be used to toggle the display of associated content.

<$reveal type="nomatch" state="$:/state/SampleReveal2" text="show">

<$button set="$:/state/SampleReveal2" setTo="show">Show me</$button>

</$reveal>
<$reveal type="match" state="$:/state/SampleReveal2" text="show">

<$button set="$:/state/SampleReveal2" setTo="hide">Hide me</$button>

! This is the revealed content
And this is some text

</$reveal>

That renders as:

Popup

Here is a simple example of a popup built with the RevealWidget:

<$button popup="$:/SamplePopupState">Pop me up!</$button>

<$reveal type="popup" state="$:/SamplePopupState">
<div class="tc-drop-down">

! This is the popup
And this is some text

</div>
</$reveal>

That renders as:

How to use text references with field content

Here is a simple example how to use text references with field content to control the RevealWidget. If the field jeremy is populated with text tiddlywiki, a message will be displayed.

<$reveal type="match" state="!!jeremy" text="tiddlywiki">
~TiddlyWiki!
</$reveal>

That renders as:

TiddlyWiki!