piral-forms
    TypeScript icon, indicating that this package has built-in type declarations

    0.14.9 • Public • Published

    Piral Logo

    Piral Forms · GitHub License npm version tested with jest Gitter Chat

    This is a plugin that only has a peer dependency to piral-core. What piral-forms brings to the table is a set of Pilet API extensions that can be used with piral or piral-core for exposing enhanced form capabilities.

    By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

    Why and When

    Quite often the management of forms is rather cumbersome. A form consists of multiple states, such as

    1. initial data loading (may be static / empty),
    2. handling of input (valid / invalid),
    3. submission of forms (in flight processing)
    4. (potentially async) handling of rejected forms (frontend was OK but backend complains)

    Full libraries such as Formik can be used to tackle (at least parts of) this problem, too, but piral-forms represents a very lightweight approach just leveraging what's there already and exposing it via the pilet API.

    Alternatives: Use known libraries exposed as shared libraries or rely on pilets to come up with their own solutions.

    Video

    We also have a video for this plugin:

    @youtube

    Documentation

    The following functions are brought to the Pilet API.

    createForm()

    Creates a new form container, which is an abstraction over a state container driven by the typical lifecycle of an input form.

    Returns a higher-order component for providing the form-related props such as error, submitting, changed, formData, setFormData(), submit(), reset(), or changeForm().

    Usage

    ::: summary: For pilet authors

    You can use the createForm function from the Pilet API to create a global state container managed form inside the Piral instance.

    Example use:

    import { PiletApi } from '<name-of-piral-instance>';
    import { MyPage } from './MyPage';
    
    export function setup(piral: PiletApi) {
      const withSimpleForm = piral.createForm({
        message: `Really lose the data?`,
        emptyData: {
          firstName: '',
          lastName: '',
        },
        onSubmit(data) {
          // return promise with data
        },
      });
      piral.registerPage('/sample-form', withSimpleForm(MyPage));
    }

    Calling createForm returns a higher-order component that injects new props from the FormProps<TFormData> interface into the component. These props contain among others a formData record and a submit function.

    :::

    ::: summary: For Piral instance developers

    The provided library only brings API extensions for pilets to a Piral instance.

    For the setup of the library itself you'll need to import createFormsApi from the piral-forms package.

    import { createFormsApi } from 'piral-forms';

    The integration looks like:

    const instance = createInstance({
      // important part
      plugins: [createFormsApi()],
      // ...
    });

    There are no options available.

    :::

    License

    Piral is released using the MIT license. For more information see the license file.

    Install

    npm i piral-forms

    Homepage

    piral.io

    DownloadsWeekly Downloads

    447

    Version

    0.14.9

    License

    MIT

    Unpacked Size

    93.8 kB

    Total Files

    66

    Last publish

    Collaborators

    • florianrappl