README
LocalizedMultilineTextInput
Description
A controlled text input component for localized multi-line strings with validation states.
Installation
yarn add @commercetools-uikit/localized-multiline-text-input
npm --save install @commercetools-uikit/localized-multiline-text-input
Additionally install the peer dependencies (if not present)
yarn add react react-dom react-intl
npm --save install react react-dom react-intl
Usage
import LocalizedMultilineTextInput from '@commercetools-uikit/localized-multiline-text-input';
const Example = () => (
<LocalizedMultilineTextInput
value={{ en: 'House\nFoo', de: 'House' }}
onChange={
(/** event */) => {
// alert(event.target.name, event.target.value)
}
}
/>
);
export default Example;
Properties
Props | Type | Required | Default | Description |
---|---|---|---|---|
id |
string |
Used as prefix of HTML id property. Each input field id will have the language as a suffix (${idPrefix}.${lang} ), e.g. foo.en |
||
name |
string |
Used as HTML name property for each input field. Each input field name will have the language as a suffix (${namePrefix}.${lang} ), e.g. foo.en |
||
autoComplete |
string |
Used as HTML autocomplete property |
||
value |
Object See signature. |
✅ | Values to use. Keyed by language, the values are the actual values, e.g. { en: 'Horse', de: 'Pferd' }
The input doesn't accept a "languages" prop, instead all possible languages have to exist (with empty or filled strings) on the value: { en: 'foo', de: '', es: '' } |
|
onChange |
Function See signature. |
Gets called when any input is changed. Is called with the change event of the changed input.
Signature: (event) => void |
||
selectedLanguage |
string |
✅ | Specifies which language will be shown in case the LocalizedTextInput is collapsed. |
|
onBlur |
Function See signature. |
Called when input is blurred | ||
onFocus |
Function See signature. |
Called when input is focused | ||
defaultExpandMultilineText |
boolean |
Expands input components holding multiline values instead of collpasing them by default. | ||
hideLanguageExpansionControls |
boolean |
Will hide the language expansion controls when set to true . All languages will be shown when set to true . |
||
defaultExpandLanguages |
boolean |
Controls whether one or all languages are visible by default. Pass true to show all languages by default. |
||
isAutofocussed |
boolean |
Sets the focus on the first input when true is passed. |
||
isDisabled |
boolean |
Disables all input fields. | ||
isReadOnly |
boolean |
Disables all input fields and shows them in read-only mode. | ||
placeholder |
Object See signature. |
Placeholders for each language. Object of the same shape as value . |
||
horizontalConstraint |
union Possible values: , 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto' |
'scale' |
Horizontal size limit of the input fields. | |
hasError |
boolean |
Will apply the error state to each input without showing any error message. | ||
hasWarning |
boolean |
Will apply the warning state to each input without showing any error message. | ||
errors |
Object See signature. |
Used to show errors underneath the inputs of specific currencies. Pass an object whose key is a currency and whose value is the error to show for that key. | ||
warnings |
Object See signature. |
Used to show warnings underneath the inputs of specific currencies. Pass an object whose key is a currency and whose value is the warning to show for that key. |
Signatures
value
Signature {
[key: string]: string;
}
onChange
Signature () => void
onBlur
Signature () => void
onFocus
Signature () => void
placeholder
Signature {
[key: string]: string;
}
errors
Signature {
[key: string]: string;
}
warnings
Signature {
[key: string]: string;
}
props data-*
The component forwards all data
attribute props. It further adds a -${language}
suffix to the values of the data-test
and data-track-component
attributes, e.g data-test="foo"
will get added to the input for en
as data-test="foo-en"
.
Main Functions and use cases are:
- Receiving localized input from user
Static Properties
createLocalizedString(languages, existingTranslations)
This function creates a localized string. It merges the languages
and the language keys of existing translations to form a localized string holding all languages.
The existingTranslations
argument is optional. If it is not passed, an empty localized field will be created.
const languages = ['en', 'de'];
LocalizedMultilineTextInput.createLocalizedString(languages);
// -> { en: '', de: '' }
In case existingTranslations is passed, it will merge an empty localized field with the existing translations. Usually this is used to ensure that a localized string contains at least the project's languages.
const languages = ['en', 'de'];
const existingTranslations = { en: 'Tree', ar: 'شجرة' };
LocalizedMultilineTextInput.createLocalizedString(
languages,
existingTranslations
);
// -> { en: 'Tree', de: '', ar: 'شجرة' }
isEmpty(localizedField)
Returns true
when all values in a localized field are empty.
LocalizedMultilineTextInput.isEmpty({});
// -> true
LocalizedMultilineTextInput.isEmpty({ en: '', de: ' ' });
// -> true
LocalizedMultilineTextInput.isEmpty({ en: 'Tree', de: '' });
// -> false
omitEmptyTranslations(localizedField)
Omits translations with empty values.
LocalizedMultilineTextInput.omitEmptyTranslations({ en: '', de: ' ' });
// -> {}
LocalizedMultilineTextInput.omitEmptyTranslations({ en: 'Tree', de: '' });
// -> { en: 'Tree' }
isTouched(touched)
Expects to be called with an object or undefined
.
Returns true
when at least one value is truthy.
RequiredValueErrorMessage
This field exports a default error message which can be used when the field is required, but the user provided no value. You can use it as
render (
return (
<div>
<LocalizedMultilineTextInput hasError={isMissing} />
{
isMissing && <LocalizedMultilineTextInput.RequiredValueErrorMessage />
}
</div>
)
)