Table

Intro

Laravolt Table menyediakan UI untuk menampilkan data dalam bentuk tabular lengkap dengan fitur penunjang sebuah datatable seperti searching, sorting, dan filtering. Laravolt Table berbasis Livewire, sehingga interaksi dapat dilakukan tanpa full page refresh. Tidak perlu khawatir juga dengan Javascript karena semua tetek bengek terkait UI sudah ditangani oleh Laravolt. Kita cukup koding PHP-nya saja.

Membuat Tabel

Karena berbasis Livewire, maka semua Table disimpan di folder app\Http\Livewire\Table. Untuk membuat Table baru, cukup jalankan perintah make:table:

php artisan make:table UserTable

Selanjutnya, cukup definisikan sumber data dan kolom apa saja yang hendak dimunculkan:

class UserTable extends TableView
{
    public function data()
    {
        return \App\Models\User::where('status', 'ACTIVE')->paginate();
    }

    public function columns(): array
    {
        return [
            Text::make('nama', 'Nama'),
            Text::make('email', 'Email'),            
        ];
    }
}

Menampilkan Tabel

Untuk menampilkan tabel, cukup panggil Blade component atau Blade directive dari view:

resources/views/users/index.blade.php
<livewire:table.user-table />

// atau

@livewire('table.user-table')

// atau

@livewire(\App\Http\Livewire\Table\UserTable::class)

Referensi

  • https://laravel-livewire.com/docs/2.x/rendering-components

Sumber Data

Laravolt Table mampu mengolah beberapa macam sumber data untuk kemudian ditampilkan ke dalam tabel. Opsi yang tersedia untuk bisa dipakai sebagai return value dari method data() adalah.

  • Array
  • Collection
  • Eloquent
  • Query Builder
  • Response dari Http Client

Array

Sumber data paling sederhana adalah array.

public function data()
{
    return [
        ['name' => 'Andi', 'email' => 'andi@example.com'],
        ['name' => 'Budi', 'email' => 'budi@example.com'],
    ];
}

Collection

\Illuminate\Support\Collection juga bisa dijadikan sebagai sumber data:

public function data()
{
    $users = [
        ['name' => 'Andi', 'email' => 'andi@example.com'],
        ['name' => 'Budi', 'email' => 'budi@example.com'],
        ['name' => 'Citra', 'email' => null],        
    ];

    return collect($users)->reject(fn($user) => $user->email === null);
}

Eloquent

Sumber data yang paling umum digunakan tentu saja Eloquent:

use App\Models\User;

public function data()
{
    return User::whereNull('deleted_at')->paginate();
}

Jika tidak membutuhkan paginasi, kita bisa langsung memanggil get():

use App\Models\User;

public function data()
{
    return User::query()->whereNull('deleted_at')->get();
}

Query Builder

Jika Eloquent bukan pilihanmu dan lebih memilih Query Builder, kita tetap bisa menerapkan hal yang sama:

public function data()
{
    return \DB::table('users')->whereNull('email')->paginate();
}

 

public function data()
{
    return \DB::table('users')->get(); // tanpa paginasi
}

Response Dari HTTP Client

Untuk mendapatkan sumber data langsung dari API, kita bisa memanfaatkan HTTP Client bawaan Laravel:

use Illuminate\Support\Facades\Http;

public function data()
{
    return Http::get('https://jsonplaceholder.typicode.com/users');
}

Column Types

Avatar

Kolom Avatar digunakan untuk menampilkan gambar avatar secara otomatis dari inisial. Pada contoh di bawah ini, inisial dari email akan digunakan untuk menghasilkan gambar avatar yang sesuai.

use Laravolt\Suitable\Columns\Avatar;

public function columns(): array
{
    return [
        Avatar::make('email', 'Avatar'),
    ];
}

Dokumentasi lengkap tentang Avatar bisa dibaca di https://github.com/laravolt/avatar.

Boolean

Kolom Boolean digunakan untuk menampilkan nilai true atau false dalam bentuk ikon. Nilai yang tidak bertipe boolean akan di-casting secara otomatis ke tipe (bool).

use Laravolt\Suitable\Columns\Boolean;

public function columns(): array
{
    return [
        Boolean::make('is_active'),
    ];
}

Button

Kolom Button digunakan untuk menambahkan tombol yang berfungsi sebagai navigasi untuk berpindah ke halaman lain.

use Laravolt\Suitable\Columns\Button;

public function columns(): array
{
    return [
        Button::make('permalink', 'Info')->label('Profile')->icon('external link'),
    ];
}

Pada contoh di atas, permalink berisi sebuah url yang valid, baik itu hardcoded "http://example.com" atau hasil dari pemanggilan fungsi route() atau url() di Laravel:

class User extends Model 
{
    public function getPermalinkAttribute()
    {
        return route('users.show', $this->id);
    }
}

