# Button

The Button Class provides properties, methods, and events to interface with the HTML tags generated by the [silk:Button](https://docs.silkbuilder.com/tags/button) component tag. The **silk:Button** component will instantiate a Button object using the component's ID. Using this object, the developer can interact with the button programmatically.

```xml
<silk:Button id="bt1" label="Click Me" />
<silk:JQcode>
	bt1.on("click", function(){
		silk.alert("I have been clicked!");
	});
</silk:JQcode>
```

**Kind**: global class

## Properties

| Name    | Type     | Description                                       |
| ------- | -------- | ------------------------------------------------- |
| $button | `Object` | jQuery object referencing to the button HTML tag. |

## Constructor

### new Button(buttonID, options)

Returns a Button instance.

| Param                    | Type      | Description                                                                            |
| ------------------------ | --------- | -------------------------------------------------------------------------------------- |
| buttonID                 | `String`  | Button's name and unique identifier.                                                   |
| options                  | `Object`  | Object containing the configuration.                                                   |
| \[option.targetPage]     | `String`  | The page to activate if clicked.                                                       |
| \[option.singleClick]    | `Boolean` | The single click behavior. It is true by default                                       |
| \[option.autoEnable]     | `Boolean` | The auto enable status after a click. It is true by default.                           |
| \[option.confirmTitle]   | `String`  | The confirmation dialog title.                                                         |
| \[option.confirmMessage] | `String`  | The confirmation dialog message.                                                       |
| \[option.confirmLabel]   | `String`  | The confirmation dialog button's label.                                                |
| \[option.confirmIcon]    | `String`  | The confirmation dialog icon.                                                          |
| \[option.toggleList]     | `String`  | The list of comma-separated elements that will be toggled together with the component. |

## Methods

### click()

Executes the click event programmatically. This method will ignore the confirmation dialog if configured. This method is executed after the user clicks the button, and a confirmation dialog has not been set up. Ultimately, the confirmation process will also execute this method.

**Kind**: instance method of [`Button`](#Button)<br>

### confirm()

Opens the confirmation dialog programmatically and waits for a response. A positive answer will execute the click event.

**Kind**: instance method of [`Button`](#Button)<br>

### getConfirmLabel() ⇒ `String`

gets the button's label from the confirmation dialog.

**Kind**: instance method of [`Button`](#Button)<br>

### getConfirmMessage() ⇒ `String`

Get the message for the confirmation dialog.

**Kind**: instance method of [`Button`](#Button)<br>

### getConfirmTitle() ⇒ `String`

Get the title of the confirmation dialog.

**Kind**: instance method of [`Button`](#Button)<br>

### getLabel() ⇒ `String`

Gets the button's label.

**Kind**: instance method of [`Button`](#Button)<br>

### getNeedsConfirmation() ⇒ `Boolean`

Return true if the button will ask for confirmation.

**Kind**: instance method of [`Button`](#Button)<br>

### go()

Triggers the show method in the targetPage if configured.

**Kind**: instance method of [`Button`](#Button)<br>

### hide()

Hides the button

**Kind**: instance method of [`Button`](#Button)<br>

### on

Load events to respond to the button's interactions. To set an event, use this code: `Button.on(<eventName>, function(){<code>})`.

**Kind**: instance property of [`Button`](#Button)

| Param         | Type       | Description                   |
| ------------- | ---------- | ----------------------------- |
| eventName     | `String`   | The event's name.             |
| eventFunction | `function` | The function to be triggered. |

### setConfirmIcon(icon)

Sets the icon for the confirmation dialog

**Kind**: instance method of [`Button`](#Button)

| Param | Type     | Description  |
| ----- | -------- | ------------ |
| icon  | `String` | The new icon |

### setConfirmLabel(label)

Sets the button's label for the confirmation dialog.

**Kind**: instance method of [`Button`](#Button)

| Param | Type     | Description   |
| ----- | -------- | ------------- |
| label | `String` | The new label |

### setConfirmMessage(message)

Sets the message for the confirmation dialog.

**Kind**: instance method of [`Button`](#Button)

| Param   | Type     | Description     |
| ------- | -------- | --------------- |
| message | `String` | The new message |

### setConfirmTitle(title)

Sets the title for the confirmation dialog

**Kind**: instance method of [`Button`](#Button)

| Param | Type     | Description   |
| ----- | -------- | ------------- |
| title | `String` | The new title |

### setDisable(mode)

Disables an enabled If a parameter is provided, the action will change accordingly. True will disable the button, and false will enable it.

**Kind**: instance method of [`Button`](#Button)

| Param | Type      | Description                      |
| ----- | --------- | -------------------------------- |
| mode  | `boolean` | True disables and false enables. |

### setEnable(mode)

Enables a disabled If a parameter is provided, the action will change accordingly. True will enable the button, and false will disable it.

**Kind**: instance method of [`Button`](#Button)

| Param | Type      | Default | Description                     |
| ----- | --------- | ------- | ------------------------------- |
| mode  | `boolean` | `true`  | True enables and false disables |

### setLabel(label)

Sets the button's label.

**Kind**: instance method of [`Button`](#Button)

| Param | Type     | Description                |
| ----- | -------- | -------------------------- |
| label | `string` | The text of the new label. |

### show()

Shows the button

**Kind**: instance method of [`Button`](#Button)<br>

### toggle(status)

Hides or shows the button based on the provided parameter. If the parameter is not provided, it will invert the current display status. If shown, it will be hidden; if hidden, it will be displayed.

**Kind**: instance method of [`Button`](#Button)

| Param  | Type      | Description                 |
| ------ | --------- | --------------------------- |
| status | `boolean` | True shows and false hides. |

## Events

### on:beforeClick

This event is triggered after the button is clicked but before the click event is called, or the confirmation dialog is open if configured. It is created with the `Button.on("beforeClick", function(){})` method. If the set function returns *false,* neither the click event nor the dialog is called.

**Kind**: event emitted by [`Button`](#Button)<br>

### on:click

This event is triggered when the button is clicked. It is created with the `Button.on("click", function(){})` method.

**Kind**: event emitted by [`Button`](#Button)<br>

### on:validateConfirm

This event is triggered before the button's confirmation dialog is called. This only operates if a confirmation dialog has been set up. If it returns true or does not return a value, the dialog is displayed. If it returns *false,* the confirmation dialog is ignored and the click event is executed. This event can also be used to modify the confirmation dialog properties before they are displayed. It is created with the `Button.on("validateConfirm", function(){})` method.

**Kind**: event emitted by [`Button`](#Button)