> For the complete documentation index, see [llms.txt](https://docs.silkbuilder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkbuilder.com/js_object/input.js.md).

# Input

The Input Class provides properties, methods, and events to interface with the HTML tags generated by the `<silk:Input>` tag.

**Kind**: global class

## Properties

| Name            | Type      | Description                                                                                             |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| columnID        | `String`  | The input's unique identifier. This would be the name of the dataProvider column if part of a Form tag. |
| $input          | `Object`  | The JQuery reference to the SILK Input HTML structure.                                                  |
| $filePreviewBt  | `Object`  | The JQuery reference to the preview button.                                                             |
| $fileDownloadBt | `Object`  | The JQuery reference to the donwload button.                                                            |
| selectedIndex   | `Integer` | The index of the last dataProvider's item in the case of type select and radio.                         |

## Constructor

### new Input(id, type, label, options, initValue)

Returns an Input instance.

| Param                        | Type      | Default                                             | Description                                                                                                                                                                                               |
| ---------------------------- | --------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                           | `String`  |                                                     | Unique identifier.                                                                                                                                                                                        |
| type                         | `String`  |                                                     | The input type: text, textarea, code, sql, js, css, xml, xhtml, html, date, time, datetime, select, numeric, integer, decimal, checkbox, button, options, radio, password, file, email, hidden, external. |
| label                        | `String`  |                                                     | The text used as the input's label.                                                                                                                                                                       |
| options                      | `Object`  |                                                     | Object containing the Input configuration options.                                                                                                                                                        |
| initValue                    | `String`  |                                                     | The value that the Input will hold when created.                                                                                                                                                          |
| \[options.columnID]          | `String`  |                                                     | The dataSource column name if different from the id parameter.                                                                                                                                            |
| \[options.description]       | `String`  |                                                     | The input's description only shows in editing mode.                                                                                                                                                       |
| \[options.descriptionPlace]  | `String`  |                                                     | The input's description position: top or bottom.                                                                                                                                                          |
| \[options.width]             | `String`  |                                                     | The width of the component in pixels or percentage.                                                                                                                                                       |
| \[options.height]            | `String`  | `200px`                                             | The input's height in case of the types: textarea, code, sql, js, css, xml, xhtml, and html.                                                                                                              |
| \[options.scrollHeight]      | `String`  |                                                     | The height limit of the component in read mode before the content needs scrolling.                                                                                                                        |
| \[options.dataSource]        | `String`  |                                                     | The dataProvider id in case of types: Select, options, and radio.                                                                                                                                         |
| \[options.required]          | `Boolean` | `false`                                             | The logic value or expression to determine if the component should be required before data submission.                                                                                                    |
| \[options.editable]          | `Boolean` | `true`                                              | The logic value or JavaScript expression to determine if the component should be visible.                                                                                                                 |
| \[options.visible]           | `Boolean` | `true`                                              | Expression to evaluate if the component should be visible.                                                                                                                                                |
| \[options.hideEmpty]         | `Boolean` | `false`                                             | Expression to evaluate if the component should be hidden when in read mode.                                                                                                                               |
| \[options.maxLength]         | `Integer` |                                                     | The number of characters the input will allow.                                                                                                                                                            |
| \[options.name]              | `String`  |                                                     | The "name" of the input if used under a regularHTML tag, if different than the ID.                                                                                                                        |
| \[options.scriptValue]       | `String`  |                                                     | Javascript expression returning the input's value.                                                                                                                                                        |
| \[options.scope]             | `String`  | `1`                                                 | The component end target. Check the setScope() method for values.                                                                                                                                         |
| \[options.mask]              | `String`  |                                                     | The input's entry mask or character filter. (<http://igorescobar.github.io/jQuery-Mask-Plugin/>)                                                                                                          |
| \[options.mode]              | `Boolean` | `false`                                             | True if editing, or false if read only.                                                                                                                                                                   |
| \[options.placeholder]       | `String`  |                                                     | The input's placeholder text, the helping text shown inside the text                                                                                                                                      |
| \[options.form]              | `String`  |                                                     | The parent Form. Undefined if operating standalone.                                                                                                                                                       |
| \[options.block]             | `Boolean` | `false`                                             | If the component is the end of a block. Next Inputs will start in a new line.                                                                                                                             |
| \[options.cssClass]          | `String`  |                                                     | The extra CSS classes to use with the input element.                                                                                                                                                      |
| \[options.inputClass]        | `String`  |                                                     | Extra CSS classes affecting the component.                                                                                                                                                                |
| \[options.valueColumn]       | `String`  |                                                     | Indicates the dataProvider's column containing the value to use in select, options, and radio.                                                                                                            |
| \[options.labelColumn]       | `String`  | `label`                                             | Indicates the dataProvider's column containing the label to use in select, options, and radio.                                                                                                            |
| \[options.linkColumns]       | `String`  |                                                     | Indicates the dataProvider's columns that will be updated in the dataSource. To use in select, options, and radio.                                                                                        |
| \[options.template]          | `String`  |                                                     | A HTML schema defining the component read view.                                                                                                                                                           |
| \[options.target]            | `String`  |                                                     | The HTML element in which the component will be rendered.                                                                                                                                                 |
| \[options.extraProperties]   | `String`  |                                                     | To add extra HTML properties to the                                                                                                                                                                       |
| \[options.htmlToolbar]       | `String`  |                                                     | The Quill menu array. To be used with type "html".                                                                                                                                                        |
| \[options.stringList]        | `String`  |                                                     | A JSON array which will serve as dataProvider for select, options, and radio. This array should contain objects with the properties' value and label.                                                     |
| \[options.prompt]            | `String`  |                                                     | The provided text will be added as an extra option to the select usually used to request a value selection.                                                                                               |
| \[options.promptValue]       | `String`  |                                                     | The value returned by the select "prompt" if the user selects it.                                                                                                                                         |
| \[options.filePreview]       | `String`  | `false`                                             | If the component will show a button to preview an uploaded file. To use with a input type file.                                                                                                           |
| \[options.fileDownload]      | `String`  | `false`                                             | If the component will show a button to download an uploaded file. To use with a input type file.                                                                                                          |
| \[options.filePreviewLabel]  | `String`  | `Preview`                                           | The label of the preview button. To use with a input type file.                                                                                                                                           |
| \[options.fileDownloadLabel] | `String`  | `Download`                                          | The label of the download button. To use with a input type file.                                                                                                                                          |
| \[options.fileUploadLabel]   | `String`  | `Drag and drop file here, or click to select file.` | The label of the upload button. To use with a input type file.                                                                                                                                            |
| \[options.filePreviewClass]  | `String`  | `btn-primary`                                       | The preview button Bootstrap class. To use with a input type file.                                                                                                                                        |
| \[options.fileDownloadClass] | `String`  | `btn-primary`                                       | The download button Bootstrap class. To use with a input type file.                                                                                                                                       |
| \[options.filePreviewIcon]   | `String`  | `fas fa-file`                                       | The preview button Font Awesome icon class. To use with a input type file.                                                                                                                                |
| \[options.fileDownloadIcon]  | `String`  | `fas fa-file-download`                              | The download button Font Awesome icon class. To use with a input type file.                                                                                                                               |
| \[options.uploadURL]         | `String`  |                                                     | The URL of the service uploading the file. To use with type file.                                                                                                                                         |
| \[options.fileTypeList]      | `String`  |                                                     | String containing the comma-separated list of accepted file extensions. To use with a input type file.                                                                                                    |
| \[options.fileSizeLimit]     | `Integer` |                                                     | The number of MB allowed to upload. To use with a input type file.                                                                                                                                        |
| \[options.timer]             | `Integer` | `0`                                                 | The number of milliseconds before triggering the "timer" event when entering data.                                                                                                                        |
| \[option.toggleList]         | `String`  |                                                     | The list of comma-separated elements that will be toggled together with the component.                                                                                                                    |
| \[option.autocomplete]       | `String`  |                                                     | Determines if the input should accept autocomlete. True by default.                                                                                                                                       |

## Methods

### cleanClasses()

Cleans the Input from markers like required, missing, and error.

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

### clear()

Clears the input value

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

### focus()

The method to focus the input when in editable mode.

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

### getEditable() ⇒ `Boolean`

Returns if the Input is editable.

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

### getID()

Returns the component's unique identifier.

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

### getInputID() ⇒ `String`

Returns the input element's ID.

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

### getItem() ⇒ `Object`

Returns the selected data dataProvider's item, or the value if the column is provided.

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

### getLabel() ⇒ `String`

Returns the Input's displayed label.

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

### getLinkedColumns() ⇒ `String`

Return the linked columns. These are the columns that will be updated into the Form's target dataSource.

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

### getMode() ⇒ `Boolean`

Returns the Input's mode.

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

### getPreviousValue() ⇒ `String`

Method to return the original Input value before editing started.

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

### getRequired() ⇒ `Boolean`

Returns if the Input is required.

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

### getScope() ⇒ `String`

Returns the Input's operational scope.

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

### getText() ⇒ `String`

Returns the Input's displayed read-only text.

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

### getType() ⇒ `String`

Returns the input's type.

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

### getValue() ⇒ `String`

Returns the Input's stored value.

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

### getVisible() ⇒ `Boolean`

Returns if the input is visible.

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

### hasChanged() ⇒ `Boolean`

Returns if the Input value has changed.

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

### hide()

Hides the

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

### load()

Executes the loading of data from the dataSource into the Input.

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

### markMissing()

Marks the Input as data missing.

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

### markRequired()

Marks the Input as required

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

### markValidationError()

Marks the Input as an entry error.

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

### on

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

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

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

### openSelect()

Method to programatically open a HTML Select input element

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

### setEnable(status)

Enables a disabled Input. If a parameter is provided, true enables it, and false disables it.

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

| Param  | Type      | Description             |
| ------ | --------- | ----------------------- |
| status | `Boolean` | Optional boolean value; |

### setLabel(label)

Sets the Input's label.

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

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

### setMask()

Sets Input's mask method following <http://igorescobar.github.io/jQuery-Mask-Plugin/docs.html>

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

### setMode(viewMode, setPreviousValue)

Sets the Input's interaction mode.

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

| Param            | Type      | Description                                                         |
| ---------------- | --------- | ------------------------------------------------------------------- |
| viewMode         | `Boolean` | True sets the input to editing, false sets the input tas read only. |
| setPreviousValue | `Boolean` | If true (default) will set the previous value.                      |

### setPreviousValue(value)

Method to set the Input's value before editing.

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

| Param | Type     | Description         |
| ----- | -------- | ------------------- |
| value | `String` | The value to apply. |

### setScope()

Sets the Input's operational scope. The values are: 0: Force send 1: If changed, go to DB (default) 2: If changed, go to DataProvider only 3: Stay in form

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

### setStringList(newList)

Sets the Input's dataSource using a JSON structure. The JSON's items should have at least the 'value' and 'label' properties.

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

| Param   | Type     | Description |
| ------- | -------- | ----------- |
| newList | `String` | JSON array. |

### setValue(value)

Changes the Input's stored value.

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

| Param | Type     | Description    |
| ----- | -------- | -------------- |
| value | `String` | The new value. |

### setVisible(visibleMode)

Sets the Input's visible status.

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

| Param       | Type      | Description         |
| ----------- | --------- | ------------------- |
| visibleMode | `Boolean` | The visible status. |

### show()

Shows the

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

### toggle(status)

Hides or shows the input based on the provided parameter.

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

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

### validate() ⇒ `Integer`

Executes a validation process. Returns 0 if no errors and 1 if errors are found.

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

## Events

### on:afterInit (Input)

This event is triggered after the Input element has been initialized. Created with the `Input.on("afterInit", function(Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| Input | `Object` | Reference to the Input. |

### on:afterLoad ($value)

This event is triggered after the Input's value has been loaded from the dataSource. Created with the `Input.on("afterLoad", function(){})` method.

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

| Param  | Type     | Description                                    |
| ------ | -------- | ---------------------------------------------- |
| $value | `Object` | The jQuery instance to the input HTML element. |

### on:afterUpload (input, status, response)

This event is triggered after a file is uploaded. Created with the `Input.on("afterUpload", function(Input, status, response){})` method. If the function returns false it will cancel the update process.

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

| Param    | Type      | Description                                                                                                                                                                                                    |
| -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| input    | `Object`  | Reference to the Input.                                                                                                                                                                                        |
| status   | `Boolean` | The upload process status: true is success and false is failure.                                                                                                                                               |
| response | `Object`  | If the operation was a success, it could return the response text or an object if the response is a JSON structure. If the operation returns an error, then this will contain the operation JavaScript object. |

### on:beforeUpload (input, formData, fileName, fileSize, file)

This event is triggered before a file is uploaded. Created with the `Input.on("beforeUpload", function(Input, formData, fileName, fileSize){})` method. If the function returns false it will cancel the update process.

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

| Param    | Type      | Description                          |
| -------- | --------- | ------------------------------------ |
| input    | `Object`  | Reference to the Input.              |
| formData | `Object`  | The form used to upload the file.    |
| fileName | `String`  | The name of the file to be uploaded. |
| fileSize | `Integer` | The file's size.                     |
| file     | `Object`  | The file element to be uploaded      |

### on:change (Input)

This event is triggered when the Input's value has changed. Created with the `Input.on("change", function(Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| Input | `Object` | Reference to the Input. |

### on:click (Input)

This event is triggered when a input type 'button' is clicked in data entry mode. Created with the `Input.on("click", function(Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| Input | `Object` | Reference to the Input. |

### on:clickDownload

This event is triggered when input's download button is clicked. Created with the `Input.on("clickDownload", function(){})` method.

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

### on:clickPreview

This event is triggered when input's preview button is clicked. Created with the `Input.on("clickPreview", function(){})` method.

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

### on:fileLoaded (Input, typeError, sizeError, file)

This event is triggered after the file extension and size has been validated. Created with the `Input.on("fileValidate", function(Input, typeError, sizeError){})` method.

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

| Param     | Type      | Description                                     |
| --------- | --------- | ----------------------------------------------- |
| Input     | `Object`  | Reference to the Input.                         |
| typeError | `Boolean` | True if the file extension type is not a match. |
| sizeError | `Boolean` | True if the size is beyond set bounderies.      |
| file      | `Object`  | The file element to be uploaded                 |

### on:fileValidate (Input, typeError, sizeError, file)

This event is triggered after the file extension and size has been validated and errors had been found. Created with the `Input.on("fileValidate", function(Input, typeError, sizeError){})` method.

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

| Param     | Type      | Description                                     |
| --------- | --------- | ----------------------------------------------- |
| Input     | `Object`  | Reference to the Input.                         |
| typeError | `Boolean` | True if the file extension type is not a match. |
| sizeError | `Boolean` | True if the size is beyond set bounderies.      |
| file      | `Object`  | The file element to be uploaded                 |

### on:filterLoad

This event is triggered before a row item is added to a list. If the function returns false, the item is ignored. This works for type select, options, and ratio. Created with the `Input.on("filterLoad", function(index,item){})` method.

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

### on:getValue ($value)

This event is triggered when the input's value is requested. If the event function returns a value this will become the returned value by the getValue method. Created with the `Input.on("getValue", function($value){})` method.

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

| Param  | Type     | Description                                    |
| ------ | -------- | ---------------------------------------------- |
| $value | `Object` | The jQuery instance to the input HTML element. |

### on:keydown (event, Input)

This event is triggered at input's keyboard keydown event. Created with the `Input.on("keydown", function(even,Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| event | `Object` | The Keyboard event.     |
| Input | `Object` | Reference to the Input. |

### on:keyup (event, Input)

This event is triggered at input's keyboard keyup event. Created with the `Input.on("keyup", function(even,Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| event | `Object` | The Keyboard event.     |
| Input | `Object` | Reference to the Input. |

### on:modeChange (mode, $text, $value)

This event is triggered when the Input's mode changes. Created with the `Input.on("modeChange", function(mode,$text,$vale){})` method.

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

| Param  | Type      | Description                                        |
| ------ | --------- | -------------------------------------------------- |
| mode   | `Boolean` | The set mode,                                      |
| $text  | `Object`  | JQuery reference to the input displayed text.      |
| $value | `Object`  | JQuery reference to the inputs input HTML element. |

### on:setValue (value, $value)

This event is triggered when the input's value is set. Created with the `Input.on("setValue", function(value, $value){})` method.

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

| Param  | Type     | Description                                    |
| ------ | -------- | ---------------------------------------------- |
| value  | `String` | The value entered.                             |
| $value | `Object` | The JQuery instance to the input HTML element. |

### on:timer (value, Input)

This event triggered when the input's data entry timer concludes. Created with the `Input.on("timer", function(value, Input){})` method.

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

| Param | Type     | Description             |
| ----- | -------- | ----------------------- |
| value | `String` | The input stored value. |
| Input | `Object` | Reference to the Input. |

### on:validation (type, value)

This event is triggered when an input is validated. If the event function returns false, the input will be marked an "invalid". Created with the `Input.on("validation", function(type,value){})` method.

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

| Param | Type     | Description                |
| ----- | -------- | -------------------------- |
| type  | `String` | The Input's type.          |
| value | `String` | The input's entered value. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.silkbuilder.com/js_object/input.js.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.