Helmut\Forms

A customisable and testable form abstraction library. Think of it as a request model on steroids. We all handle forms in different ways. Forms reduces the complexity and allows you focus on design. Use the included default fields, or build up your own library of reusable and testable fields, and drop them into every application you build.

• Makes forms testable
• Abstracts the request not the html
• Provides a model for reusing field components
• Design fields exactly the same way you normally would
• Render using mustache, twig, or blade
• Built in validation

Documentation

• Installation
• Usage
• API Reference
• Field Types
  • Button
  • Text
  • Name
  • Email
  • Number
  • Password
  • Paragraph Text
  • Checkbox
  • Checkboxes
  • Dropdown
  • Search
• Customisation
• Templates
• Language
• Plugins
• Autoloading
• Security
• License

Installation

To get the latest version of Forms, simply require the project using Composer:

$ composer require helmut/forms

Instead, you may of course manually update your require block and run composer update if you so choose:

{
    "require": {
        "helmut/forms": "~1.0"
    }
}

If you are using Laravel you need to register the service provider. Open up config/app.php and add the Helmut\Forms\Providers\Laravel::class key to the providers array.

Usage

Step 1

Create a class that extends \Helmut\Forms\Form.

// File: app/Forms/Form.php

namespace App\Forms;

class Form extends \Helmut\Forms\Form {

}

Step 2

Now you can create a form.

$form = new \App\Forms\Form;

Or in Laravel, simply type hint route or controller methods.

// File: app/Http/routes.php

Route::any('/', function(\App\Forms\Form $form) {

	// Now you can access $form

});

Step 2

Define fields to build the form.

$form->email('email')->label('Email Address')->required();
$form->password('password')->label('Password')->required();
$form->checkbox('remember')->label('Remember me');
$form->button('login')->label('Sign In');

Or alternatively you can create a class just for this specific form that extends \App\Forms\Form. Then fields can be defined within a define method and they will be added automatically.

// File: app/Forms/Login.php

namespace App\Forms;

class Login extends Form {

	public function define()
	{
		$this->email('email')->label('Email Address')->required();
		$this->password('password')->label('Password')->required();
		$this->checkbox('remember')->label('Remember me');
		$this->button('login')->label('Sign In');
	} 

}

Step 4

You can now render the form and handle submissions.

$form = new \App\Forms\Login;

if ($form->completed()) {

	// The form has been submitted and passed validation
}
	
echo $form->render();

Or in Laravel:

// File: app/Http/Controllers/LoginController.php

class LoginController extends Controller {
	
    public function handleLoginForm(\App\Forms\Login $form)
    {
    	if ($form->completed()) {

			// The form has been submitted and passed validation

        }

        return view('login.form', compact('form'));
    }

}

// File: resources/views/login/form.blade.php

@extends('template')

@section('content')

	<h3>Sign In</h3>

    {!! $form !!}

@endsection

Step 6

API Reference

These methods allow you to interact with your form:

	// Fields

	$form->button('register')					// Create a button
	$form->text('foo')							// Create a text field
	$form->name('foo')							// Create a name field
	$form->email('foo')							// Create an email field
	$form->number('foo')						// Create a numeric field
	$form->password('foo')						// Create a password field
	$form->paragraph_text('foo')				// Create paragraph text field
	$form->checkbox('foo')						// Create a checkbox field
	$form->checkboxes('foo')					// Create checkboxes field
	$form->dropdown('foo')						// Create dropdown field
	$form->search('foo')						// Create a search box field

	// Applying Modifiers

	$form->text('foo')->required()				// Make a field required
	$form->text('foo')->default('bar')			// Set a default value
	$form->checkbox('foo')->checked()			// Make it checked
	$form->checkbox('foo')->unchecked()			// Make it unchecked
	$form->dropdown('foo')->options([...])		// Add dropdown options

	// Pre-Filling

	$form->defaults($array)						// Load defaults from an array
	$form->defaults($user, $company, ...)		// Load defaults from model/s

	// Rendering

	$form->render() 							// Generate form
	$form->render('flat') 						// Generate form using flat templates

	// Processing

	$form->valid() 								// Validate the form
	$form->valid('name') 						// Validate a specific field
	$form->invalid() 							
	$form->invalid('name') 						
	$form->submitted() 							// Check if the form has been submitted
	$form->submitted('register') 				// Check if submitted using a specific button
	$form->completed() 							// Check if submitted and valid

	// Retrieving Values

	$form->all() 								// Get all the values
	$form->get('foo') 							// Get the foo field values
	$form->get('foo', 'bar') 					// Get the foo[bar] field value

	// Filling Models

	$form->fill($user) 							// Fills all fields in user model
	$form->fill($user, 'name')	 				// Fills just the name fields
	$form->fill($user, ['name', 'email'])	 	// Fills just the name and email fields

