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
actionsattribute - 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.