Konfigurasi Datatables

Sebelum kita melanjutkan latihan praktik membuat datatable dengan use case spesifik. Kita akan memepelajari terlebih dahulu konfigurasi yang tersedia untuk package yajra/laravel-datatables

Konfigurasi tersebut terdapat pada config/datatables.php.

Pencarian / Search

Konfigurasi search mengatur tentang perilaku pencarian pada datatable yang kita pakai.

`smart`

Konfigurasi pertama pada kelompok konfigurasi pencarian adalah smart, konfigurasi ini mengatur apakah keyword yang dimasukkan pada input pencarian di datatable akan dikelilingi dengan % seperti ini LIKE "%keyword%".

Tentu kamu paham kan, perbedaan jika menggunakan % dan tidak. Sebagai pengingat, pada SQL, pencarian dengan perintah LIKE keyword akan mencari row yang memiliki cell bernilai seperti keyword, mirip seperti = meskipun berbeda, tapi secara garis besar keduanya mirip.

Sementara jika keyword dikelilingi % % seperti ini LIKE "%keyword%"" maka pencarian akan dilakukan terhadap row dengan cell yang mengandung keyword tidak peduli di depan, di tengah atau di belakang posisi keyword tersebut.

Untuk mengaktifkan smart kamu cukup biarkan saja konfigurasi seperti bawaan yaitu bernilai true, jika ingin menonaktifkan mode smart maka kamu ubah nilai konfigurasinya menjadi false.

`multi_term`

Konfigurasi berikutnya adalah multi term, apabila bernilai true maka kata kunci pencarian akan dipecah dan digunakan sebagai keyword tersendiri bukan satu kesatuan.

Misalnya jika kita mencari nama Muhammad Azamuddin, maka datatable akan memecah menjadi dua kata kunci yaitu Muhammad dan Azamuddin, sehingga setiap User di database dengan kata yang mengandung Muhammad atau Azamuddin akan masuk ke hasil pencarian.

Sementara jika kita ubah nilai konfigurasi multi term ini menjadi false maka kata kunci Muhammad Azamuddin akan diperlaukan sebagai satu kata kunci dan tentu hasilnya adalah users yang memiliki nama mengandung Muhammad Azamuddin, sedangkan Muhammad Ilzam atau Azamuddin Kahfi tidak masuk hasil pencarian.

`case_insensitive`

Konfigurasi ini sangat jelas ya, jika bernilai true maka kata kunci pencarian pada DataTable akan diperlakukan secara case insenstive alias tidak peduli kapitalisasi hurufnya, yakni kata kunci Muhammad Azamuddin dianggap sama saja dengan muhammad azamuddin.

Sementara jika kita ubah menjadi false, maka kedua kata kunci tadi dianggap kata kunci yang berbeda.

`use_wildcards`

Secara bawaan nilai dari konfigurasi ini adalah false, jika dijadikan true maka kata kunci akan disisipkan karakter wildcard (%) pada setiap karakter kata kunci misalnya Muhammad Azamuddin akan menjadi %M%u%h%a%m%m%a%d% %A%z%a%m%u%d%d%i%n% pada SQL pencariannya.

`starts_with`

Konfigurasi terakhir pada kelompok konfigurasi pencarian adalah starts_with, nilai bawaan dari konfigurasi ini adalah false. Jika kita ubah menjadi true, maka datatable akan melakukan pencarian keyword pada bagian awal setiap cell yang dicari. Alias menggunakan SQL semacam ini keyword%

`nulls_last_sql`

Merupakan konfigurasi untuk mengatur perintah SQL yang digunakan untuk mensortir pada kolom agar nilai NULL ditampilkan paling akhir. Kenapa diperlukan konfigurasi ini? Karena perintah yang digunakan tergantung database engine yang kita gunakan.

Nilai bawaan dari konfigurasi ini adalah untuk database Postgres atau Oracle yaitu:

:column :direction NULLS LAST

Jika kamu menggunakan MySQL silahkan ubah nilainya menjadi seperti ini:

CASE WHEN :column IS NULL THEN 1 ELSE 0 END, :column :direction

`error`

Konfigurasi ini kita gunakan untuk menentukan pesan error yang akan diberikan yang terkait dengan package yajra/laravel-datatables. Ada 3 nilai yang bisa kita berikan yaitu:

null
'throw'
pesan custom

Secara bawaan nilai dari konfigurasi ini adalah null.

Untuk mengubah nilai konfigurasi ini, kamu bisa mengubah langsung pada file config/datatables.php atau dengan mengubah pada file .env dengan key DATATABLES_ERROR, hal ini karena secara bawaan konfigurasi ini membaca dari file .env terlihat dari kode env('DATATABLES_ERROR', null)

Berikut adalah penjelasan masing-masing nilai yang bisa kita pilih.

null

Jika kita menggunakan nilai null maka pesan asli terkait error akan ditampilkan misalnya seperti ini:

{
    "draw": 24,
    "recordsTotal": 200,
    "recordsFiltered": 0,
    "data": [],
    "error": "Exception Message:\n\nSQLSTATE[42S22]: Column not found: 1054 Unknown column 'xxx' in 'order clause' (SQL: select * from `users` where `users`.`deleted_at` is null order by `xxx` asc limit 10 offset 0)"
}

