diff --git a/API.md b/API.md index fa1a198..667e468 100644 --- a/API.md +++ b/API.md @@ -12,6 +12,7 @@ - [onInvalidSubmit()](#oninvalidsubmit) - [onChange()](#onchange) - [reset()](#resetform) + - [getModel()](#getmodel) - [preventExternalInvalidation](#preventexternalinvalidation) - [Formsy.Mixin](#formsymixin) - [name](#name) @@ -45,13 +46,13 @@ ### Formsy.Form #### className -```html +```jsx ``` Sets a class name on the form itself. #### mapping -```javascript +```jsx var MyForm = React.createClass({ mapInputs: function (inputs) { return { @@ -77,7 +78,7 @@ Use mapping to change the data structure of your input elements. This structure #### validationErrors You can manually pass down errors to your form. In combination with `onChange` you are able to validate using an external validator. -```js +```jsx var Form = React.createClass({ getInitialState: function () { return { @@ -108,7 +109,7 @@ var Form = React.createClass({ ``` #### onSubmit(data, resetForm, invalidateForm) -```html +```jsx ``` Takes a function to run when the submit button has been clicked. @@ -116,37 +117,37 @@ Takes a function to run when the submit button has been clicked. The first argument is the data of the form. The second argument will reset the form. The third argument will invalidate the form by taking an object that maps to inputs. This is useful for server side validation. E.g. `{email: "This email is taken"}`. Resetting or invalidating the form will cause **setState** to run on the form element component. #### onValid() -```html +```jsx ``` Whenever the form becomes valid the "onValid" handler is called. Use it to change state of buttons or whatever your heart desires. #### onInvalid() -```html +```jsx ``` Whenever the form becomes invalid the "onInvalid" handler is called. Use it to for example revert "onValid" state. #### onValidSubmit(model, resetForm, invalidateForm) -```html +```jsx ``` Triggers when form is submitted with a valid state. The arguments are the same as on `onSubmit`. #### onInvalidSubmit(model, resetForm, invalidateForm) -```html +```jsx ``` Triggers when form is submitted with an invalid state. The arguments are the same as on `onSubmit`. #### onChange(currentValues, isChanged) -```html +```jsx ``` "onChange" triggers when setValue is called on your form elements. It is also triggered when dynamic form elements have been added to the form. The "currentValues" is an object where the key is the name of the input and the value is the current value. The second argument states if the forms initial values actually has changed. #### reset(values) -```html +```jsx var MyForm = React.createClass({ resetForm: function () { this.refs.form.reset(); @@ -162,8 +163,25 @@ var MyForm = React.createClass({ ``` Manually reset the form to its pristine state. You can also pass an object that inserts new values into the inputs. Keys are name of input and value is of course the value. +#### getModel() +```jsx +var MyForm = React.createClass({ + getMyData: function () { + alert(this.refs.form.getModel()); + }, + render: function () { + return ( + + ... + + ); + } +}); +``` +Manually get values from all registered components. Keys are name of input and value is of course the value. + #### preventExternalInvalidation -```html +```jsx var MyForm = React.createClass({ onSubmit: function (model, reset, invalidate) { invalidate({ @@ -184,20 +202,20 @@ With the `preventExternalInvalidation` the input will not be invalidated though ### Formsy.Mixin #### name -```html +```jsx ``` The name is required to register the form input component in the form. You can also use dot notation. This will result in the "form model" being a nested object. `{email: 'value', address: {street: 'value'}}`. #### value -```html +```jsx ``` You should always use the [**getValue()**](#getvalue) method inside your formsy form element. To pass an initial value, use the value attribute. This value will become the "pristine" value and any reset of the form will bring back this value. #### validations -```html +```jsx ``` Works just fine. #### validationError -```html +```jsx ``` The message that will show when the form input component is invalid. It will be used as a default error. #### validationErrors -```html +```jsx required -```html +```jsx ``` A property that tells the form that the form input component value is required. By default it uses `isDefaultRequiredValue`, but you can define your own definition of what defined a required state. -```html +```jsx ``` Would be typical for a checkbox type of form element that must be checked, e.g. agreeing to Terms of Service. #### getValue() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], render: function () { @@ -268,7 +286,7 @@ var MyInput = React.createClass({ Gets the current value of the form input component. #### setValue(value) -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -284,7 +302,7 @@ var MyInput = React.createClass({ Sets the value of your form input component. Notice that it does not have to be a text input. Anything can set a value on the component. Think calendars, checkboxes, autocomplete stuff etc. Running this method will trigger a **setState()** on the component and do a render. #### hasValue() - DEPRECATED -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -303,7 +321,7 @@ var MyInput = React.createClass({ The hasValue() method helps you identify if there actually is a value or not. The only invalid value in Formsy is an empty string, "". All other values are valid as they could be something you want to send to the server. F.ex. the number zero (0), or false. #### resetValue() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -322,7 +340,7 @@ var MyInput = React.createClass({ Resets to empty value. This will run a **setState()** on the component and do a render. #### getErrorMessage() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -341,7 +359,7 @@ var MyInput = React.createClass({ Will return the validation message set if the form input component is invalid. If form input component is valid it returns **null**. #### isValid() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -364,7 +382,7 @@ Returns the valid state of the form input component. #### isValidValue() You can pre-verify a value against the passed validators to the form element. -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -389,7 +407,7 @@ var MyForm = React.createClass({ ``` #### isRequired() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -409,7 +427,7 @@ var MyInput = React.createClass({ Returns true if the required property has been passed. #### showRequired() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -429,7 +447,7 @@ var MyInput = React.createClass({ Lets you check if the form input component should indicate if it is a required field. This happens when the form input component value is empty and the required prop has been passed. #### showError() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -449,7 +467,7 @@ var MyInput = React.createClass({ Lets you check if the form input component should indicate if there is an error. This happens if there is a form input component value and it is invalid or if a server error is received. #### isPristine() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -470,7 +488,7 @@ By default all formsy input elements are pristine, which means they are not "tou **note!** When the form is reset, using the resetForm callback function on for example [**onSubmit**](#onsubmitdata-resetform-invalidateform) the inputs are reset to their pristine state. #### isFormDisabled() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], render: function () { @@ -487,7 +505,7 @@ React.render(); You can now disable the form itself with a prop and use **isFormDisabled()** inside form elements to verify this prop. #### isFormSubmitted() -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], render: function () { @@ -504,7 +522,7 @@ var MyInput = React.createClass({ You can check if the form has been submitted. #### validate -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], changeValue: function (event) { @@ -528,7 +546,7 @@ You can create custom validation inside a form element. The validate method defi #### formNoValidate To avoid native validation behavior on inputs, use the React `formNoValidate` property. -```javascript +```jsx var MyInput = React.createClass({ mixins: [Formsy.Mixin], render: function () { @@ -543,7 +561,7 @@ var MyInput = React.createClass({ ### Formsy.HOC The same methods as the mixin are exposed to the HOC version of the element component, though through the `props`, not on the instance. -```js +```jsx import {HOC} from 'formsy-react'; class MyInput extends React.Component { @@ -560,7 +578,7 @@ export default HOC(MyInput); ### Formsy.Decorator The same methods as the mixin are exposed to the decorator version of the element component, though through the `props`, not on the instance. -```js +```jsx import {Decorator as FormsyElement} from 'formsy-react'; @FormsyElement() @@ -578,25 +596,25 @@ export default MyInput ### Formsy.addValidationRule(name, ruleFunc) An example: -```javascript +```jsx Formsy.addValidationRule('isFruit', function (values, value) { return ['apple', 'orange', 'pear'].indexOf(value) >= 0; }); ``` -```html +```jsx ``` Another example: -```javascript +```jsx Formsy.addValidationRule('isIn', function (values, value, array) { return array.indexOf(value) >= 0; }); ``` -```html +```jsx ``` Cross input validation: -```javascript +```jsx Formsy.addValidationRule('isMoreThan', function (values, value, otherField) { // The this context points to an object containing the values // {childAge: "", parentAge: "5"} @@ -604,13 +622,13 @@ Formsy.addValidationRule('isMoreThan', function (values, value, otherField) { return Number(value) > Number(values[otherField]); }); ``` -```html +```jsx ``` ## Validators **matchRegexp** -```html +```jsx @@ -618,116 +636,116 @@ Formsy.addValidationRule('isMoreThan', function (values, value, otherField) { Returns true if the value is thruthful **isEmail** -```html +```jsx ``` Return true if it is an email **isUrl** -```html +```jsx ``` Return true if it is an url **isExisty** -```html +```jsx ``` Returns true if the value is not undefined or null **isUndefined** -```html +```jsx ``` Returns true if the value is the undefined **isEmptyString** -```html +```jsx ``` Returns true if the value is an empty string **isTrue** -```html +```jsx ``` Returns true if the value is the boolean true **isFalse** -```html +```jsx ``` Returns true if the value is the boolean false **isAlpha** -```html +```jsx ``` Returns true if string is only letters **isNumeric** -```html +```jsx ``` Returns true if string only contains numbers. Examples: 42; -3.14 **isAlphanumeric** -```html +```jsx ``` Returns true if string only contains letters or numbers **isInt** -```html +```jsx ``` Returns true if string represents integer value. Examples: 42; -12; 0 **isFloat** -```html +```jsx ``` Returns true if string represents float value. Examples: 42; -3.14; 1e3 **isWords** -```html +```jsx ``` Returns true if string is only letters, including spaces and tabs **isSpecialWords** -```html +```jsx ``` Returns true if string is only letters, including special letters (a-z,ú,ø,æ,å) **equals:value** -```html +```jsx ``` Return true if the value from input component matches value passed (==). **equalsField:fieldName** -```html +```jsx ``` Return true if the value from input component matches value passed (==). **isLength:length** -```html +```jsx ``` Returns true if the value length is the equal. **minLength:length** -```html +```jsx ``` Return true if the value is more or equal to argument **maxLength:length** -```html +```jsx ``` Return true if the value is less or equal to argument