The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Yancy-1.085
River stage one • 3 direct dependents • 3 total dependents
43 ++
/ Yancy::Plugin::Form

NAME

Yancy::Plugin::Form - Generate form HTML using various UI libraries

VERSION

version 1.085

SYNOPSIS

    use Mojolicious::Lite;
    plugin Yancy => {
        backend => 'pg://localhost/mysite',
        read_schema => 1,
    };
    app->yancy->plugin( 'Form::Bootstrap4' );
    app->routes->get( '/people/:id/edit' )->to(
        'yancy#set',
        schema => 'people',
        template => 'edit_people',
    );
    app->start;
    __DATA__
    @@ edit_people.html.ep
    %= $c->yancy->form->form_for( 'people' );

DESCRIPTION

The Form plugins generate forms from JSON schemas. Plugin and application developers can use the form plugin API to make forms, and then sites can load a specific form library plugin to match the style of the site.

NOTE: This API is EXPERIMENTAL and will be considered stable in Yancy version 2.0. Please report any issues you have or features you'd like to see. Minor things may change before version 2.0, so be sure to read the release changelog before upgrading.

Available Libraries

HELPERS

All form plugins add the same helpers with the same arguments so that applications can use the form plugin that matches their site's appearance. Yancy plugin and app developers should use form plugins to build forms so that users can easily customize the form's appearance.

yancy->form->input

    my $html = $c->yancy->form->input( %args );
    %= $c->yancy->form->plugin( %args );

Create a form input. Usually one of a <input>, <textarea, or <select> element, but can be more.

%args is a list of name/value pairs with the following keys:

type

The type of the input field to create. One of the JSON schema types. See "Types" in Yancy::Guides::Schema for details on the supported types.

name

The name of the input. Required.

value

The value to show in the input. If not defined, will take the value from the current request parameters.

format

For string types, the format the string should take. One of the supported JSON schema formats, along with some additional ones. See "Types" in Yancy::Guides::Schema for details on the supported formats.

pattern

A regex pattern to validate the field before submit.

required

If true, the field will be marked as required.

readonly

If true, the field will be marked as read-only.

disabled

If true, the field will be marked as disabled.

placeholder

The placeholder for <input> and <textarea> elements.

id

The ID for this field.

class

A string with additional classes to add to this field.

minlength

The minimum length of the text in this field. Used to validate the form.

maxlength

The maximum length of the text in this field. Used to validate the form.

minimum

The minimum value for the number in this field. Used to validate the form.

maximum

The maximum value for the number in this field. Used to validate the form.

Most of these properties are the same as the JSON schema field properties. See "Declaring a Schema" in Yancy::Guides::Schema for details on how Yancy translates JSON schema into forms.

yancy->form->input_for

    my $html = $c->yancy->form->input_for( $schema, $property, %args );
    %= $c->yancy->form->input_for( $schema, $property, %args );

Create a form input for the given schema's property. This creates just the input field, nothing else. To add a label, see field_for.

%args is a list of name/value pairs with the following keys:

type
value
required
format
enum
enum_labels
class

yancy->form->filter_for

    my $html = $c->yancy->form->filter_for( $schema, $property, %args );
    %= $c->yancy->form->filter_for( $schema, $property, %args );

Create a form input suitable as a filter for the given schema's property. A filter input is never a required field, and always allows some kind of "blank" value. The filter automatically captures a value from the query parameter of the same name as the $property. This creates just the input field, nothing else.

Takes the same %args as "input_for", with the following changes:

  • required is always false

  • format is always removed, to allow for partial searches

  • 'boolean' type fields become enum fields with 'yes', 'no', and empty (either) options

yancy->form->field_for

    my $html = $c->yancy->form->field_for( $schema, $name, %args );
    %= $c->yancy->form->field_for( $schema, $name, %args );

Generate a field for the given $schema and property $name. The field will include a <label>, the appropriate input (<input>, <select>, or otherwise ), and any descriptive text. %args is a hash with the following keys:

title

The field's title. Defaults to the title defined for this property in the schema (see Yancy::Guides::Schema), or the field's name.

description

The field's description. Optional. Defaults to the description defined for this property in the schema (see Yancy::Guides::Schema).

class

A class to apply to the input element. See "input".

yancy->form->form_for

    my $html = $c->yancy->form->form_for( $schema, %args );
    %= $c->yancy->form->plugin( $schema, %args );

Generate a form to edit an item from the given $schema. The form will include all the fields, a CSRF token, and a single button to submit the form.

NOTE: For CSRF tokens to work, this must be called with the current controller, not with app. To disable CSRF (not recommended), pass csrf => 0 in %args.

%args is a list of name/value pairs with the following keys:

method

The method attribute for the <form> tag. Defaults to POST.

action

The action URL for the <form> tag.

item

A hashref of values to fill in the form. Defaults to the value of the item in the stash (which is set by "set" in Yancy::Controller::Yancy.)

properties

Arrayref of fields to show in this form. Defaults to the properties stash value (like the set action in Yancy::Controller::Yancy uses). Otherwise, defaults to showing all fields except read-only fields.

SEE ALSO

Yancy

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.