Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zaceno/hyperapp-form
Utility library for plumbing forms with hyperapp
https://github.com/zaceno/hyperapp-form
Last synced: about 2 months ago
JSON representation
Utility library for plumbing forms with hyperapp
- Host: GitHub
- URL: https://github.com/zaceno/hyperapp-form
- Owner: zaceno
- License: mit
- Created: 2020-03-04T23:18:24.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-02-03T05:23:57.000Z (almost 2 years ago)
- Last Synced: 2024-04-25T22:20:17.470Z (8 months ago)
- Language: JavaScript
- Size: 272 KB
- Stars: 9
- Watchers: 4
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- hyperawesome - hyperapp-form - Eases the pain of validating & submitting forms (Utilities)
README
# Hyperapp-form
No matter what framework you're using, working with forms
can be frustrating. It often involves lots of plumbing that can feel pretty
tangential to the main logic of your app. This library tries to
alleviate some of this drudgery for developers using Hyperapp (v2)
## Getting it into your project
### ES Module import
You can simply import the form components as es-modules:
```js
import * as form from 'https://unpkg.com/hyperapp-form'
```
### NPM Package
Alternatively, install it as a dependency in your project
```sh
npm i hyperapp-form
```
and import the form components from the installed package:
```js
import * as form from 'hyperapp-form'
```
> This library has a peer dependency on hyperapp, so remember to also
> install hyperapp!
## Basics
### Initializing
A form using this library, needs to keep some state in the app's global state. Before rendering
the form, make sure to initialize the form state using the `init` function. Typically, in the
initial state of your app, or in the action that causes the form to be rendered
```js
const ShowForm = state => ({
...state,
page: 'form',
form: form.init(),
})
```
### The form component
When you render your form, rather than using a plain `` tag pair, use the `form`
component from this library instead.
```jsx
state => (
My form:
s.form}
setFormState={(s, x) => ({ ...s, form: x })}
onsubmit={HandleSubmittedForm}
>
... form contents here ...
)
```
You'll need to pass a handfull of props to the form, described below:
`state` is simply to tell the form its current state. However, we take care of updating the form state with actions under the hood. So we need to know how to get and set the form state in the actions as well. That is why you must pass `getFormState` and `setFormState`.
Finally, `onsubmit` is the action where you handle the result of a successfully submitted form. The data entered into the form will be passed as a key-value object in the payload of the action.
```js
const HandleSubmittedForm = (state, data) => [
state,
data.sendCopy &&
sendEmailEffect({
address: data.email,
message: data.message,
}),
]
```
### inputs
In order to get some data to your submit-handler, it needs to be entered in the form somewhere. Instead of adding a plain `` tag, add an `input` component.
```jsx
```
This component returns a regular `` tag with all the same properties you set on it, only wired to the `form` component that contains it. This is one of the core ideas of the library: to be as close as possible to writing a regular form in html, and not introduce any surprising elements in the DOM.
### Submitting
Buttons for submitting forms can also be added
```jsx
Submit
```
All that we've covered so far, is combined in a live runnable example you can try out (while inspecting the code) here: [https://zaceno.github.io/hyperapp-form/#flow/submitting](https://zaceno.github.io/hyperapp-form/#flow/submitting)
Go there, type "bar" in the input field then click submit. Notice two things:
- After the form was submitted, the input and submit-button became disabled. A form, once submitted, cannot be submitted again. You must initialize the state to render the form editable once more (Use the "Reset" button in the example to do this).
- The data submitted was: `{foo: "bar"}`. "bar" is the text you typed, and `foo` is because you typed it in an input with `name="foo"`.
### Validation On Submit
Most often you want the data submitted from a form to conform to certain rules. If the entered data is not conformant, you don't want the submission to go through, but to leave the form editable, with hints so users can correct it.
Visit [https://zaceno.github.io/hyperapp-form/#flow/validating](https://zaceno.github.io/hyperapp-form/#flow/validating) for an example.
Try typing some letters in the input box, and hit enter. Notice:
- The form did not submit. (The submitted value is still null)
- The form is still editable.
- The error message "Code must be six digits" is displayed.
- The input gets a red border and color.
This is all due to the `validator` prop on the input:
```jsx
```
where the `validcode` validator is defined as:
```js
const validcode = x =>
!!x && x.match(/^\d{6}$/) ? '' : 'Code must be six digits'
```
When a form is submitted, each validator attached to a `form.input` is called with the value for that input. If any the validators return a string message (or any truthy value in fact), we will _not_ call the `onsubmit` handler, and we leave the form open.
Moreover, each input whose validator returned an error message, will have "error" added to its class list.
The error message is displayed thanks to this component:
```jsx
```
It returns a virtual node representing the html:
```html
Some error message
```
If any of the validators returned a message, _one_ of those messages will be shown. The `p` tag is rendered always, but it is hidden until there is a message to show.
### Validation while editing
Validators also run as the user types in fields where there is an error. When the error is corrected, the "error" class is removed, and the error message dissapears.
And even if a form is not submitted, when the user blurs a field containing a bad value, that particular field is validated. We validate on blur so as not to unnecessarily annoy users.
The onblur validation only applies to text-style inputs (text, password, email et c). Others like radios, checkboxes, select-dropdowns are validated immediately when the value changes.
Give it a try!
### Forms with initial values
Sometimes the form is meant for changing a bunch of values already existing on the server. So we want all pre-existing values set on
the form from the beginning.
You can see how to do that in this example: [https://zaceno.github.io/hyperapp-form/#flow/initvals](https://zaceno.github.io/hyperapp-form/#flow/initvals)
Notice how we initialize the form with an object as the first argument:
```js
const init = {
submitted: null,
form: form.init({
foo: 'default value',
hidden: 'not editable',
}),
}
```
You will notice that the input has the value "default value" from the start. That is because the name of the input is `"foo"`.
You do not see the text "not editable" anywhere because there is no `form.input` with the name `"hidden"`. However, if you submit the form, you will see that both values were passed through to the onsubmit handler.
### Forms with initial errors
In the end, all the validation we do on the client side is just
to help the user produce sensible data to send to a server. The real validation happens there, and sometimes it finds problems the client side can't check for.
In those cases, we probably want to present the form again, with the values intact and an error message explaining what went wrong.
See the example [https://zaceno.github.io/hyperapp-form/#flow/initerrors](https://zaceno.github.io/hyperapp-form/#flow/initerrors)
The email input already has the "error" class from the start, and the error message is explaining that something went wrong server side. This, again, is because of how we initialized the form:
```js
const init = {
submitted: null,
form: form.init(
{
email: '[email protected]',
},
{
email: 'We could not verify your email, please double check it!',
}
),
}
```
As before, we are setting the "email" default value to an email address the user probably typed before. But we are also passing a second argument - these are the errors that the form should register from the start.
These initial errors will be cleared the first time a user validates the input or submits the form (when all inputs are validated).
## More Components
You've already encountered regular input components in the preceeding examples. But `` and `` work a bit differently. And there's a couple other components to look at while we're at it.
### Checkboxes
You render a checkbox by using the `form.input` component, with the `type="checkbox"` property. You should also give it a `name` property.
If the `name` of the checkbox is "foo", then if the form is submitted with the checkbox checked, the values submitted will have `{foo: 'on'}`. You can also assign a value, `value="bar"`, in which case the values would have `{foo: "bar"}`
If the form is submitted with multiple checkboxes having the same name, then the values will be listed as an array. For example, consider these:
```jsx
```
If the form is submitted with the 'a', 'c' and 'd' boxes checked, the values will have: `{foo: ['a', 'c', 'd']}`
Have a look at [https://zaceno.github.io/hyperapp-form/#components/checkboxes](https://zaceno.github.io/hyperapp-form/#components/checkboxes) for a more in-depth example.
Just like the other inputs, you can set a validator on checkboxes. Validators apply by name, so if you have multiple checkboxes with the same name, you don't need to set the validator on each of them, but it doesn't hurt either. Unlike text-style inputs, validation occurs immediately on input. Not on blur.
### Radio buttons
You render radiobuttins by setting `type="radio"` on a `form.input`. For radio buttons to make sense, there should be more than one having the same `name` but different values. For example if you have:
```jsx
```
Then only one of those can be checked at a time. The one (if any) that is checked when the form is submitted will also be the value submitted for name "foo".
Validation works the same as for checkboxes (see above).
For a more complete example see [https://zaceno.github.io/hyperapp-form/#components/radios](https://zaceno.github.io/hyperapp-form/#components/radios)
### Dropdown menus
To make a dropdown, do as you would with regular html and just replace the `` tag with the `form.select` component, e g:
```jsx
Select your age:
under 18
under 40
under 80
over 80
```
There is no special component for the `` or `` tags - just use the regular html-tags.
You can attach a `validator` to the `form.select` component as well. Like checkboxes and radio-buttons, validation happens immediately on input. Not on blur.
For a complete example, see: [https://zaceno.github.io/hyperapp-form/#components/select](https://zaceno.github.io/hyperapp-form/#components/select)
There is not yet any support for multi-selectable `select`s
### Buttons
You've already seen the `` component in the examples. If you need other buttons for other reasons among the children of your `form.form` component, then you would normally need to make sure to set `type="button"` on them (or they would also submit the form). You'd also need to handle disabling the buttons for submitted forms some other way. Instead you can simply use the `form.button` component with no type, and it will behave as you probably want:
```jsx
Click me
```
## Advanced
### Custom Form Inputs
Perhaps the standard fields aren't enough for you and you'd like to build a more complex type of input. You can do this with the `widget` function.
You call widget with: `form.widget(name, validator, renderer)` and it will return whatever you return from `renderer`. `renderer` is called with a set of props (computed from the form-props as well as `name` and `validator`) and should return a virtual-node which may use those props.
For a concrete example have a look at [https://zaceno.github.io/hyperapp-form/#advanced/custominput](https://zaceno.github.io/hyperapp-form/#advanced/custominput)
The props that the renderer is called with are:
- `value`: the current value for the given name,
- `error`: the current error for the given name,
- `Set`: an action which sets the value for the current name (give as payload)
- `Validate`: an action which validates the given payload and sets the error maybe for the given name.
- `disabled`: boolean if the widget should be disabled (because the form is already submitted)
> Notice you might want want to call the `Set` and `Validate` action in one go. To do that, we offer you the `form.batch` action utility. It's not form related but we use it internally so we might as well let you use it too. It defines one action from several. Dispatching `batch(a1, a2, a3)` is the same as dispatching actions a1, a2, a3 in succession (with the same payload, and no rendering in between).
### Context
The secret behind how this library works, is that the `form.form` component provides a _context_ to all the children and grandchildren. That is to say, there is an object of computed values and actions available anywhere in the tree below `form.form`. To define a component which can read the context, instead of returning a virtual-node from your component, return a function which returns the virtual-node. That function will be called with the context as argument.
```js
const MyFormAwareComponent = props => context => html`
...`
```
The context is an object with the following properties:
- `values`: all the current values of the form
- `SetValues`: action to set all the values of the form
- `errors`: all the current errors of the form
- `SetErrors`: action to set all the values of the form
- `submitted`: wether the form has been submitted or not
- `register`: a function for registering validators
The `register` function is how form widgets can register validators that will be called (reduced) before the form submits. A validator you register here has the signature: `currentErrors => newErrors`
One reason for using context could be to implement a more advanced
type of form-component that `widget` is not enough for. Another reason would be to implement components that visualize some calculation of the currently entered values as in this example (a box shows the color representation of the currently entered hue, saturation & lightness values): [https://zaceno.github.io/hyperapp-form/#advanced/custominfo](https://zaceno.github.io/hyperapp-form/#advanced/custominfo)
### Overriding Context
If you want more control over the widgets of a form, you can modify the context provided by using the `form.provide` function.
```js
form.provide({
register: ...
values: ...
errors: ...
submitted: ...
SetValues: ...
SetErrors: ...
},
[ ...children]
)
```
Technically, `provide` is not specifically for forms, and you could use it to provide any context to any parts of your app. But if you want to control behavior of components from hyperapp-form, you need to provide a context object that looks and behaves like how they expect.
An example of this can be found here: [https://zaceno.github.io/hyperapp-form/#advanced/custombehavior](https://zaceno.github.io/hyperapp-form/#advanced/custombehavior)