laravel form components

Hemat waktu dan manfaatkan satu set komponen bentuk yang dinamis, siap digunakan dan sepenuhnya dapat disesuaikan.

Komponen kompatibel dengan LiveWire dan dapat digunakan dengan kerangka kerja UI berikut:

• Bootstrap 5
• Bootstrap 4
• Tailwindcss 3 (fitur mendatang)

Menemukan paket ini bermanfaat? Harap pertimbangkan mendukung pekerjaan saya!

Kesesuaian

Laravel	LiveWire	Php	Kemasan
^9.0 | ^10.0	^2.0	8.1.* | 8.2.*	^1.2
^8.0 | ^9.0	^2.0	^8.1 | ^8.2	^1.1
^8.0 | ^9.0	^2.0	^8.0 | ^8.1	^1.0

Panduan Upgrade

• Dari komponen oksiva/laravel-bootstrap hingga komponen oksiva/laravel

Contoh Penggunaan

Panggil saja komponen yang Anda butuhkan dalam pandangan Anda dan biarkan paket ini mengurus bagian yang memakan waktu generasi HTML.

< x:form::form class = " row " method = " PUT " :action = " route('user.update', $user) " :bind = " $user " >
    < div class = " col-md-6 " >
        < x:form::input name = " name " />
        < x:form::input type = " email " name = " email " />
        < x:form::textarea name = " biography " :locales = " ['fr', 'en'] " />
    </ div >
    < div class = " col-md-6 " >
        < x:form::select name = " hobbies " :options = " [1 => 'Sport', 2 => 'Cinema', 3 => 'Literature', 4 => 'Travel'] " caption = " Select your favorite hobbies. " multiple />
        < x:form::checkbox name = " technologies " :group = " [1 => 'Laravel', 2 => 'Bootstrap', 3 => 'Tailwind', 4 => 'Livewire'] " inline />
        < x:form::radio name = " gender " :group = " [1 => 'Male', 2 => 'Female', 3 => 'Other'] " inline />
        < x:form::toggle-switch name = " active " />
    </ div >
    < div class = " col-12 mt-2 " >
        < x:form::button .link class = " btn-secondary me-3 " > {{ __ ( ' Cancel ' ) } } </ x:form::button .link >
        < x:form::button .submit />
    </ div >
</ x:form:form >

Dan mendapatkan komponen -komponen ini ditampilkan:

Daftar isi

• Instalasi
• Konfigurasi
• Tampilan
• Komponen
  • Membentuk
  • Masukan
  • TexTarea
  • Memilih
  • Kotak centang
  • Mengalihkan
  • Radio
  • Tombol
• Bagaimana
  • Berurusan dengan atribut dan kelas
  • Setel id
  • Kelola Label dan Placeholder
  • Menangani tampilan label mengambang
  • Atur addons
  • Mengikat data
  • Tetapkan nilai kustom
  • Menangani status dan kesalahan validasi
  • Tambahkan keterangan
  • Aktifkan mode multibahasa
  • Plug With LiveWire
• Pengujian
• Changelog
• Berkontribusi
• Kredit
• Lisensi

Instalasi

Anda dapat menginstal paket melalui komposer:

composer require okipa/laravel-form-components

Konfigurasi

Anda dapat mempublikasikan file konfigurasi dengan:

php artisan vendor:publish --tag=form-components:config

Di antara konfigurasinya, paket ini memungkinkan Anda untuk memilih kerangka kerja UI mana yang akan digunakan.

Harap dicatat bahwa Anda harus menginstal dan mengkonfigurasi kerangka kerja UI yang ingin Anda gunakan sebelum menggunakan paket ini.

Tampilan

Anda dapat mempublikasikan tampilan paket untuk menyesuaikannya jika perlu:

php artisan vendor:publish --tag=form-components:views

Komponen

Membentuk

Komponen dapat dibungkus ke dalam komponen bentuk.

Jika tidak ada metode khusus yang ditetapkan, metode GET akan ditetapkan secara default.

Bidang metode CSRF dan spoofing tersembunyi akan secara otomatis dihasilkan saat dibutuhkan, sesuai dengan metode formulir yang ditentukan:

