From 95def877dd50ca15ae751cfaeccdc05b14594c7c Mon Sep 17 00:00:00 2001 From: Gustavo Fenilli Date: Wed, 1 Nov 2023 22:53:14 -0300 Subject: [PATCH] docs: updates docs to follow new names --- README.md | 354 +++++++++++++++--------------------------------------- 1 file changed, 96 insertions(+), 258 deletions(-) diff --git a/README.md b/README.md index 259d9f7..f65c77b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

-# FormKit Inertia Integration +# Inertia Plugin GitHub Build Status @@ -12,68 +12,40 @@ Npm Version -This project aims to seamlessly integrate Inertia.js with FormKit forms, leveraging a robust event system that harnesses Inertia.js event callbacks and FormKit plugins for a smooth and powerful web development experience, and here is why: - -- Your time should be used on creating forms and backends, not integrations. -- Having an easy to install and use package, makes it so you don't need to care about packaging and publishing. +The `@formkit/inertia` plugin aims to seamlessly integrate Inertia.js with FormKit forms, leveraging a robust event system that harnesses Inertia.js event callbacks and FormKit plugins for a smooth and powerful web development experience. ### Table of Contents -1. [Quick Start](#quick-start) -2. [The Composable `useForm()`](#the-composable-useform) +1. [Installation](#installation) +2. [Usage](#usage) 1. [Method Calls](#method-calls) 2. [States](#states) 3. [Event Functions](#event-functions) -3. [Event System](#event-system) +3. [Event Callback Manager](#event-callback-manager) 4. [Roadmap](#roadmap) 5. [Types](#types) -## Quick Start - -First, you should already have a Laravel with InertiaJS application, you can check the docs on how [here](https://laravel.com/docs/10.x/starter-kits#breeze-and-inertia). +## Installation -You also should already have FormKit added to your vue application, you can check the docs on how [here](https://formkit.com/getting-started/installation). +To use the Inertia plugin we need to have a Laravel project already with Inertia Vue.JS installed and running you can check how by looking into the first sections of the guide [Using FormKit with Laravel Inertia](https://formkit.com/guides/using-formkit-with-laravel-inertia). -Now you have all requisites ready to use this package, you can install it with your preferred package manager. +Now you can install using your preferred package manager by following this bash command: ```bash npm install @formkit/inertia ``` -You should be able to to use the now available composable `useForm()`: - -```ts -import { useForm } from '@formkit/inertia' - -const form = useForm() -const submit = form.post('/login') +## Usage - - // The rest of your form goes here - -``` +To use the Inertia plugin we need to import the `useForm` function from `@formkit/inertia`, call the `useForm` function to receive the `form`, it comes with Inertia method calls, reactive states, the plugin event system, and the FormKit plugin. -And that is it, now you're ready to look more into the available features of this package, like the agnostic [event system]() and more about the [vue composable](). +The `useForm` function can take one optional argument: -

(back to top)

- -## The Composable `useForm()` - -To make integration between FormKit and Inertia easier we include a form helper composable designed to reduce the boilerplate needed for handling form submissions, it by default creates the event system, add method calls and reactive states, and it will also add default behaviours to FormKit forms like loading, disabling and setting errors that come from your backend. - -The `useForm()` accepts a single optional parameter that is the initial fields of your form: - -```ts -const form = useForm({ - email: 'foo@bar.baz', -}) -``` - -> Remember that for everything to work as expected you should add the returned plugin to FormKit: `:plugins="[form.plugin]"`. +- `initialFields`: The initial fields to be passed to your form. ### Method Calls -To submit the form, `useForm()` returns the methods `get`, `post`, `put`, `patch` and `delete`, any of those will return a suitable function that FormKit `@submit` expects. +The `useForm()` composable returns the methods `get`, `post`, `put`, `patch` and `delete`. All of these methods will return a suitable function for use as FormKit’s `@submit` handler. The easiest way to use it is by creating a new `const` with the resulting method of your choice: @@ -82,18 +54,18 @@ The easiest way to use it is by creating a new `const` with the resulting method import { useForm } from '@formkit/inertia' const form = useForm() - const submit = form.post('/login') + const submitHandler = form.post('/login') ``` -But you can also manually pass the variables to the returned function: +You could also also define the handler directly in your template: ```html Those will also remove any default events to that specific event, meaning that if you for example add `onStart` you will lose the events from `start` that are for example loading, disabling and processing. +> The `options` event callbacks will overwrite any default events to that specific event, meaning that if you for example add `onStart` you will lose the events from `start` that are for example loading, disabling and processing. ```html All FormKit based states will be null if `form.plugin` wasn't added to the FormKit form input. - -Those events can be helpful for example for disabling the form submit button if you're using your own submit instead of the provided FormKit one: - -> The `node` can be really helpful if you need the underlining [FormKit node](https://formkit.com/essentials/architecture). +The `useForm()` composable also returns reactive states. The Inertia ones are: `processing`, `progress`, `recentlySuccessful` and `wasSuccessful`, the FormKit based ones are `valid`, `errors`, `dirty` and `node`. For example, you could use the `processing` state to disable the form submit button while Inertia is processing the form (assuming that you’re using your own submit button): ```html