From da57f85c14356a801275840372266502cdef04fa Mon Sep 17 00:00:00 2001 From: dtrelogan Date: Sun, 23 Jul 2017 09:05:06 -0400 Subject: [PATCH] standard change handler --- docs/advantages.md | 2 +- docs/api.md | 18 +++++++++--------- docs/asyncExample.md | 2 +- docs/basicExample.md | 2 +- docs/deprecatedDatePickerExample.md | 4 ++-- docs/onBlurExample.md | 2 +- docs/onUpdateExample.md | 2 +- docs/updatingFormState.md | 12 ++++++------ docs/validationWiring.md | 2 +- 9 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/advantages.md b/docs/advantages.md index 5d6a05d..5e48962 100644 --- a/docs/advantages.md +++ b/docs/advantages.md @@ -47,7 +47,7 @@ validateConfirmNewPassword(confirmationValue, context) { } ``` -and you can override the framework generated change handler using a simple API: +and you can override the standard change handler using a simple API: ```jsx diff --git a/docs/api.md b/docs/api.md index 7beaa26..83b0d43 100644 --- a/docs/api.md +++ b/docs/api.md @@ -101,7 +101,7 @@ a Field is a representation of a rendered input component. if you define an inpu /> ``` -a framework object is created with the following properties: +a Field instance is created with the following properties: ```es6 { @@ -181,9 +181,9 @@ defines a default value for your input. values will be [coerced](#FieldState.get if a model is [injected](#FormState.injectModel) into form state, the model value takes precedence over the default value. *be careful*: when inputs do not align exactly with your backing model, some inputs could receive an initial value from the injected model while other unaligned inputs could receive the configured default value. this could be a source of confusion and/or bugs during development. -do not confuse this property with the defaultValue for a react [uncontrolled component](https://facebook.github.io/react/docs/forms.html#uncontrolled-components). input components managed by the framework are [controlled components](https://facebook.github.io/react/docs/forms.html#controlled-components). always supply a value property to your inputs. +do not confuse this property with the defaultValue for a react [uncontrolled component](https://facebook.github.io/react/docs/forms.html#uncontrolled-components). input components managed by react-formstate are [controlled components](https://facebook.github.io/react/docs/forms.html#controlled-components). always supply a value property to your inputs. -note: if you are using the DEPRECATED framework generated 'updateFormState' change handler, for select-multiple and checkbox group inputs *always* supply an array default value in your jsx. you must do this because otherwise the framework has no idea whether your component contains a text input or a select input. it is better to use the new 'handleValueChange' handler where this is no longer a concern. +note: if you are using the DEPRECATED 'updateFormState' change handler, for select-multiple and checkbox group inputs *always* supply an array default value in your jsx. you must do this because otherwise the react-formstate has no idea whether your component contains a text input or a select input. it is better to use the new 'handleValueChange' handler where this is no longer a concern. ### revalidateOnSubmit @@ -559,7 +559,7 @@ the following deprecated prop is also passed: - updateFormState: the DEPRECATED onChange handler for your input component (takes an event parameter) -note: for asynchronous validation you must override the framework generated handleValueChange handler. see an example [here](/docs/asyncExample.md) +note: for asynchronous validation you must override the handleValueChange handler. see an example [here](/docs/asyncExample.md) FormObjects and FormArrays pass the following properties to nested FormObjects and FormArrays. @@ -913,11 +913,11 @@ let value = this.formState.getu('x'); ### void onUpdate(function callback) -sets a callback from the framework generated onChange handler. +sets a callback from the standard handleValueChange onChange handler. -if you add an onUpdate callback, be sure to call context.updateFormState in your callback, as the framework delegates that responsibility. +if you add an onUpdate callback, be sure to call context.updateFormState in your callback, as react-formstate delegates that responsibility. -if you override the framework generated event handler for any of your fields, remember to call your onUpdate callback from your change handler. +if you override the standard event handler for any of your fields, remember to call your onUpdate callback from your change handler. an onUpdate callback may only be added to a root form state instance (i.e., not a nested one). @@ -988,9 +988,9 @@ handleSubmit(e) { } ``` -the framework can perform common transformations for you. see [noTrim](#Field.noTrim), [preferNull](#Field.preferNull), and [intConvert](#Field.intConvert) +react-formstate can perform common transformations for you. see [noTrim](#Field.noTrim), [preferNull](#Field.preferNull), and [intConvert](#Field.intConvert) -note that createModel is meant to run *synchronously*. if an asynchronous validation were triggered directly by a form submission, the user would have to hit the submit button again after validation completes. this is not seen as a limitation of the framework, however, as a field with an asynchronous validation is typically accompanied by a synchronous required field validation. maybe there is a legitimate use case that would suggest enhancement in this regard, but it is not currently understood by the author. +note that createModel is meant to run *synchronously*. if an asynchronous validation were triggered directly by a form submission, the user would have to hit the submit button again after validation completes. this is not seen as a limitation of react-formstate, however, as a field with an asynchronous validation is typically accompanied by a synchronous required field validation. maybe there is a legitimate use case that would suggest enhancement in this regard, but it is not currently understood by the author. ### FieldState get(string name) diff --git a/docs/asyncExample.md b/docs/asyncExample.md index ac8fdef..f01e50f 100644 --- a/docs/asyncExample.md +++ b/docs/asyncExample.md @@ -33,7 +33,7 @@ export default class UserForm extends Component { disabled = true; } - // notice we are overriding the framework-generated handleValueChange prop for username + // notice we are overriding the standard handleValueChange prop for username // also notice username is still marked required. // this will prevent a valid form submission before the user enters anything. diff --git a/docs/basicExample.md b/docs/basicExample.md index 216e0ab..470d289 100644 --- a/docs/basicExample.md +++ b/docs/basicExample.md @@ -91,7 +91,7 @@ export default class ChangePasswordForm extends Component { } - // you can override the framework generated change handler if necessary + // you can override the standard change handler generated by react-formstate if necessary handlePasswordChange(newPassword) { const context = this.formState.createUnitOfWork(); context.set('newPassword', newPassword).validate(); diff --git a/docs/deprecatedDatePickerExample.md b/docs/deprecatedDatePickerExample.md index e6ab204..b7dffe1 100644 --- a/docs/deprecatedDatePickerExample.md +++ b/docs/deprecatedDatePickerExample.md @@ -11,7 +11,7 @@ for problem #2, the best solution may vary depending on use case. four methods a ## method 1 - override the change handler -the most straightforward way to deal with a nonstandard input is to override the framework generated event handler: +the most straightforward way to deal with a nonstandard input is to override the standard event handler: ```es6 import React, { Component } from 'react'; @@ -140,7 +140,7 @@ since this feature will frequently be used in tandem with 'noCoercion', you can another approach is to wrap the nonstandard event handler to make it act as if it returns an event like a normal html input. -the framework generated event handler only looks at e.target.type and e.target.value. e.target.type is only important so much as it's not 'checkbox' or 'select-multiple'. +the standard event handler only looks at e.target.type and e.target.value. e.target.type is only important so much as it's not 'checkbox' or 'select-multiple'. ```es6 import React, { Component } from 'react'; diff --git a/docs/onBlurExample.md b/docs/onBlurExample.md index 35d1888..48943ab 100644 --- a/docs/onBlurExample.md +++ b/docs/onBlurExample.md @@ -136,7 +136,7 @@ The best way to understand what this does is to play with the [demo](https://dtr ## Overriding showValidationMessage -Like 'handleValueChange', 'showValidationMessage' is another framework generated handler prop. You can always override it if necessary: +Like 'handleValueChange', 'showValidationMessage' is another standard handler prop generated by react-formstate. You can always override it if necessary: ```jsx diff --git a/docs/onUpdateExample.md b/docs/onUpdateExample.md index 0e1cf23..cbb4126 100644 --- a/docs/onUpdateExample.md +++ b/docs/onUpdateExample.md @@ -14,7 +14,7 @@ export default class LoginForm extends Component { this.formState = new FormState(this); this.state = {}; - // set a callback from the framework generated onChange handler + // set a callback from the standard onChange handler this.formState.onUpdate(this.onUpdate.bind(this)); this.handleSubmit = this.handleSubmit.bind(this); diff --git a/docs/updatingFormState.md b/docs/updatingFormState.md index 4d920e7..a36e368 100644 --- a/docs/updatingFormState.md +++ b/docs/updatingFormState.md @@ -1,6 +1,6 @@ # Updating form state -## The framework generated change handler +## The standard change handler If you provide a 'formField' prop to an element nested within a react-formstate 'Form' element, react-formstate considers it an input meant to capture a value and generates additional props for the element. @@ -20,8 +20,8 @@ const RfsInput = ({fieldState, handleValueChange, ...other}) => { ``` ```jsx render() { - // A framework generated change handler is provided - // to both the name input and the address.city input. + // A standard change handler generated by react-formstate is + // provided to both the name input and the address.city input. // The generated handler prop is named 'handleValueChange' return ( @@ -34,7 +34,7 @@ render() { } ``` -The 'handleValueChange' prop represents the framework generated change handler. Using the standard handler will normally save you time and effort, but you can always override it if necessary. +The 'handleValueChange' prop represents the standard change handler. Using the standard handler will normally save you time and effort, but you can always override it if necessary. To demonstrate, let's build a custom handler and pass it to the 'name' input. @@ -96,7 +96,7 @@ and that's the crux of react-formstate. It's simple, really. Sophisticated user experiences sometimes require updating form state whenever *any* input is updated. -It might be handy, then, to be aware of the existence of the 'onUpdate' callback from the framework generated change handler. (The custom handler above is more or less the implementation of the standard handler, but not entirely.) +It might be handy, then, to be aware of the existence of the 'onUpdate' callback from the standard change handler. (The custom handler above is more or less the implementation of the standard handler, but not entirely.) An advanced example of using the 'onUpdate' callback is provided [here](onUpdateExample.md). @@ -384,7 +384,7 @@ If you find a need for react-formstate to revalidate a particular field during c /> ``` -but consider that between a custom change handler, or the [onUpdate callback](onUpdateExample.md) from the framework generated handler, there is likely a better solution. +but consider that between a custom change handler, or the [onUpdate callback](onUpdateExample.md) from the standard handler, there is likely a better solution. For instance, in the case of a password confirmation: diff --git a/docs/validationWiring.md b/docs/validationWiring.md index d69a459..19c5f7c 100644 --- a/docs/validationWiring.md +++ b/docs/validationWiring.md @@ -251,4 +251,4 @@ Enjoy! ### asynchronous validation -All validation functions documented in this section are intended to be callbacks for the framework generated event handler. They should be *synchronous*. Asynchronous validation should instead override the event handler. An example is provided [here](/docs/asyncExample.md) +All validation functions documented in this section are intended to be callbacks for the standard event handler. They should be *synchronous*. Asynchronous validation should instead override the event handler. An example is provided [here](/docs/asyncExample.md)