• Anda tidak perlu mendefinisikan arahan @method() , nyatakan tindakan PUT , PATCH atau DELETE Anda secara langsung di atribut action
• Anda tidak perlu mendefinisikan arahan @csrf() , itu akan dinyatakan secara otomatis dengan POST , PUT , PATCH dan DELETE tindakan

Formulir dihasilkan dengan atribut HTML novalidate default, yang mencegah validasi browser yang mendukung validasi sisi server (yang merupakan praktik yang baik untuk masalah keamanan).

< x:form::form method = " PUT " >
    < x:form::input name = " first_name " />
    ...
</ x:form::form >

Input dan TextArea

Tambahkan input dan TextArea ke dalam formulir Anda.

Jika Anda tidak mengatur jenis kustom ke input, itu akan mengambil jenis text default.

Input radio, kotak, dan tombol harus digunakan dengan komponen mereka sendiri karena perilaku mereka yang berbeda.

Komponen TextArea dapat digunakan dengan cara yang sama seperti komponen input tetapi tanpa menyatakan jenis.

< x:form::input type = " file " name = " avatar " />
< x:form::input name = " first_name " />
< x:form::input type = " email " name = " email " />
...
< x:form::textarea name = " description " />

Memilih

Setel Komponen Pilih dalam formulir Anda.

Auto menghasilkan opsi dengan memberikan nilai asosiatif/array label.

Elemen SELECT HTML secara asli tidak menerima atribut placeholder, namun komponen pilih memungkinkan Anda untuk menangani opsi seperti placeholder telah disiapkan ke yang lain. Placeholder ini akan berperilaku untuk komponen lainnya.

Secara default, opsi Placeholder Pilih ini dipilih, dinonaktifkan, dan disembunyikan. Namun, Anda dapat mengizinkannya dipilih jika Anda perlu mengatur bidang nullable misalnya. Untuk melakukan itu, cukup tambahkan atribut allowPlaceholderToBeSelected ke komponen Anda.

Dalam beberapa mode, paket ini akan berhati -hati untuk mengubah nama menjadi nama array, jadi Anda tidak perlu menambahkannya secara manual.

 @php ( $options = [ 1 => ' Laravel ' , 2 => ' Bootstrap ' , 3 => ' Tailwind ' , 4 => ' Livewire ' ] )
