orchestra/html

HTML Component for Orchestra Platform

HTML Component for Orchestra Platform

HTML Component extends the functionality of Illuminate\Html with the extra functionality to including a chainable Form and Table builder. These set of functionality are the backbone in allowing extensions in Orchestra Platform to attach action to any existing form or table., _(*1)

, _(*2)

Version Compatibility

Installation

To install through composer, run the following command from terminal:, _(*3)

composer require "orchestra/html"

Configuration

Next add the service provider in config/app.php., _(*4)

'providers' => [

    // ...

    Orchestra\Html\HtmlServiceProvider::class,
],

Aliases

You might want to add the following to class aliases in config/app.php:, _(*5)

'aliases' => [

    // ...

    'Form' => Orchestra\Support\Facades\Form::class,
    'HTML' => Orchestra\Support\Facades\HTML::class,
    'Table' => Orchestra\Support\Facades\Table::class,
],

Usage

Orchestra\Html\HtmlBuilder is a small improvement from Illuminate\Html\HtmlBuilder., _(*6)

Advise to use this only when manipulating HTML outside of view, otherwise it's better (and faster) to use html., _(*7)

Create HTML

Create a HTML tag from within your libraries/extension using following code:, _(*8)

return HTML::create('p', 'Some awesome information');

Will return <p>Some awesome information</p>., _(*9)

You can customize the HTML attibutes by adding third parameter., _(*10)

return HTML::create('p', 'Another awesomeness', ['id' => 'foo']);

Will return <p id="foo">Another awesomeness</p>., _(*11)

Raw HTML Entities

Mark a string to be excluded from being escaped., _(*12)

return HTML::link('foo', HTML::raw('<img src="foo.jpg">'));

Will return <a href="foo"><img src="foo.jpg"></a>., _(*13)

This also can be dynamically done via., _(*14)

return HTML::link('foo', HTML::image('foo.jpg'));

Decorate HTML

Decorate method allow developer to define HTML attributes collection as HTML::attributes method, with the addition of including default attributes array as second parameter., _(*15)

return HTML::decorate(['class' => 'foo'], ['id' => 'foo', 'class' => 'span5']);

Will return array('class' => 'foo span5', 'id' => 'foo');., _(*16)

It also support replacement of default attributes if such requirement is needed., _(*17)

return HTML::decorate(['class' => 'foo !span5'], ['class' => 'bar span5']);

Will return array('class' => 'foo bar');, note that span5 is excluded when we give !span5 in the first parameter., _(*18)

Forms

Creating forms couldn't be any easier using Orchestra's HTML package. Let's get started., _(*19)

Creating a new Form

To create a new form, use the Form::of() method. The first parameter is simply a string to define what the form is for:, _(*20)

return Form::of('users');

Form Attributes

To customize your forms attributes, call the attributes($attributes) method on the FormGrid instance:, _(*21)

return Form::of('users', function ($form) {
    $attributes = [
        'method' => 'PATCH',
        'id'     => 'user-login-form',
        'class'  => 'form-horizontal',
    ];

    $form->attributes($attributes);
});

Specifying the Form layout

To specify the layout of the form, call the layout($view) method on the FormGrid instance:, _(*22)

return Form::of('users', function ($form) {
    $form->layout('layouts.form');
});

Adding Fields

To add fields to our form, we'll pass in a closure into the second parameter, and call the fieldset() method off of the injected FormGrid. Here's an example:, _(*23)

return Form::of('users', function ($form) {
    $form->fieldset(function ($fieldset) {
        $fieldset->control('input:text', 'username');
        $fieldset->control('input:email', 'email');
        $fieldset->control('input:password', 'password');
    });
});

Available Fields

// A text field
$form->control('input:text', 'name');

// A password field
$form->control('input:password', 'name');

// A file field
$fieldset->control('input:file', 'name');

// A textarea filed
$form->control('textarea', 'name');

// A select field
$form->control('select', 'name')
    ->options(['one', 'two', 'three']);

Adding Labels to Fields

To add a label onto a form control, use the method label():, _(*24)

$form->fieldset(function ($fieldset) {
    $form->control('input:text', 'username')
        ->label('Username');

    $form->control('input:email', 'email')
        ->label('Email');

    $form->control('input:password', 'password')
        ->label('Password');
});

Adding Default Values to Fields

To add a default value to the field, use the method value() on the form control:, _(*25)

$form->fieldset(function ($fieldset) {
    $form->control('input:text', 'username')
        ->label('Username')
        ->value(Auth::user()->username);

    $form->control('input:email', 'email')
        ->label('Email')
        ->value(Auth::user()->email);

    $form->control('input:password', 'password')
        ->label('Password');
});

Changing the submit button label

To change the submit button label, modify the FormGrid property submit like so:, _(*26)

return Form::of('users', function ($form) {
    // The form submit button label
    $form->submit = 'Save';

    $form->fieldset(function ($fieldset) {
        $form->control('input:text', 'username');
        $form->control('input:email', 'email');
        $form->control('input:password', 'password');
    });
});

Customizing the form control attributes

To customize the form controls attributes, call the attributes($attributes) method on the control:, _(*27)

$attributes = [
    'placeholder' => 'Enter your username',
    'class'       => 'form-control',
];

$form->control('input:text', 'username')
    ->attributes($attributes);

Customizing the form control itself

$form->control('input:email', 'email', function ($control) {
    $control->field(function ($row) {
        return "<input type='email' name="email" value='$row->email'>";
    });
});

You could also create a Renderable class:, _(*28)

use Illuminate\Contracts\Support\Renderable;

class EmailAddressField implements Renderable
{
    public function __construct($name, $value)
    {
        $this->name = $name;
        $this->value = $value;
    }

    public function render()
    {
        return sprintf('<input type="email" name="%s" value="%s">', $this->name, $this->value);
    }
}

And you can simply register it via:, _(*29)

$form->control('input:email', 'email', function ($control) {
    $control->field(function ($row) {
        return new EmailAddressField('email', $row->email);
    });
});

Displaying your form

To display your form, simply display it in your view with unescaped blade tags:, _(*30)

public function index()
{
    $form = Form::of('users', function ($form) {
        $form->fieldset(function ($fieldset) {
            $form->control('input:text', 'username');
            $form->control('input:email', 'email');
            $form->control('input:password', 'password');
        });
    });

    return view('index', compact('form'));
}

// In index.blade.php

{!! $form !!}