Aire API Overview

Aire is designed to be fluent and expressive. Methods are chainable when possible, and most things “just work” without too much effort.

Using the Aire facade or aire() helper

For the most part, everything is accessed via the Aire facade or the aire() helper method. All code examples from here on out will use the facade syntax, but the helper works exactly the same.

Most calls to Aire are passed down to the currently active form. The first call to any method will instantiate a new Form instance for you. All subsequent calls will be passed to that instance until you create a new form.

Opening a new Form

Typically, the first step to using Aire is to instantiate a new Form and open it. You can do that in a single call, with:

Aire::open($action = null, $bound_data = null)

You can instantiate a new form with Aire::form(), but in practice you'll rarely need this step.

Adding an Element to the Form

Aire provides most common form elements and has helper methods to quickly instantiate them. All elements are fluent, which means that configuring them is quick and easy.

The elements that Aire provides are:

• <form>
• <input>
• <select>
• <textarea>
• <button>

The Input element supports the following types:

• checkbox
• color
• date
• datetime
• datetime-local
• email
• file
• hidden
• image
• month
• number
• password
• radio
• range
• reset
• search
• submit
• tel
• text
• time
• url
• week

Aire also supports special RadioGroup and CheckboxGroup faux-elements that abstract away managing the values of individual radio buttons or multi-value checkboxes.

Each element and input type can be instantiated directly from the Aire facade or from the current Form instance.

{{ Aire::open() }}
			
{{ Aire::input('name', 'Your Name') }} {{-- Creates a text input --}}

{{ Aire::email('email_address', 'Your Email Address') }} {{-- Creates an email input --}}

{{ Aire::submit('Submit') }} {{-- Creates a button input with type="submit" --}}

{{ Aire::close() }}

Each helper method provides the most common properties as parameters. Below is an overview of each method signature:

• Aire::input($name = null, $label = null)
• Aire::hidden($name = null, $value = null)
• Aire::color($name = null, $label = null)
• Aire::date($name = null, $label = null)
• Aire::dateTime($name = null, $label = null)
• Aire::dateTimeLocal($name = null, $label = null)
• Aire::email($name = null, $label = null)
• Aire::file($name = null, $label = null)
• Aire::image($name = null, $label = null)
• Aire::month($name = null, $label = null)
• Aire::number($name = null, $label = null)
• Aire::password($name = null, $label = null)
• Aire::radio($name = null, $label = null)
• Aire::range($name = null, $label = null, $min = 0, $max = 100)
• Aire::search($name = null, $label = null)
• Aire::tel($name = null, $label = null)
• Aire::time($name = null, $label = null)
• Aire::url($name = null, $label = null)
• Aire::week($name = null, $label = null)
• Aire::button(string $label = null)
• Aire::submit(string $label = 'Submit')
• Aire::select(array $options, $name = null, $label = null)
• Aire::textArea($name = null, $label = null)
• Aire::checkbox($name = null, $label = null)

Summary Helper

Aire comes with a special element that can be added to your form using Aire::summary(). If you're using Laravel form validation, this element will show a short summary of the errors on the page, if any exist:

You can also add additional information to the summary block with Aire::summary()->verbose().

Element Groups

One of the major benefits of a form builder like Aire is that all the boilerplate markup that wraps around your form elements can be generated for you. All Aire elements are groupable, which allows you to associate things like a label, or help text to the element without worrying about additional markup.

Where it makes sense, elements are grouped by default. This means that Aire::input() can be passed a ->label() and it will just work. You can override these defaults by calling grouped() to enable grouping, or withoutGroup() to disable it. Groups provide a few additional methods to any element:

• label(string $text) sets the label text for the element
• helpText(string $text) adds help text/instructions below the element
• valid() marks the group as valid (this is usually handled automatically, but you have the option to manually set it if you like)
• invalid() marks the group as invalid (this is usually handled automatically, but you have the option to manually set it if you like)
• errors($message) adds a specific error message to be shown below the element
• prepend(string $text) prepends text inline before the element
• append(string $text) appends text inline after the element

Resourceful Helper

If you're using standard resourceful routing conventions, you can use the resourceful() helper. It take an instance of a model as its first parameter, and infers the route name, method, and model binding for you. For example, these examples are essentially the same:

{{ Aire::resourceful(User::find(1)) }}

{{ Aire::open()
	->route('users.update', 1)
	->bind(User::find(1))
	->put() }}

{{ Aire::resourceful(new User()) }}

{{ Aire::open()
	->route('users.store')
	->post() }}

This is particularly useful because you can use the same view partial for both your create and update views, and simple pass a new Model() into your create view.

By default, Aire will guess the route name based on the model. User will become users.store and users.update and so forth. If you need your own name, pass it as the second parameter:

{{ Aire::resourceful(User::find(1), 'people') }}

Now Aire will use people.store and people.update depending on the state of the model passed in.

If you're using a nested route, you can pass route parameters to prepend as the third option:

{{ Aire::resourceful($user, 'teams.users', [$team]) }}

Now Aire will use teams.users.update with [$team, $user] as the route parameters.

Variants

As of Aire 1.5.0 we now support variants like primary or sm:

{{ Aire::input()->variant('sm') }}

If you're just applying one variant, you can use the syntax above or do it fluently:

{{ Aire::input()->variant()->sm() }}

If you're applying multiple variants, use the variants() method:

{{ Aire::input()->variants('sm', 'blue') }}

When you define your variants, you can use (arbitrary) keys to manage conflict resolution. For example, if this were our config:

[
	'variant_classes' => [
		'input' => [
			'default' => [
				'border' => 'border',
				'size' => 'p-2 text-base rounded',
				'color' => 'border-gray-200',
			],
			'primary' => [
				'color' => 'border-blue-300',
			],
			'sm' => [
				'size' => 'p-1 text-sm rounded-sm',
			],
		],
	],
]

Using the keys color and size help us manage how variants('sm', 'primary') are applied (in this case, it would result in class="border p-1 text-sm rounded-sm border-blue-300").