Button::make() juga menerima Closure untuk meng-generate url secara dinamis ketika pemanggilan:

use Laravolt\Suitable\Columns\Button;

public function columns(): array
{
    return [
        // bisa memakai sintaks baru (arrow function)
        Button::make(fn ($user) => route('users.show', $user['id'])),

        // atau cara lama yang lebih panjang
        Button::make(
            function ($user) {
                return route('users.show', $user['id']);
            }
        ),    
    ];
}

Checkall

Kolom Checkall digunakan untuk menambahkan checkbox di setiap baris yang selanjutnya bisa digunakan sebagai multiple selection. ID yang telah dipilih (dicentang) selanjutnya bisa dikirim sebagai parameter ketika kita mendefinisikan Table Action.

use Laravolt\Suitable\Columns\Checkall;

public function columns(): array
{
    return [
        Checkall::make('id'),
    ];
}

Date

Kolom Date digunakan untuk mengubah tanggal dari database dengan format format 2021-06-02 menjadi tanggal yang lebih manusiawi untuk dibaca, yaitu 2 Juni 2021.

use Laravolt\Suitable\Columns\Date;

public function columns(): array
{
    return [
        Date::make('created_at'),
    ];
}

Ada method tambahan yang tersedia untuk tipe kolom Date, yaitu:

  • format(string $format) dimana $format adalah string yang sesuai dengan format yang diterima oleh Moment.js.
  • timezone(string $timezone) untuk melakukan konversi otomatis tanggal ke timezone yang sesuai. Daftar timezone yang valid bisa dilihat di dokumentasi resmi PHP. Jika tidak memanggil timezone() secara eksplisit, maka konversi ke timezone akan dilakukan dengan melihat:
    • Atribut timezone dari user yang sedang login: auth()->user()->timezone.
    • Jika null, timezone akan dilihat dari config('app.timezone').

DateTime

Mirip seperti kolom Date, DateTime mengubah nilai 2021-06-02 22:54:00 menjadi 2 Juni 2021 pukul 22.45.

use Laravolt\Suitable\Columns\DateTime;

public function columns(): array
{
    return [
        DateTime::make('created_at'),   
    ];
}

Method format() dan timezone() juga tersedia, dengah behaviour yang sama dengan kolom Date.

Html

Kolom Html digunakan jika konten yang akan ditampilkan mengandung tag HTML, dan kita ingin menampilkannya sesuai format HTML.

public function data()
{
    return [
        ['bio' => '<b>Strong</b> <i>foo</i>'],
    ];
}

public function columns(): array
{
    return [
        Html::make('bio')
    ];
}

Pada contoh di atas, tabel akan menampilkan konten sebagai "Strong foo". Kolom ini biasa digunakan ketika data yang disimpan berasar dari WYSIWYG atau rich text editor seperti redactor dan tinymce.

Id

Kolom Id digunakan untuk menampilkan primary key dari sebuah model Eloquent. Di balik layar, kolom ini akan memanggil getKey(). Jadi pastikan hanya menggunakan kolom ini ketika sumber data berasal dari Eloquent.

use Laravolt\Suitable\Columns\Id;

public function columns(): array
{
    return [
      Id::make(),
    ];
}

Image

use Laravolt\Suitable\Columns\Image;

public function columns(): array
{
    return [
      Image::make('profile_picture')
    ];
}

Method tambahan yang tersedia: - height(int $sizeInPixel) untuk mengatur tinggi gambar. - width(int $sizeInPixel) untuk mengatur lebar gambar. - alt(string $text) untuk mengatur atribut alt (alternate text).

Label

Kolom Label digunakan untuk menampilkan sebuah nilai agar terlihat lebih mencolok. Contoh nilai yang cocok ditampilkan sebagai Label antara lain: status, kategori, jenis, tipe, dan sejenisnya.

use Laravolt\Suitable\Columns\Label;

public function columns(): array
{
    return [
        Label::make('status'),
    ];
}

Untuk menambahkan kelas CSS kepada Label, bisa memanfaatkan method addClass:

use Laravolt\Suitable\Columns\Label;

public function columns(): array
{
    return [
        Label::make('status')->addClass('green small'),
    ];
}

Ada beberapa kelas built in yang bisa dipakai untuk menentukan warna sebuah Label, yaitu red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey, black.

Pada prakteknya, ada kebutuhan untuk memberikan warna yang berbeda untuk setiap value. Hal ini bisa dilakukan dengan memanfaatkan method map():

use Laravolt\Suitable\Columns\Label;

public function columns(): array
{
    return [
        Label::make('status')->map([
            'active' => 'green',
            'banned' => 'red',
        ]),
    ];
}

Number

