NAME

Mojolicious::Plugin::FormFieldsFromJSON - create form fields based on a definition in a JSON file

VERSION

version 1.02

SYNOPSIS

# Mojolicious
$self->plugin('FormFieldsFromJSON');

# Mojolicious::Lite
plugin 'FormFieldsFromJSON';

DESCRIPTION

Mojolicious::Plugin::FormFieldsFromJSON is a Mojolicious plugin.

NAME

Mojolicious::Plugin::FormFieldsFromJSON - create form fields based on a definition in a JSON file

VERSION

version 0.32

CONFIGURATION

You can configure some settings for the plugin:

dir

The directory where the json files for form field configuration are located

$self->plugin( 'FormFieldsFromJSON' => {
  dir => '/home/mojo/fields',
});

You can also pass an arrayreference with directory names. This will help when you store the JSON files where your templates are...

$self->plugin( 'FormFieldsFromJSON' => {
  dir => [
    '/home/mojo/templates/admin/json',
    '/home/mojo/templates/author/json',
    '/home/mojo/templates/guest/json',
  ]
});

template

With template you can define a template for the form fields.

$self->plugin( 'FormFieldsFromJSON' => {
  template => '<label for="<%= $id %>"><%= $label %>:</label><div><%= $field %></div>',
});

See Templates.

templates

With template you can define type specific templates for the form fields.

plugin 'FormFieldsFromJSON' => {
  templates => {
    text => '<%= $label %>: <%= $field %>',
  },
};

See Templates.

global_attributes

With global_attributes, you can define attributes that should be set for every field (except hidden fields)

plugin 'FormFieldsFromJSON' => {
  global_attributes => {
    class => 'important-field',
  },
};

So with this configuration

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name"
   },
   {
       "label" : "Background",
       "type" : "text",
       "name" : "background"
   }
]

You get

<input class="important-field" id="name" name="name" type="text" value="" />
<input class="important-field" id="background" name="background" type="text" value="" />

alias

Using aliases can help you a lot. Given you want to have several forms where the user can define a color (e.g. by using bootstrap-colorpicker), you don't want to define the special templates in each form. Instead you can define those fiels as type "color" and use an alias:

plugin 'FormFieldsFromJSON' => {
  template  => '<%= $label %>: <%= $field %>',
  templates => {
    color => '<%= $label %> (color): <%= $field %>',
  },
  alias => {
    color => 'text',
  },
};

The alias defines that "color" fields are "text" fields.

So with this configuration

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name"
   },
   {
       "label" : "Background",
       "type" : "color",
       "name" : "background"
   }
]

You get

<label for="name">Name:</label><div><input id="name" name="name" type="text" value="" /></div>
<label for="background">Background (color):</label><div><input id="background" name="background" type="text" value="" /></div>

translate_labels

If translate_labels is true, the labels for the templates are translated. You have to provide a translation_method, too.
```
plugin 'FormFieldsFromJSON' => {
  template           => '<%= $label %>: <%= $field %>',
  translate_labels   => 1,
  translation_method => \&loc,
};
```
For more details see Translation.
translation_method

If translate_labels is true, the labels for the templates are translated. You have to provide a translation_method, too.
```
plugin 'FormFieldsFromJSON' => {
  template           => '<%= $label %>: <%= $field %>',
  translate_labels   => 1,
  translation_method => \&loc,
};
```
For more details see Translation|Mojolicious::Plugin::FormFieldsFromJSON/Translation.
types

If you have written a plugin that implements a new "type" of input field, you can allow this type by passing types when you load the plugin.
```
plugin 'FormFieldsFromJSON' => {
  types => {
      'testfield' => 1,
  },
};
```
Now you can use
```
[
  {
    "label" : "Name",
    "type" : "testfield",
    "name" : "name"
  }
]
```
For more details see Additional Types.

HELPER

form_fields

form_fields returns a string with all configured fields "translated" to HTML.

$controller->form_fields( 'formname' );

Given this configuration:

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name"
   },
   {
       "label" : "City",
       "type" : "text",
       "name" : "city"
   }
]

You'll get

<input id="name" name="name" type="text" value="" />
<input id="city" name="city" type="text" value="" />

dynamic config

Instead of a formname, you can pass a config:

$controller->form_fields(
  [
    {
      "label" : "Name",
      "type" : "testfield",
      "name" : "name"
    }
  ]
);

This way, you can build your forms dynamically (e.g. based on database entries).

validate_form_fields

This helper validates the input. It uses the Mojolicious::Validator::Validation and it validates all fields defined in the configuration file.

For more details see Validation.

forms

This method returns a list of forms. That means the filenames of all .json files in the configured directory.

my @forms = $controller->forms;

The filenames are returned without the file suffix .json.

fields

fields() returns a list of fields (label or name).

my @fieldnames = $controller->fields('formname');

If your configuration looks like

[
  {
    "label" : "Email",
    "name"  : "email",
    "type"  : "text"
  },
  {
    "name"  : "password",
    "type"  : "password"
  }
]

You get

(
  Email,
  password
)

FIELD DEFINITIONS

This plugin supports several form fields:

text
checkbox
radio
select
textarea
password
hidden

Those fields have the following definition items in common:

name

The name of the field. If you do not pass an id for the field in the attributes-field, the name is also taken for the field id.
label

If a template is used, this value is passed for $label. If the translation feature is used, the label is translated.
type

One of the above mentioned types. Please note, that you can add own types.
data

For text, textarea, password and hidden this is the value for the field. This can be set in various ways:
1. Data passed in the code like
```
$c->form_fields( 'form', fieldname => { data => 'test' } );
```
2. Data passed via stash
```
$c->stash( fieldname => 'test' );
```
3. Data in the request

4. Data defined in the field configuration

5. Data passed via stash - part two
```
$c->stash( any_name => { fieldname => 'test' } );
$c->form_fields( 'form', from_stash => 'any_name' );
```
For select, checkbox and radio fields, data contains the possible values.
attributes

Attributes of the field like "class":
```
attributes => {
  class => 'button'
}
```
If global_attributes are defined, then the values are added, so that
```
plugin( 'FormFieldsFromJSON' => {
  global_attributes => {
    class => 'button-danger',
  }
});
```
and the attributes field as shown, then the field has two classes: button and button-danger. In the field the classes mentioned in field config come first.
```
<button class="button button-danger" ...>
```

EXAMPLES

The following sections should give you an idea what's possible with this plugin

text

With type text you get a simple text input field.

A simple text field

This is the configuration for a simple text field:

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name"
   }
]

And the generated form field looks like

<input id="name" name="name" type="text" value="" />

Set CSS classes

If you want to set a CSS class, you can use the attributes field:

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name",
       "attributes" : {
           "class" : "W75px"
       }
   }
]

And the generated form field looks like

<input class="W75px" id="name" name="name" type="text" value="" />

Text field with predefined value

Sometimes, you want to predefine a value shown in the text field. Then you can use the data field:

[
   {
       "label" : "Name",
       "type" : "text",
       "name" : "name",
       "data" : "default value"
   }
]

This will generate this input field:

<input id="name" name="name" type="text" value="default value" />