'throw'

Jika kita menggunakan nilai 'throw' maka package akan melemparkan Exception yaitu \Yajra\DataTables\Exception. Kemudian kita bisa menangani kesalahan Exception tersebut pada app/Exceptions/Handler.php seperti ini:

Pada method render di file app/Exceptions/Handler.php kita mengecek terlebih dahulu apakah $exception berasal dari \Yajra\DataTables\Exception, jika iya maka tangani dengan kode berikut:

return response([
    'draw'            => 0,
    'recordsTotal'    => 0,
    'recordsFiltered' => 0,
    'data'            => [],
    'error'           => 'Laravel Error Handler',
]);

Sehingga file tersebut menjadi seperti ini:

  /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Throwable  $exception
     * @return \Illuminate\Http\Response
     */
    public function render($request, Throwable $exception)
    {
        if ($exception instanceof \Yajra\DataTables\Exception) {
            return response([
                'draw'            => 0,
                'recordsTotal'    => 0,
                'recordsFiltered' => 0,
                'data'            => [],
                'error'           => 'Terjadi kesalahan terkait datatable',
            ]);
        }

        return parent::render($request, $exception);
    }

Pesan Custom

Untuk menggunakan pesan custom kita cukup gunakan String pesan yang kita inginkan misalnya "Terjadi kesalahan terkait datatables", kita juga bisa menggunakan key pada penerjemahan misalnya datatables.error (dengan asumsi kamu sudah memiliki key tersebut)

Contoh response dengan pesan custom

{
    "draw": 24,
    "recordsTotal": 200,
    "recordsFiltered": 0,
    "data": [],
    "error": "Terjadi kesalahan terkait datatables"
}

Columns / Kolom

Kelompok konfiguarsi kolom mengatur bagaimana perilaku kolom pada DataTable yang kita gunakan.

`excess`

Konfigurasi ini berbentuk Array yang memiliki nilai bawaan yaitu ['rn', 'row_num'].

Item yang berada pada Array di atas adalah nama dari kolom yang ingin disembunyikan dari DataTable. Jika ingin menambahkan kolom lain maka kita cukup tambahkan item pada Array tersebut misalnya menjadi ['rn', 'row_num', 'internal_id']

`escape`

Konfigurasi ini juga bertipe Array yang menentukan kolom mana saja yang akan dilakukan escape sehingga aman dari serangan XSS. Nilai bawaannya adalah * yang artinya semua kolom dilakukan escaping.

Jika ada kolom yang ingin kita non aktifkan escape ini maka kita ganti nilainya dari * menjadi misalnya ['free_column']

Untuk menonaktifkan pada semua kolom maka kita gunakan Array kosong seperti ini []

`raw`

Konfigurasi ini berisi kolom yang diizinkan untuk berisi HTML dan merender konten HTML tersebut. Secara bawaan bernilai ['action'] yang berarti kolom action diizinkan untuk memuat HTML dan merendernya.

Kita bisa menambahkan kolom lain jika diperlukan, tapi perlu diingat bahwa menambahkan kolom di sini itu berarti kita membuka diri terhadap serangan XSS untuk kolom tersebut.

`blacklist`

Konfigurasi ini digunakan untuk melarang kolom untuk dicari pada pencarian ataupun dilakukan sortir.

Secara bawaan nilainya adalah ['password', 'remember_token'] yang berarti kolom password dan remember_token tidak akan bisa dilakukan pencarian maupun sortir pada DataTable.

`whitelist`

Merupakan kebalikan dari blacklist, hanya kolom yang terdaftar di sini yang bisa dilakukan pencarian / sortir.

Nilai bawaan dari konfigurasi ini adalah * yang artinya semua kolom bisa dilakukan pencarian maupun sortir, kecuali yang didaftarkan pada konfigurasi blacklist

Konfigurasi Lainnya

Konfigurasi yang tidak dijelaskan di atas kami kelompokkan pada Konfigurasi Lainnya karena konfigurasi ini mungkin tidak akan teman-teman gunakan, namun untuk pengetahuan tetap kami sebutkan di sini.

`json`

Terdapat dua konfigurasi pada kelompok konfigurasi json yaitu header dan option, konfigurasi ini digunakan untuk melakukan setting terhadap response header dan options.

`index_column`

Untuk mengubah nama internal column index yang digunakan oleh DataTable, nilai bawaanya adalah DT_RowIndex.

`engines`

Berisi mapping builder yang tersedia pada DataTable, kita bisa menambahkan builder custom jika mau. Nilai bawaanya adalah seperti berikut:

'engines'        => [
  'eloquent'   => Yajra\DataTables\EloquentDataTable::class,
  'query'      => Yajra\DataTables\QueryDataTable::class,
  'collection' => Yajra\DataTables\CollectionDataTable::class,
  'resource'   => Yajra\DataTables\ApiResourceDataTable::class,
],

`builders`

Berisi builder yang diterima oleh DataTable dan diteruskan melalui mapping pada konfigurasi engines.

Basic Datatable Datatable Service