README

This package provides a custom CEP form field commonly used in Brazilian's web applications integrated with ViaCep, BrasilAPI and AwesomeAPI web services.

Filament Compatibility

Compatible with Filament v4 and above.

Installation

You can install the package via composer:

composer require otavio-araujo/filament-easy-ptbr-form-fields

Basic Usage

The custom field searches for CEP and fills up the form fields with the data returned by the web service.

By default, the fields that will be filled up are:

street;
neighborhood;
city;
state;
state_code;
ibge_code;
country;
and country_code.

public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                CepField::make('postal_code'),

                TextInput::make('street'),
                TextInput::make('neighborhood'),
                TextInput::make('city'),
                TextInput::make('state'),
                TextInput::make('state_code'),
                TextInput::make('ibge_code'),
                TextInput::make('country'),
                TextInput::make('country_code'),
                TextInput::make('number'),
            ]);
    }

Using Custom Field Names

If you want to customize the fields that will be filled up, you can chain on the following methods:

public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                CepField::make('postal_code')
                    ->setStreetField('custom_street')
                    ->setNeighborhoodField('custom_neighborhood')
                    ->setCityField('custom_city')
                    ->setStateField('custom_state')
                    ->setStateCodeField('custom_state_code')
                    ->setIbgeCodeField('custom_ibge_code')
                    ->setCountryField('custom_country')
                    ->setCountryCodeField('custom_country_code'),

                TextInput::make('custom_street'),
                TextInput::make('custom_neighborhood'),
                TextInput::make('custom_city'),
                TextInput::make('custom_state'),
                TextInput::make('custom_state_code'),
                TextInput::make('custom_ibge_code'),
                TextInput::make('custom_country'),
                TextInput::make('custom_country_code'),
                TextInput::make('number'),
            ]);
    }

Customize Action's Button Icon and Position

If you want to customize the action's button icon and position, you can chain on the following methods:

public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                CepField::make('postal_code')
                    ->actionPosition('prefix') // Options: 'prefix', 'suffix' | Default: 'suffix'
                    ->actionIcon(Heroicon::OutlinedDocumentMagnifyingGlass), // Default: 'heroicon-o-magnifying-glass' 
            ]);
    }

Set Focus on an Input After Filling up the Fields

If you want to set focus on an input after filling up the fields, you can chain on the following methods:

public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                CepField::make('postal_code')
                    ->nextFocusTarget('number'),
                ...
                TextInput::make('number'),
            ]);
    }

Customize Action's Label

If you want to customize the action's label, you can chain on the following method:

public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                CepField::make('postal_code')
                    ->actionLabel('Custom Action Label'), // Default: 'Buscar CEP'
                ...
            ]);
    }

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

otavio-araujo / filament-easy-ptbr-form-fields

Maintainers

Details