NAME

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

VERSION

version 0.16

SYNOPSIS

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

# Mojolicious::Lite
plugin 'FormFieldsFromJSON';

DESCRIPTION

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

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',
});
```

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|Mojolicious::Plugin::FormFieldsFromJSON/Translation_method, too.
```
plugin 'FormFieldsFromJSON' => {
  template           => '<%= $label %>: <%= $field %>',
  translate_labels   => 1,
  translation_method => \&loc,
};
```
For more details see Translation|Mojolicious::Plugin::FormFieldsFromJSON/Translation.
translation_method

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

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="" />

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:

label
type
data
attributes

Attributes of the field like "class"

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" />