< x:form::select name = " hobby " placeholder = " What is your hobby prefered hobby? " :options = " $options " selected = " 1 " />
< x:form::select name = " hobbies " :options = " $options " :selected = " [2, 3] " allowPlaceholderToBeSelected multiple /> {{-- You'll be able to selected the placeholder and the name will be converted to hobbies[] --}}

Kotak centang, sakelar sakelar dan radio

Kotak centang, sakelar sakelar, dan komponen radio tersedia untuk Anda gunakan.

Karena input radio tidak pernah digunakan sendirian, Anda harus mendeklarasikan atribut group yang diperlukan saat menggunakannya, menunggu array asosiatif nilai/label dari mana bidang radio akan dihasilkan.

Mengenai input centang dan sakelar sakelar, Anda akan dapat menggunakannya dalam mode tunggal atau dalam grup. Untuk menggunakannya dalam mode grup, Anda juga harus mendeklarasikan atribut group .

Dalam mode grup, paket ini akan berhati -hati untuk mengubah nama menjadi nama array, jadi Anda tidak perlu menambahkannya secara manual.

Jika Anda ingin menampilkan komponen input ini inline, cukup tentukan atribut inline .

< x:form::checkbox name = " newsletter_subscription " :checked = " true " /> {{-- 1 generated checkbox --}}
< x:form::checkbox name = " technologies " :group = " ['laravel' => 'Laravel', 'bootstrap' => 'Bootstrap'] " :checked = " laravel " /> {{-- 2 generated checkboxes --}}
< x:form::toggle-switch name = " active " :checked = " false " inline /> {{-- 1 generated toggle switch with inline mode --}}
< x:form::toggle-switch name = " technologies " :group = " ['tailwind' => 'Tailwind', 'livewire " => 'Livewire']" :checked="livewire"/> {{-- 2 generated toggle switches --}}
< x:form::radio name = " gender " :group = " ['female' => 'Female', 'male' => 'Male'] " :checked = " male " inline /> {{-- 2 generated radios with inline mode --}}

Tombol

Komponen kirim dan tautan tersedia.

Kirim tombol memungkinkan Anda untuk memicu formulir dan akan memberikan tubuh default __('Submit') jika tidak ada yang ditentukan.

Tombol Link memungkinkan Anda untuk mengatur tindakan seperti Back atau Cancel formulir Anda dengan menyediakan tautan dengan tampilan seperti tombol. Karena komponen ini adalah tautan HTML, ia akan memberikan judul default dengan menganalisis tubuhnya.

Secara default, kedua komponen akan menetapkan warna latar belakang dasar jika tidak ada atribut kelas khusus yang ditentukan.

< x:form::form >
    ...
    < div class = " d-grid " >
        < x:form::button .submit >Submit this form</ x:form::submit > {{-- Will provide `btn-primary` class with Bootstrap UI --}}
        < x:form::button .link class = " btn-secondary " href = " {{ back () } } " > {{-- Will auto-generate `title="Back"` --}}
            < i class = " fas fa-undo fa-fw " ></ i >
            Back
        </ x:form::submit >
    </ div >
</ x:form::form >

Bagaimana

Berurusan dengan atribut dan kelas

Komponen yang disediakan dibangun menggunakan komponen blade.

Mengikuti cara kerja komponen blade, Anda dapat mengatur atribut dan kelas HTML:

• Atribut akan menggantikan yang default
• Kelas akan digabungkan untuk yang sudah ada

Setel id

Tentukan ID komponen seperti yang akan Anda lakukan untuk elemen HTML apa pun.

Jika tidak ada ID khusus yang ditetapkan, ID akan dihasilkan menggunakan nilai kebab Cased <type>-<name> .

< x:form::input id = " custom-id " name = " first_name " /> {{-- Default id: `input-first-name` --}}

< x:form::textarea id = " custom-id " name = " first_name " /> {{-- Default id: `textarea-first-name` --}}

Mengaktifkan atau menonaktifkan input margin dasar

Secara default, semua komponen input akan mendeklarasikan margin bawah untuk memposisikan diri dengan benar dalam bentuk.

Kadang -kadang Anda perlu menonaktifkan margin bawah default ini: Anda dapat melakukan ini dengan mengatur atribut marginBottom ke false .

< x:form::input name = " first_name " /> {{-- Will declare a bottom margin --}}

< x:form::textarea name = " first_name " :marginBottom = " false " /> {{-- Will not declare any bottom margin --}}

Kelola Label dan Placeholder

Anda dapat mendefinisikan label pada semua komponen input (kecuali untuk radio).

Jika tidak ada label khusus yang ditentukan, label akan mengambil nilai default __('validation.attributes.<name>) .

Mengikuti perilaku yang sama, semua komponen input yang memungkinkan penggunaan placeholder (terpilih termasuk) akan memberikan placeholder default yang akan mengambil nilai label .

Anda dapat mengganti nilai default ini dengan mengatur placeholder khusus.

Anda juga dapat menyembunyikan label dan placeholder yang dihasilkan secara otomatis oleh mereka untuk false .

< x:form::input name = " first_name " label = " First Name " placeholder = " Please fill your first name... " /> {{-- Will display the custom label and placeholder --}}
< x:form::input name = " last_name " :label = " false " :placeholder = " false " /> {{-- Will hide the label and placeholder --}}
< x:form::input type = " tel " name = " phone_number " /> {{-- Will display default auto-generated label and placeholder --}}

Menangani tampilan label mengambang

Paket ini memungkinkan Anda untuk mengaktifkan atau menonaktifkan label mengambang yang ditampilkan.

Anda dapat mengatur perilaku label floating global dengan config('form-components.floating_label') .

Anda akan dapat mengesampingkan perilaku global ini pada tingkat bentuk untuk semua komponen yang terkandung.

< x:form::form :floatingLabel = " true " >
    < x:form::input name = " first_name " /> {{-- Will display a floating label even if it has been disabled in config --}}
</ x:form::form >

Akhirnya, Anda juga dapat mengesampingkan semua perilaku lain yang ditentukan pada komponen itu sendiri.

    < x:form::input name = " first_name " :floatingLabel = " true " />

Atur addons

Anda dapat mendefinisikan prepend dan append HTML Addons pada komponen input dan TextArea.

    < x:form::input name = " " prepend = " <i class= " fas fa-code fa-fw " ></i> " />
    < x:form::input name = " search " append = " <i class= " fas fa-search fa-fw " ></i> " />

Catatan: Anda dapat menggunakan HTML secara langsung alih -alih komponen untuk manajemen Addon yang kompleks.

Mengikat data

Anda dapat mengikat model, objek, koleksi, atau array yang fasih untuk mengarahkan nilai komponen terikat.

Mengikat data pada komponen formulir akan memicu pengikatan semua komponen yang terkandung.

Anda dapat mengikat data secara langsung pada komponen dan mengganti ikatan formulir.

Dalam hal kesalahan validasi, komponen akan diisi ulang oleh nilai -nilai lama yang akan mengesampingkan nilai terikat.

Untuk kasus penggunaan tertentu, Anda juga dapat menggunakan @bind($boundDataBatch) dan arahan @endbind blade untuk mengikat sekelompok komponen.

 @php
    $dataBatch1 = [ ' description ' => ' A wonderful description ' ];
    $dataBatch2 = [ ' first_name ' => ' John ' , ' last_name ' => ' Bonham ' ];
@endphp
< x:form::form :bind = " $user " >
    < x:form::input type = " email " name = " email " /> {{-- Will set the value from `$user->email` --}}
    < x:form::textarea name = " description " :bind = " $dataBatch1 " /> {{-- Will set the value from `$dataBatch1['description`] --}}
    @bind ( $dataBatch2 )
        < x:form::input name = " first_name " /> {{-- Will set the value from `$dataBatch2['first_name`] --}}
        < x:form::input name = " last_name " /> {{-- Will set the value from `$dataBatch2['last_name`] --}}
    @endbind