Kolom Number digunakan untuk menampilkan sebuah value dalam format angka yang lebih manusiawi. Sebagai contoh, sebuah nilai 1000000 akan secara otomatis diubah menjadi 1.000.000 dan ditampilkan rata kanan.

use Laravolt\Suitable\Columns\Number;

public function columns(): array
{
    return [
        Number::make('gaji',)
    ];
}

Format angka yang saat ini digunakan adalah format yang umum dipakai di Indonesia.

Raw

Kolom Raw digunakan untuk menampilkan sebuah value apa adanya (unescaped), tanpa melewati fungsi htmlspecialchars. Hati-hati ketika menggunakan Raw untuk sebuah value yang berasal dari inputan user, karena ada peluang terjadinya Cross Site Scripting (XSS).

use Laravolt\Suitable\Columns\Raw;

public function data()
{
    return [
        ['bio' => '<b>Strong</b><script>alert("foo")</script>'],
    ];
}

public function columns(): array
{
    return [
        Raw::make('bio'),
    ];
}

Pada contoh di atas, kita akan mendapatkan sebuah tulisan Strong (dalam huruf tebal) dan kode Javascript untuk menampilkan alert akan dieksekusi oleh browser.

RestfulButton

Kolom RestfulButton digunakan untuk membuat tombol-tombol standard sebuah proses create-read-update-delete atau CRUD. Kita hanya perlu mendefinisikan resource name untuk kemudian dihasilkan tiga buat tombol show, edit, dan destroy.

use Laravolt\Suitable\Columns\RestfulButton;

public function columns(): array
{
    return [
        RestfulButton::make('users'),
    ];
}

Pada contoh kode di atas, ketiga tombol yang dihasilkan akan memiliki route:

  • show: route('users.show', <id>)
  • edit: route('users.edit', <id>)
  • destroy: route('users.destroy', <id>)

<id> otomatis diambil dari primary key object yang bersangkutan. Oleh sebab itu, RestfulButton hanya bisa dipakai jika sumber data berasal dari Eloquent.

Method tambahan yang tersedia:

  • only($action1, $action2) jika hanya ingin menampilkan aksi tertentu saja, misalnya only('show').
  • except($action1, $action2) jika ingin menghilangkan tombol tertentu, misalnya except('destroy').

Untuk memahami lebih lanjut tentang resource controller, silakan membaca dokumentasi resmi dari Laravel.

RowNumber

Kolom RowNumber digunakan untuk menampilkan nomor baris secara terurut, dimulai dari 1.

use Laravolt\Suitable\Columns\RowNumber;

public function columns(): array
{
    return [
        RowNumber::make(),
    ];
}

Text

Kolom Text digunakan untuk menampilkan value secara aman, terhindar dari Cross Site Scripting (XSS), memanfaatkan fungsi htmlspecialchars bawaan PHP.

use Laravolt\Suitable\Columns\Text;

public function data()
{
    return [
        ['bio' => '<b>Strong</b><script>alert("foo")</script>'],
    ];
}

public function columns(): array
{
    return [
        Text::make('bio'),      
    ];
}

Pada contoh di atas, "bio" akan ditampilkan apa adanya sesuai teks yang tertulis:

<b>Strong</b><script>alert("foo")</script>

Text vs Html vs Raw

Ada tiga kolom yang bisa digunakan untuk menampilkan konten yang berasal dari WYSIWYG dan mengandung tag HTML (dan Javascript). Berikut ini adalah perbedaan dari ketiganya:

Kolom Output Keterangan
Text <b>Strong</b> <script>alert("foo")</script> Paling aman, menampilkan teks apa adanya.
Html Strong <script>alert("foo")</script> Jika hanya ingin mengeksekusi tag HTML saja.
Raw Strong (dan muncul alert di browser) Jika ingin mengeksekusi sepenuhnya kode HTML dan Javascript.

Url

Kolom Url digunakan untuk menampilkan sebuah URL secara otomatis menjadi link yang bisa diklik.

use Laravolt\Suitable\Columns\Url;

public function columns(): array
{
    return [
        Url::make('website),
    ];
}

View

Ketika tampilan semakin kompleks, kita bisa memanfaatkan kolom View untuk memindahkan logic untuk merender isi sebuah kolom ke sebuah file blade terpisah.

use Laravolt\Suitable\Columns\View;

public function columns(): array
{
    return [
        View::make('profil')
    ];
}

Lalu buat sebuah file blade profil.blade.php:

resources/views/profil.blade.php
<dl>
    <dt>Name</dt>
    <dd>{{ $data->name }}</dd>
    <dt>Email</dt>
    <dd>{{ $data->email }}</dd>
</dl>

Custom Column

Style

Searching

Show/Hide Searchbox

Search Debounce

Sorting

Filtering

Pagination

Export

Pooling

Query String

Table Action