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.
Attribute | Description |
---|---|
actions | A string containing ActionWidgets to be triggered when the key combination is detected. New in: 5.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 |
to | The title of the tiddler to navigate to |
message | The name of the widget message to send when the button is clicked |
param | The optional parameter to the message |
set | A TextReference to which a new value will be assigned |
setTitle | A title to which a new value will be assigned, without TextReference. Gets preferred over set |
setField | A field name to which the new value will be assigned, if the attribute setTitle is present. Defaults to the text field |
setIndex | An index to which the new value will be assigned, if the attribute setTitle is present |
setTo | The 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 |
selectedClass | An 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 |
default | Default value if set tiddler is missing for testing against setTo to determine selectedClass |
popup | Title of a state tiddler for a popup that is toggled when the button is clicked. See PopupMechanism for details |
popupTitle | Title 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 |
popupAbsCoords | New in: 5.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-label | Optional Accessibility label |
tooltip | Optional tooltip |
class | An optional CSS class name to be assigned to the HTML element |
style | An optional CSS style attribute to be assigned to the HTML element |
tag | An optional html tag to use instead of the default "button" |
dragTiddler | An optional tiddler title making the button draggable and identifying the payload tiddler. See DraggableWidget for details |
dragFilter | An optional filter making the button draggable and identifying the list of payload tiddlers. See DraggableWidget for details |
tabindex | Sets the tabindex attribute of the button to the given value |
disabled | New in: 5.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:
<$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.