status-qml/sandbox/StatusInputPage.qml

104 lines
2.2 KiB
QML
Raw Normal View History

import QtQuick 2.14
import QtQuick.Controls 2.14
import QtQuick.Layouts 1.14
import StatusQ.Core 0.1
import StatusQ.Core.Theme 0.1
import StatusQ.Controls 0.1
feat(StatusInput): introduce new validator pipeline There's a new `validators` property that can be used to add validators to `StatusInput` instances, which are executed in the same order: ```qml StatusInput { text: "Some value" validators: [...] } ``` For convenience StatusQ provides some common validation methods, such as `StatusMinLengthValidator`, StatusMaxLengthValidator` and could be extended to other (e.g. email validation etc): ```qml StatusInput { text: "Some value" validators: [ StatusMinLengthValidator { minLength: 3 } ] } ``` Validators are executed every time the text of the input changes. They are executed in the same order they have been applied, which enables users to create cascading conditions like "First make sure the value is at least 3 characters long, then make sure it matches a certain pattern". When a validation fails, it sets the validity of the input (`valid: false`) accordingly and optionally exposes additional error information on `StatusInput.errors`: ```qml StatusInput { text: "Fo" onTextChanged: { if (errors) { /** * errors now has the following structure: * errors: { * minLength: { minValue: 3, actual: ... } * } * Also, `StatusInput` is now `valid = false` **/ errorMesssage = "Expected " + errors.minLenght.minValue + " but got: "+ errors.minLength.actual; // i18n'able } } validators: [ StatusMinLengthValidator { minLength: 3 } ] } ``` There can be any number of error objects on the `errors` property, depending on who many validators have been run that failed validation. Custom validators can be implemented by introducing a new `StatusValidator` type that has to implement a `validate()` function and defines the validators name. The `validate()` function has to return either `true` or `false` depending on whether the value is valid. Alternatively, the function can return an error object which gets exposed on the underlying input's `errors` property, at which point it's considered invalid as well. Here's a simple custom validator: ```qml // HelloValidator.qml import StatusQ.Controls.Validators 0.1 StatusValidator { property string name: "hello" validate: function (value) { // `value` is the `text` value of the underlying control return value === "hello" } } ``` Applying this validators would look like this: ```qml StatusInput { text: "Some value" validators: [ HelloValidator {} ] onTextChanged: { if (errors.hello) { errorMessage = "Doesn't say hello!" } } } ``` Alternatively, validators can return error objects to provide more information about what went wrong. Here's the implementation of the `StatusMinLengthValidator` as an example: ```qml StatusValidator { property int minLength: 0 name: "minLength" validate: function (value) { return value.length >= minLength ? true : { min: minLength, actual: value.length } } } ``` Because validators as components, they can hold any custom properties they need to be configured. There has been concern that, with this API, error messages need to be potentially defined in multiple places, given that there could be multiple instances of any validator. This is easily solved by having a centralized function figure out what the error message is, given a certain error object: ```qml StatusInput { validators: [ StatusMinLengthValidator { minLength: 3 } ] onTextChanged: { if (errors) { errorMessage = getErrorMessage(errors) // this function is provided by global or elsewhere } } } ``` Closes #298
2021-08-13 11:37:26 +00:00
import StatusQ.Controls.Validators 0.1
import Sandbox 0.1
Column {
spacing: 8
StatusInput {
input.placeholderText: "Placeholder"
}
StatusInput {
label: "Label"
input.placeholderText: "Disabled"
input.enabled: false
}
StatusInput {
input.placeholderText: "Clearable"
input.clearable: true
}
StatusInput {
input.placeholderText: "Invalid"
input.valid: false
}
StatusInput {
label: "Label"
input.icon.name: "search"
input.placeholderText: "Input with icon"
}
StatusInput {
label: "Label"
input.placeholderText: "Placeholder"
input.clearable: true
}
StatusInput {
charLimit: 30
input.placeholderText: "Placeholder"
input.clearable: true
}
StatusInput {
label: "Label"
charLimit: 30
input.placeholderText: "Placeholder"
input.clearable: true
}
StatusInput {
label: "Label"
charLimit: 30
errorMessage: "Error message"
input.clearable: true
input.valid: false
input.placeholderText: "Placeholder"
}
feat(StatusInput): introduce new validator pipeline There's a new `validators` property that can be used to add validators to `StatusInput` instances, which are executed in the same order: ```qml StatusInput { text: "Some value" validators: [...] } ``` For convenience StatusQ provides some common validation methods, such as `StatusMinLengthValidator`, StatusMaxLengthValidator` and could be extended to other (e.g. email validation etc): ```qml StatusInput { text: "Some value" validators: [ StatusMinLengthValidator { minLength: 3 } ] } ``` Validators are executed every time the text of the input changes. They are executed in the same order they have been applied, which enables users to create cascading conditions like "First make sure the value is at least 3 characters long, then make sure it matches a certain pattern". When a validation fails, it sets the validity of the input (`valid: false`) accordingly and optionally exposes additional error information on `StatusInput.errors`: ```qml StatusInput { text: "Fo" onTextChanged: { if (errors) { /** * errors now has the following structure: * errors: { * minLength: { minValue: 3, actual: ... } * } * Also, `StatusInput` is now `valid = false` **/ errorMesssage = "Expected " + errors.minLenght.minValue + " but got: "+ errors.minLength.actual; // i18n'able } } validators: [ StatusMinLengthValidator { minLength: 3 } ] } ``` There can be any number of error objects on the `errors` property, depending on who many validators have been run that failed validation. Custom validators can be implemented by introducing a new `StatusValidator` type that has to implement a `validate()` function and defines the validators name. The `validate()` function has to return either `true` or `false` depending on whether the value is valid. Alternatively, the function can return an error object which gets exposed on the underlying input's `errors` property, at which point it's considered invalid as well. Here's a simple custom validator: ```qml // HelloValidator.qml import StatusQ.Controls.Validators 0.1 StatusValidator { property string name: "hello" validate: function (value) { // `value` is the `text` value of the underlying control return value === "hello" } } ``` Applying this validators would look like this: ```qml StatusInput { text: "Some value" validators: [ HelloValidator {} ] onTextChanged: { if (errors.hello) { errorMessage = "Doesn't say hello!" } } } ``` Alternatively, validators can return error objects to provide more information about what went wrong. Here's the implementation of the `StatusMinLengthValidator` as an example: ```qml StatusValidator { property int minLength: 0 name: "minLength" validate: function (value) { return value.length >= minLength ? true : { min: minLength, actual: value.length } } } ``` Because validators as components, they can hold any custom properties they need to be configured. There has been concern that, with this API, error messages need to be potentially defined in multiple places, given that there could be multiple instances of any validator. This is easily solved by having a centralized function figure out what the error message is, given a certain error object: ```qml StatusInput { validators: [ StatusMinLengthValidator { minLength: 3 } ] onTextChanged: { if (errors) { errorMessage = getErrorMessage(errors) // this function is provided by global or elsewhere } } } ``` Closes #298
2021-08-13 11:37:26 +00:00
StatusInput {
label: "Label"
charLimit: 30
input.placeholderText: "Input with validator"
validators: [
StatusMinLengthValidator { minLength: 10 }
]
onTextChanged: {
if (errors && errors.minLength) {
errorMessage = `Value can't be shorter than ${errors.minLength.min} but got ${errors.minLength.actual}`
}
}
}
StatusInput {
input.multiline: true
input.placeholderText: "Multiline"
}
StatusInput {
input.multiline: true
input.placeholderText: "Multiline with static height"
input.implicitHeight: 100
}
StatusInput {
input.multiline: true
input.placeholderText: "Multiline with max/min"
input.minimumHeight: 80
input.maximumHeight: 200
}
}