This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

ButtonWidget

 13th November 2023 at 9:33am

Introduction

The button widget displays an HTML <button> element that can perform a combination of optional actions when clicked:

  • Executing any ActionWidgets passed in the actions attribute
  • Executing any ActionWidgets that are immediate children of the button widget
  • Execute any integrated actions:
    • Navigate to a specified tiddler
    • Dispatch a user defined widget message
    • Trigger a user defined popup
    • Assign new text to a specified tiddler

The integrated actions are provided as a shortcut for invoking common actions. The same functionality is available via ActionWidgets, with the exception of the support for highlighting selected popups.

Content and Attributes

The content of the <$button> widget is displayed within the button.

AttributeDescription
actionsA string containing ActionWidgets to be triggered when the key combination is detected. Introduced in v5.1.23 the modifier variable lists the modifier keys that are pressed when the action is invoked. The possible modifiers are ctrl, ctrl-alt, ctrl-shift, alt, alt-shift, shift and ctrl-alt-shift
toThe title of the tiddler to navigate to
messageThe name of the widget message to send when the button is clicked
paramThe optional parameter to the message
setA TextReference to which a new value will be assigned
setTitleA title to which a new value will be assigned, without TextReference. Gets preferred over set
setFieldA field name to which the new value will be assigned, if the attribute setTitle is present. Defaults to the text field
setIndexAn index to which the new value will be assigned, if the attribute setTitle is present
setToThe new value to assign to the TextReference identified in the set attribute or the text field / the field specified through setField / the index specified through setIndex of the title given through setTitle
selectedClassAn optional additional CSS class to be assigned if the popup is triggered or the tiddler specified in set already has the value specified in setTo
defaultDefault value if set tiddler is missing for testing against setTo to determine selectedClass
popupTitle of a state tiddler for a popup that is toggled when the button is clicked. See PopupMechanism for details
popupTitleTitle of a state tiddler for a popup that is toggled when the button is clicked. In difference to the popup attribute, no TextReference is used. See PopupMechanism for details
popupAbsCoordsIntroduced in v5.2.4 If set to yes writes absolute coordinates to the tiddler referenced by the popup. If set to no (the default) uses relative coordinates. See Coordinate Systems for details
aria-labelOptional Accessibility label
tooltipOptional tooltip
classAn optional CSS class name to be assigned to the HTML element
data-*New in v5.3.2 Optional data attributes to be assigned to the HTML element
style.*New in v5.3.2 Optional CSS properties to be assigned to the HTML element
styleAn optional CSS style attribute to be assigned to the HTML element
tagAn optional html tag to use instead of the default "button"
dragTiddlerAn optional tiddler title making the button draggable and identifying the payload tiddler. See DraggableWidget for details
dragFilterAn optional filter making the button draggable and identifying the list of payload tiddlers. See DraggableWidget for details
tabindexSets the tabindex attribute of the button to the given value
disabledIntroduced in v5.1.23 Optional, disables the button if set to "yes". Defaults to "no"

Note: In almost all other cases where a TextReference is used as a widget attribute, it will be placed between curly brackets, to transclude the value currently stored there. However, when we use a TextReference as the value of a button widget's set attribute, we are referencing the storage location itself, rather than the value stored there, so we do not use curly brackets there. Example: we could code a button widget that sets the caption field of TiddlerA to be the same as that of TiddlerB as:

Tip
Introduced in v5.1.18 setTitle, setField and setIndex 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 (!!, ##)

<$button set="TiddlerA!!caption" setTo={{TiddlerB!!caption}} >

Press me!

</$button>

Tip: Set class to tc-btn-invisible tc-tiddlylink to have a button look like an internal link.