# XlReactWidgetString

This element helps you to create an input element for text in different variations:
1. Single line input element with visible text
2. Single line input element with hidden text (aka password)
3. Multi line input element with visible text
4. Multi line input element with hidden text 
5. Multi line input element with visible text based on Visual Studio Editor 

### Summary

* [Exports](#exports)
* [Playground](#playground)
* [Properties](#properties)
* [Example](#example)

### Exports
```
- XlReactWidgetString
- XlReactWidgetStringComponent
- XlReactWidgetStringMonacoEditor
```

### Playground

* [String Widget](https://xebialabs.github.io/xl-react-components/kitchen-sink.html#/widget/widgetString1)

## Properties

- **addons**  (node or array of nodes) - is added before and in line of the input component
- **className** (string) - that class name appends to the root class name of the component. That can be useful if you want 
to apply only for certain component specific CSS styles, but not for all of them. Plus it can be handful for e2e 
tests to rely on named input fields.
- **disabled** (boolean) - does not allow user neither to type nor select other value if is set as `true` 
- **displayMode** (string) - 3 options are available to choose: 
      _"creation"_ or _"edit"_ - allows to make changes
      _"display"_ - makes component readonly and user can only view the current value
- **inputIconRenderer** (function) - renders the icon on the left side inside of the input component. 
- **invalid** (bool) - if sets as `true` makes component invalid irrelevantly of validators outcome
- **message** (object) - overrides default warning/error message provided in validator with provided text here. 
The structure of the model is:
    - **show** (boolean): - the message will be displayed if is set as `true`
    - **text** (string): - the content of the message,
    - **type** (string): - the type of the message. Depends on the type the highlight of the message is different and 
    
    it also affects the validation. Currently we support 2 types of messages: _ERROR_ and _WARNING_.
    
    _ERROR_ type will force user to fix the issue and message will be highlighted in red color and the border of components as well
    
    _WARNING_ type only will notify the user regarding his mistakes, allow to proceed and the message will be highlighted
     in orange color and the border of components as well.
    
- **metadata** (object) - set of parameters of the element, namely:
    - **autocomplete** (boolean) - Default value is false. Tells the browser if that field can be re-filled again.
    That will happen only if user in prior saved that value in browser.  
    - **description** (string) - text under the input field, in case of error/warning, will be replaced with error/warning message
    - **label** (string) - text displayed on the left side from the element.
    - **name** (string) - gives HTML name to an element. It's important when component is a part of the form.
    - **placeholder** (string) - Hint shown to the user when input field is empty.
    - **required** (boolean) - forces user to fill in the field. Shows asterisk on the label side. In case of empty value makes element invalid.
    - **requiredDirection** (boolean) - Default value is 'right'. Possible values 'left' or 'right'. With that variable you can control where to display asterisk, on the left or right side of label.
    - **type** (string) - checks if that field equals to 'password', makes the value not visible to the user 
    - **size** (string) - Default value is `SMALL`. There are 3 options here:
        - **SMALL** (string) - renders usual input text HTML component.
        - **MEDIUM** (string) - renders text area with height of 72px
        - **LARGE** (string) -  renders text area with height of 126px
    - **view** (string) - Default value is `default`. There are 2 options here:
        - **default** (string) - will display input text or text area depending on other parameters.
        - **monaco** (string) - will display monaco editor regardless of other parameters. 
        Limitations: 
            * It can't work with 'password' mode.
            * You can't choose the size of monaco editor by parameter. Though you can affect it via CSS styles. 
- **model** (object) - controls the current value 
- **onKeyPress** (function) - triggers once user presses the key and being focused inside of this element. 
- **onMessageChange** (function) - triggers once message is changed.
- **onModelChange** (function) - triggers once model is changed.
- **onPristinityChange** (function) - triggers once pristinity is changed.
- **onValidityChange** (function) - triggers once validity is changed.
- **register** (function) - triggers when component is mounted. It contains a parameter *api*, which is an object containing 
 helpful component functions which you can invoke to do certain actions, namely
    - **applyDefaultModel** (function) - reverts back the default value to the component. For example if user has some stale changes and he wants to 
        reset it to the initial state.
    - **focus** (function) - changes the focus to this element.
    - **isPristine** (function) - checks the current state of the element.
    - **markAsDirty** (function) - changes the state of the element to not pristine.  
    - **resetPristinity** (function) - changes the state of the element to pristine. 
- **showParentMessages** (boolean) - if sets as `true` ignores own messages, but takes it from parent component. It is useful once you start.
- **validators** (function) - that's a function which returns back an array of triggers. Read more about structure of triggers below. Validators are 
called on every change of model. The result of the validators is to show if the component valid or not and providing a 
message to the user (error or warning). In case of many messages there is a priority rule. First shows error message, if all of them are solved - then warnings.
In case of many error (or warning messages) - first message will be shown.  

### Example
Example of `1. Single line input element with visible text`
```jsx

const searchInputIcon = () => <i className="xl-icon search-icon"/>;
const state = {model : 'John'};
const handleModelChange = (model) => this.setState({model});

<XlReactWidgetString
    className="user-name"
    inputIconRenderer={searchInputIcon}
    metadata={{label: 'Name', placeholder: 'User name'}}
    model={state.model}
    onModelChange={handleModelChange}
/>

```
