# Class: FileUpload

## LuCI .ui. FileUpload

The `FileUpload` class implements a widget which allows the user to upload, browse, select and delete files beneath a predefined remote directory.

UI widget instances are usually not supposed to be created by view code directly, instead they're implicitly created by `LuCI.form` when instantiating CBI forms.

This class is automatically instantiated as part of `LuCI.ui`. To use it in views, use `'require ui'` and refer to `ui.FileUpload`. To import it in external JavaScript, use `L.require("ui").then(...)` and access the `FileUpload` property of the class instance value.

#### new LuCI.ui.FileUpload(value, options)

ui.js, line 2705

  Instantiate a file upload widget.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `value` | string | Array.<string> | null | optional The initial input value.
  `options` | LuCI.ui.DynamicList.InitOptions |  | optional Object describing the widget specific options to initialize the file upload control.

### Extends

- LuCI.ui.AbstractElement

### Methods

#### inherited getValidationError(){string}

ui.js, line 166

  Returns the current validation error

  ##### Returns:

  Type | Description
  --- | ---
  string | The validation error at this time

#### inherited getValue(){string|Array.<string>|null}

ui.js, line 3199

  Read the current value of the input widget.

  ##### Returns:

  Type | Description
  --- | ---
  string | Array.<string> | null | The current value of the input element. For simple inputs like text fields or selects, the return value type will be a - possibly empty - string. Complex widgets such as `DynamicList` instances may result in an array of strings or `null` for unset values.

#### inherited isChanged(){boolean}

ui.js, line 141

  Check whether the input value was altered by the user.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the input value has been altered by the user or `false` if it is unchanged. Note that if the user modifies the initial value and changes it back to the original state, it is still reported as changed.

#### inherited isValid(){boolean}

ui.js, line 154

  Check whether the current input value is valid.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the current input value is valid or `false` if it does not meet the validation constraints.

#### inherited registerEvents(targetNode, synevent, events)

ui.js, line 215

  Dispatch a custom (synthetic) event in response to received events.

  Sets up event handlers on the given target DOM node for the given event names that dispatch a custom event of the given type to the widget root DOM node.

  The primary purpose of this function is to set up a series of custom uniform standard events such as `widget-update`, `validation-success`, `validation-failure` etc. which are triggered by various different widget specific native DOM events.

  Name | Type | Description
  --- | --- | ---
  `targetNode` | Node | Specifies the DOM node on which the native event listeners should be registered.
  `synevent` | string | The name of the custom event to dispatch to the widget root DOM node.
  `events` | Array.<string> | The native DOM events for which event handlers should be registered.

#### inherited render(){Node}

ui.js, line 2799

  Render the widget, set up event listeners and return resulting markup.

  ##### Returns:

  Type | Description
  --- | ---
  Node | Returns a DOM Node or DocumentFragment containing the rendered widget markup.

#### inherited setChangeEvents(targetNode, events)

ui.js, line 284

  Set up listeners for native DOM events that may change the widget value.

  Sets up event handlers on the given target DOM node for the given event names which may cause the input value to change completely, such as `change` events in a select menu. In contrast to update events, such change events will not trigger input value validation but they may cause field dependencies to get re-evaluated and will mark the input widget as dirty.

  Name | Type | Description
  --- | --- | ---
  `targetNode` | Node | Specifies the DOM node on which the event listeners should be registered.
  `events` | string | repeatable The DOM events for which event handlers should be registered.

#### inherited setPlaceholder(value)

ui.js, line 113

  Set the current placeholder value of the input widget.

  Name | Type | Description
  --- | --- | ---
  `value` | string | Array.<string> | null | The placeholder to set for the input element. Only applicable to text inputs, not to radio buttons, selects or similar.

#### inherited setUpdateEvents(targetNode, events)

ui.js, line 240

  Set up listeners for native DOM events that may update the widget value.

  Sets up event handlers on the given target DOM node for the given event names which may cause the input value to update, such as `keyup` or `onclick` events. In contrast to change events, such update events will trigger input value validation.

  Name | Type | Description
  --- | --- | ---
  `targetNode` | Node | Specifies the DOM node on which the event listeners should be registered.
  `events` | string | repeatable The DOM events for which event handlers should be registered.

#### inherited setValue(value)

ui.js, line 3204

  Set the current value of the input widget.

  Name | Type | Description
  --- | --- | ---
  `value` | string | Array.<string> | null | The value to set the input element to. For simple inputs like text fields or selects, the value should be a - possibly empty - string. Complex widgets such as `DynamicList` instances may accept string array or `null` values.

#### inherited triggerValidation()

ui.js, line 180

  Force validation of the current input value.

  Usually input validation is automatically triggered by various DOM events bound to the input widget. In some cases it is required though to manually trigger validation runs, e.g. when programmatically altering values.

### Type Definitions

#### LuCI.ui.FileUpload.InitOptionsLuCI.ui.AbstractElement.InitOptions

  In addition to the `AbstractElement.InitOptions` the following properties are recognized:

  ##### Properties:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `browser` | boolean | <optional> | false | Use a file browser mode.
  `show_hidden` | boolean | <optional> | false | Specifies whether hidden files should be displayed when browsing remote files. Note that this is not a security feature, hidden files are always present in the remote file listings received, this option merely controls whether they're displayed or not.
  `enable_upload` | boolean | <optional> | true | Specifies whether the widget allows the user to upload files. If set to `false`, only existing files may be selected. Note that this is not a security feature. Whether file upload requests are accepted remotely depends on the ACL setup for the current session. This option merely controls whether the upload controls are rendered or not.
  `enable_remove` | boolean | <optional> | true | Specifies whether the widget allows the user to delete remove files. If set to `false`, existing files may not be removed. Note that this is not a security feature. Whether file delete requests are accepted remotely depends on the ACL setup for the current session. This option merely controls whether the file remove controls are rendered or not.
  `enable_download` | boolean | <optional> | false | Specifies whether the widget allows the user to download files.
  `root_directory` | string | <optional> | /etc/luci-uploads | Specifies the remote directory the upload and file browsing actions take place in. Browsing to directories outside the root directory is prevented by the widget. Note that this is not a security feature. Whether remote directories are browsable or not solely depends on the ACL setup for the current session.