</ x:form::form >

Tetapkan nilai kustom

Ikatan data dapat ditimpa dengan mengatur nilai khusus pada komponen.

 @php ( $data = [ ' description ' => ' A wonderful description ' ]; )
< x:form::form :bind = " $user " >
    ...
    < x:form::textarea
        name = " description "
        :bind = " $user "
        :value = " $data['description'] " /> {{-- Will set the value from `$data['description`] --}}
</ x:form::form >

Menangani status dan kesalahan validasi

Komponen akan dapat menampilkan atau menyembunyikan status keberhasilan/kesalahan mereka dan pesan kesalahan saat kesalahan validasi dipicu:

• Jika keberhasilan validasi yang ditampilkan diaktifkan, komponen hanya akan ditandai sebagai valid ketika komponen lain dalam bentuk terdeteksi sebagai tidak valid
• Jika kegagalan validasi yang ditampilkan diaktifkan, komponen dalam kesalahan akan ditandai sebagai tidak valid dan akan menampilkan pesan kesalahan terkait mereka

Anda dapat mengontrol perilaku ini di berbagai tingkatan:

• Tentukan perilaku default global dengan config('form-components.display_validation_success') dan config('form-components.display_validation_failure')
• Kustomisasi perilaku ini pada formulir dan terapkan secara lokal untuk semua komponen yang terkandung
• Tetapkan perilaku tertentu secara langsung pada komponen

< x:form::form displayValidationSuccess = " false " displayValidationFailure = " false " >
    < x:form::input type = " email " name = " email " /> {{-- Disabled success/error statuses and error message --}}
    < x:form::textarea
        name = " description "
        displayValidationSuccess = " true "
        displayValidationFailure = " true " /> {{-- Enabled success/error statuses and error message --}}
</ x:form::form >

Anda juga dapat menyesuaikan tas kesalahan yang harus digunakan untuk menentukan komponen keberhasilan/status kesalahan dan pesan kesalahan pada komponen formulir.

< x:form::form errorBag = " form_error_bag " > {{-- Error bag for all components within the form --}}
    @errorbag ( ' group_error_bag ' ) {{-- Error bag for a group of components --}}
        < x:form::input name = " first_name " />
        < x:form::input name = " last_name " />
    @enderrorbag
    < x:form::input type = " email " name = " email " errorBag = " component_error_bag " /> {{-- Error bag for a specific component --}}
    ...