Field Types

These field types have been included by default:

button

$form->button('foo')->label('Foo')
$form->submitted('foo') // Returns true if form was submitted using this button
$form->completed('foo') // Returns true if form both submitted and valid

Example:

$form->button('signup')->label('Sign Up');

text

$form->text('foo')->label('Foo')->default('bar')->required()
$form->get('foo') // Returns 'bar'

Validations: between(min, max), min(num), max(num), alpha, alpha_num, alpha_dash, in(array), not_in(array)

Example:

$form->text('address')->label('Address')->required();

name

$form->name('foo')->label('Foo')->default(['first' => 'Bar', 'surname' => 'Baz'])->required()
$form->get('foo') // Returns ['foo_first' => 'Bar', 'foo_surname' => 'Baz', 'foo' => 'Bar Baz']
$form->get('foo', 'surname') // Returns 'Baz'

Example:

$form->name('name')->label('Name')->required();

email

$form->email('foo') // Same as `text` but with email validation added.

Example:

$form->email('email')->label('Email Address')->required();

number

$form->number('foo')->label('Foo')->default('123')->required()
$form->get('foo') // Returns '123'

Validations: between(min, max), min(num), max(num), integer, in(array), not_in(array)

Example:

$form->number('age')->label('Age')->integer()->min(18)->required();

password

$form->password('foo')->label('Foo')->required()
$form->get('foo') // Returns 'hashed_bar'
$form->password('foo')->matches('other_hash') // Returns true/false

Example:

$form->password('password')->label('Password')->required();

paragraph_text

$form->paragraph_text('foo')->label('Foo')->default('bar')->required()
$form->get('foo') // Returns 'bar'

Example:

$form->paragraph_text('comments')->label('Comments');

checkbox

$form->checkbox('foo')->label('Foo')->required()
$form->checkbox('foo')->checked() // Check the box
$form->checkbox('foo')->unchecked() // Uncheck the box
$form->get('foo') // Returns true/false

Example:

$form->checkbox('subscribe')->label('Subscribe to our newsletter');

checkboxes

$form->checkboxes('foo')->label('Foo')->options(['bar' => 'Bar', 'baz' => 'Baz'])->required()
$form->checkboxes('foo')->checked() // Check all the boxes
$form->checkboxes('foo')->checked(['bar']) // Check some of the boxes
$form->checkboxes('foo')->unchecked() // Uncheck all the boxes
$form->checkboxes('foo')->unchecked(['baz']) // Uncheck some of the boxes
$form->get('foo') // Returns ['foo_bar' => false, 'foo_baz' => false]

Example:

$form->checkboxes('interests')->label('Interests')->options(['golf' => 'Golf', 'swimming' => 'Swimming', 'dancing' => 'Dancing', 'reading' => 'Reading'])->required();

dropdown

$form->dropdown('foo')->label('Foo')->options(['bar' => 'Bar', 'baz' => 'Baz'])->default('baz')->required()
$form->get('foo') // Returns 'baz'

Example:

$form->dropdown('colour')->label('Colour')->options(['red' => 'Red', 'green' => 'Green', 'blue' => 'Blue']);

search

$form->search('foo')
$form->get('foo') // Returns ['foo' => 'bar', 'foo_button' => true]	

Example:

$form->search('search');

Customisation

Forms was designed as a framework upon which developers can build a library of modules to simplify the repetitive task of processing complex requests. A basic set of fields and templates are included, however the expectation is that you will use those as a starting point for customisation. By rolling your own, you can design, build and test them once, and drop them into any application.

• Creating fields
• Creating templates
• Creating plugins

Templates

A few basic template packages are provided by default that are compatible with common css frameworks such as Bootstrap and Foundation. These should provide a great base for customisation. Forms is compatible with CSS preprocessors and development of base templates for Jeet, Singularity and Neat are in the pipeline.

$form->setTemplate('bootstrap') 		// Default
$form->setTemplate('foundation')

$form->setTemplate('jeet')              // Coming soon...
$form->setTemplate('singularity')       // Coming soon...
$form->setTemplate('neat')              // Coming soon...

Languages

$form->setLanguage('en') 	// Set language to english
$form->setLanguage('es') 	// Idioma establecida en español

Plugins

$form->addPlugin('feedback');   // Instant validation feedback
$form->addPlugin('memory');   // Autosave as you type

Security

If you discover any security related issues, please email helmut.github [at] gmail.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

License

The MIT License (MIT). Please see License File for more information.