Usage

When creating a form, you'll be asked to select a template. This is the form that can be filled in by the end-user. For each submitted form, a VanOns\FilamentFormBuilder\Models\FormSubmission will be created.

To be able to set up and use a form, we must create at least 1 template to use.

Creating a template

You're free to set up form-templates as you want to, but there are a few requirements. Your form-template:

• must POST to a specific route: route('filament-form-builder.form.store', ['formId' => $form->id ]). $form being an instance of VanOns\FilamentFormBuilder\Models\Form.
• may have a form field submitter_email.
• may have a field return_url that will be used to redirect to, otherwise you'll be redirect to the page the form is on.
• may use the flashed 'submit_notification_type' and 'submit_notification_content' to display content on the page redirected to after submitting.

To get started, create a blade component for your form-template: php artisan make:component Forms/MyAwesomeForm.

After creating the component, make sure to extend the VanOns\FilamentFormBuilder\View\Components\FormComponent class, instead of the default Component class. When extending FormComponent you no longer need the __construct method in your class.

Make sure your form-template is constructed with an instance of VanOns\FilamentFormBuilder\Models\Form, this will be used in the action of the html form in your blade template:

use VanOns\FilamentFormBuilder\Models\Form;
use VanOns\FilamentFormBuilder\View\Components\FormComponent;
 
class MyAwesomeForm extends FormComponent
{
    public function render(): View|Closure|string
    {
        return view('components.forms.my-awesome-form');
    }
}

In your resources/views/components/forms/my-awesome-form.blade.php implement the form with the required items:

• The action pointing to the route filament-form-builder.form.store.
• The method being POST.
• A hidden field containing the url you want to be redirected to. (optional)
• A submitter_email field.

Example:

<div>
    <form method="POST" action={{ route('filament-form-builder.form.store', ['formId' => $form->id ]) }}>
        @csrf
        <input type="hidden" name="return_url" value="{{route('index')}}">
        <input type="text" name="submitter_email" value="">
        <input type="text" name="field1" value="">
        <input type="text" name="field2" value="">
        <button type="submit">send</button>
    </form>
</div>

Registering a template

To start registering templates, you must publish the config: php artisan vendor:publish --tag=filament-form-builder-config.

You can register your component in the templates array.

The key must be the component's class, the value is the label that the admin will see in the templates dropdown in the Filament Resource.

Using a form

To use a form simply add the provided component in your blade view, and give it an instance of VanOns\FilamentFormBuilder\Models\Form:

@php
    $myForm = VanOns\FilamentFormBuilder\Models\Form::first();
@endphp
 
<div>
    <x-render-form :form="$myForm" />
</div>

What this will do in the background is

• Take the form's template property, which is the class string of your configured template.
• Call Illuminate\Support\Facades\Blade::renderComponent(), with a new instance of the template class, passing it the form instance.
• Resulting in your template being rendered.

Validation, attributes & messages

Similar to a request, you can use the rules, attributes, and messages methods in your form component. These methods are used to validate the form data when it is submitted. Behind the scenes, these methods are used in a Request.

use VanOns\FilamentFormBuilder\Models\Form;
use VanOns\FilamentFormBuilder\View\Components\FormComponent;
 
class MyAwesomeForm extends FormComponent
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
        ];
    }
 
    public function attributes(): array
    {
        return [
            'name' => 'Full name',
        ];
    }
 
    public function messages(): array
    {
        return [
            'name.required' => 'Please enter your full name.',
        ];
    }
}

Placeholders

The placeholder method is used to show the user what placeholders can be when creating form notifications. You can choose to only add a key in this method, or add a key with a value. The value is used to set a fallback for when a field is not filled. By default, the fallback is -.

/**
 * @return array<string>
 */
public function placeholders(): array
{
    return [
        'name',
        'message' => 'No message',
    ];
}

Apart from the placeholders set in the form component, these placeholders are always available:

• form_title: The title of the form.
• all_fields: Adds all fields in the form, wrapped in a panel component, to the notification.

If for any reason you want to change the default placeholders, you can overwrite the $defaultPlaceholders variable set in a form component:

class MyAwesomeForm extends FormComponent
{
    public array $defaultPlaceholders = [
        'form_title',
    ];
}

Custom form builder

The custom form builder can be enabled/disabled by adding \VanOns\FilamentFormBuilder\View\Components\Forms\CustomForm::class => <label> to the templates array in the filament-form-builder.php config file.

Select the 'custom' template in filament if you want to build your own form. Choose what inputs you want to use in the form, and fill in the fields.

Fields

You can use the following fields:

• Input (text, number, email, phone)
• Select (multi)
• Checkbox
• Text area
• Submit (button)

You can also create your own fields:

1. Create a class that extends VanOns\FilamentFormBuilder\Filament\FormBuilder\Fields\FormField.
2. Set the view property to the path of your field's blade template (create this if it doesn't exist).
3. Add fields to the getFields method.
4. Add properties to your class that correspond to the field names.
5. Add the class to the filament-form-builder.php config file.

Tip: look in the existing fields for examples.

Dynamic visibility

You can set fields to be dynamically visible based on other field's values. To do this, fill the fields under the 'Visibility' section.

You must import the JavaScript for this to work. See JavaScript for more info.

Recaptcha

Enter your recaptcha keys in your .env file:

RECAPTCHA_ENABLED=true
RECAPTCHA_KEY=
RECAPTCHA_SECRET=

Then navigate to the form you want to use recaptcha on, and set the $recaptcha property to true. This adds the recaptcha rules to the form, if you don't do this, the captcha will not be validated.

class MyAwesomeForm extends FormComponent
{
    public bool $recaptcha = true;
}

Overwriting existing views

You can overwrite the views of the default fields by publishing the views: php artisan vendor:publish --tag=filament-form-builder-views.

This will publish the views to resources/views/vendor/filament-form-builder/components/fields, where you can then modify them.

Translations

This package comes with translation, they can be published with: php artisan vendor:publish --tag=filament-form-builder-translations.

The default for most files should be ok, one file to note is the fields.php file. You should register translations for each of your form's fields in there. The email that is sent out will look for a translation based on the field's name property.

Events

All models events can be hooked into:

FormSubmissions:

• VanOns\FilamentFormBuilder\Events\FormSubmission\FormSubmissionCreated::class
• VanOns\FilamentFormBuilder\Events\FormSubmission\FormSubmissionUpdated::class
• VanOns\FilamentFormBuilder\Events\FormSubmission\FormSubmissionDeleted::class
• VanOns\FilamentFormBuilder\Events\FormSubmission\FormSubmissionRestored::class
• VanOns\FilamentFormBuilder\Events\FormSubmission\FormSubmissionForceDeleted::class

Forms:

• VanOns\FilamentFormBuilder\Events\Form\FormCreated::class
• VanOns\FilamentFormBuilder\Events\Form\FormUpdated::class
• VanOns\FilamentFormBuilder\Events\Form\FormDeleted::class
• VanOns\FilamentFormBuilder\Events\Form\FormRestored::class
• VanOns\FilamentFormBuilder\Events\Form\FormForceDeleted::class

JavaScript

To enable dynamic visibility in the custom form builder, you need to import the JavaScript file provided by the package.

// app.js
import '../../vendor/van-ons/filament-form-builder/resources/js/form-builder.js';