</ x:form::form >

Tambahkan keterangan

Membantu pengguna dan menampilkan instruksi tambahan di bawah komponen Anda dengan menambahkan teks.

    < x:form::input name = " name " caption = " Please fill this input with your full name. " />

Aktifkan mode multibahasa

Aktifkan mode multibahasa pada komponen input dan textarea untuk mendapatkan manfaat dari fitur berikut:

• Duplikasi Komponen: Satu komponen per lokal akan ditampilkan
• Nama Lokalisasi: name="description" akan diubah menjadi name="description[<locale>]"
• Label Default dan Pesan Kesalahan Lokalisasi: __(validation.attributes.name) Terjemahan yang digunakan untuk menghasilkan label default dan pesan kesalahan akan ditambahkan dengan (<LOCALE>)

< x:form::input name = " name " :locales = " ['fr', 'en'] " />
< x:form::textarea name = " description " :locales = " ['fr', 'en'] " />

Plug With LiveWire

Bentuk dan komponen input kompatibel dengan LiveWire.

Alih-alih mendefinisikan atribut wire:model html pada setiap komponen yang ingin Anda kawat seperti yang akan Anda lakukan tanpa paket ini, di sini Anda hanya perlu mendefinisikan atribut wire="<optional-modifier>" HTML untuk membuat ini berfungsi.

Setiap komponen input kabel akan menggunakan atribut name sendiri dan mengonversinya ke wire:model="<name>" satu.

< x:form::form wire:submit.prevent = " submit " >
    < x:form::input name = " name " /> {{-- Will not be wired --}}
    < x:form::input type = " email " name = " email " wire /> {{-- Will bind the value from the Livewire component `$email` property with no defined Livewire modifier --}}
    < x-form::input name = " description " wire = " lazy " /> {{-- Will bind the value from the Livewire component `$description` property with the the `lazy` Livewire modifier --}}
    < x-form::submit />
</ x:form::form >

Mengikuti logika yang sama, Anda juga dapat menghubungkan komponen input langsung dari bentuk yang terkandung.

< x-form::form wire:submit.prevent = " submit " wire >
    < x-form::input type = " email " name = " email " /> {{-- Will bind the value from the Livewire component `$email` property with no defined Livewire modifier --}}
    < x-form::input name = " description " wire = " lazy " /> {{-- Will bind the value from the Livewire component `$description` property with the the `lazy` Livewire modifier --}}
    < x-form::submit />
</ x:form::form >

Untuk kasus penggunaan tertentu, Anda juga dapat menggunakan @wire($modifier) dan arahan @endwire blade untuk memasang sekelompok komponen dengan pengubah livewire tertentu.

< x-form::form wire:submit.prevent = " submit " wire = " lazy " >
    < x-form::input name = " first_name " /> {{-- Will bind the value from the Livewire component `$first_name` property with the `lazy` Livewire modifier --}}
    @wire ( ' debounce.150ms ' )
        < x-form::input name = " last_name " /> {{-- Will bind the value from the Livewire component `$last_name` property with the `debounce.150ms` Livewire modifier --}}
    @endbind
    @wire ( null )
        < x-form::input type = " email " name = " email " /> {{-- Will bind the value from the Livewire component `$email` property with no defined Livewire modifier --}}
        < x-form::input name = " description " wire = " lazy " /> {{-- Will bind the value from the Livewire component `$description` property with the the `lazy` Livewire modifier --}}
    @endbind
    < x-form::submit />
</ x-form::form >

Pengujian

composer test 

Changelog

Silakan lihat Changelog untuk informasi lebih lanjut tentang apa yang telah berubah baru -baru ini.

Berkontribusi

Silakan lihat berkontribusi untuk detailnya.

Kerentanan keamanan

Harap tinjau kebijakan keamanan kami tentang cara melaporkan kerentanan keamanan.

Kredit

• Arthur Lorent
• Semua kontributor

Lisensi

Lisensi MIT (MIT). Silakan lihat file lisensi untuk informasi lebih lanjut.