Pelajaran yang bisa dipetik dari Writebook, aplikasi Ruby on Rails dari 37Signals

Writebook adalah aplikasi Rails yang didistribusikan melalui ONCE dari 37Signals. Aplikasi ini ibaratnya sebuah perpustakaan. Orang bisa membuat dan mempublish bukunya sendiri. Tak hanya untuk buku digital namun bisa juga untuk menaruh dokumentasi internal perusahaan. Suka menulis? Ingin membuat publikasi pribadi? Mungkin Writebook bisa menjadi pilihan. Ada beberapa contoh publikasi yang bisa kamu lihat berikut ini.

Perbedaan Writebook dengan aplikasi Open Source pada umumnya adalah cara memperolehnya. Biasanya aplikasi Open Source bisa diunduh dari repository GitHub atau lainnya. Namun aplikasi ini diperoleh dengan membelinya seharga 0 rupiah dari website mereka: https://once.com/writebook. Cara ini cukup menarik untuk membuat orang lebih familiar dengan produk-produk yang ada di platform ONCE milik 37Signals.

Setelah "membelinya", kamu akan mendapatkan e-mail berikut beserta kode untuk instalasinya:

Writebook ini didistribusikan melalui sebuah hub privat Docker milik 37Signals. Perintah di atas adalah perintah yang digunakan untuk mendapatkan aplikasi tersebut. Metode instalasi menggunakan command line seperti ini mengingatkan saya dengan installer milik Bitnami.

Dengan menjalankan once setup [TOKEN] , kamu akan dihadapkan pada pilihan berikut ini:

Dari pengamatan saya, ketika instalasi yang dilakukan adalah:

• Prompt untuk nama domain, ONCE akan melakukan pengecekan DNS. Kalau tidak ada, maka akan setup untuk localhost
• preparing ini sepertinya akan menginstall Docker
• downloading ini sepertinya mendownload Docker Image terbaru dari Writebook (atau aplikasi ONCE lainnya)
• starting ini sepertinya starting Docker image, kemudian run initial setup dari aplikasi Rails Writebook. Kayaknya sih running bin/setup, sebuah script instalasi yang berfungsi untuk menyiapkan aplikasi Rails pertama kalinya. Biasanya berisi persiapan untuk menyiapkan database (migrasi) atau script inisiasi lainnya.

DockerFile

Bagi yang belum pernah menginstal aplikasi Rails beberapa tahun terakhir mungkin melewatkan bahwa Rails punya DockerFile. Sekarang sebagian besar aplikasi modern memilikinya, namun dulu ini sangat jarang. Menariknya, DockerFile dari Rails juga dilengkapi komentar yang menjelaskan setiap bagian dengan apik. Bagi yang pemula yang masih malu-malu dengan server, saya sarankan untuk mempelajari file ini.

Saya menyadari keberadaan file ini setelah saya menginstall aplikasi Rails 7 dari awal. Selama ini saya hanya menggunakan DockerFile yang dibuat oleh teman kantor semenjak Ruby 2.4(!) 😅.

Gem-gem menarik yang digunakan di Writebook

Writebook adalah sebuah aplikasi Ruby on Rails. Sebagai Rails programmer, saya tertarik mempelajari gem-gem apa saja yang digunakan di Writebook. Sebuah perusahaan sekelas 37Signals, sebagai pelopor dari Rails, tentunya sangat menarik untuk mempelajari keputusan-keputusan yang mereka buat. Di mana pemilihan gem menjadi salah satu di antaranya.

• Di halaman buku bisa di-share dengan QR Code. Kode ini di-generate dengan menggunakan rqrcode
• Deteksi User Agent browser dengan useragent. Biasanya saya menggunakan browser karena fiturnya lebih banyak. Mungkin gem ini dipilih karena kebutuhannya yang simpel.
• Code highlighter menggunakan rouge. Ini dipakai untuk House-MD (Markdown Editor) di Writebook
• HTTP/2 Proxy menggunakan thruster. Sebuah gem yang ditulis menggunakan Go. Ketika gem ini diinstal, akan mendownload binary sesuai dengan operating system-nya. Saya sebenarnya masih kurang paham betul apa manfaatnya dan cara kerjanya. Jika ada minat dan waktu luang saya ingin mempelajarinya.
• Di aplikasi Rails X-CSRF-TOKEN header diperlukan untuk setiap http request, termasuk request dari JavaScript. Ini digunakan untuk mencegah CSRF (Cross-Site Request Forgery), yakni untuk mencegah sebuah request dikirim dari website lain. Library yang digunakan untuk membalut header ini secara default adalah requestjs-rails.

Penulisan Private Function di JS

Tak hanya Ruby, di Writebook juga ada kode JavaScript yang bisa saya pelajari. Di antaranya adalah metode penulisan private function ini:

Ketika mengulik kodingan JS-nya, saya menemukan bahwa private function ditulis menggunakan hashtag # sebagai prefix. Kalau di Cookpad sendiri menggunakan underscore _. Namun saya baru tahu bahwa ini sudah ada convention-nya di JS. Nice, mulai sekarang pakai hashtag # untuk menulis private function.

Editor house_md

Writebook dibekali dengan Markdown Editor bernama house_md. Pustaka JS ini turut diperkenalkan pada Rails World 2024 kemarin. Menurut saya, ini salah satu editor markdown yang paling cantik, sekelas dengan markdown editor-nya GitHub.

Di dalam kode sumber Writebook, house_md bisa kita intip dalam bentuk minified JS seperti ini. Artinya, pustaka ini belum dipublikasikan sebagai library open source. Masih banyak saya temui kode SVG-nya yang masih hardcoded, harapannya ketika open source nanti asset ini bisa diubah-ubah.

Namun demikian, sepertinya akan butuh waktu lama untuk menjadikan ini open source. Karena saya melihat masih banyak deklarasi attribut di berbagai tempat, sepertinya masih belum praktis untuk menggunakan library ini. Tak sabar rasanya ingin mencicipi editor ini untuk website saya sendiri.

Preview Halaman Buku

Ada sebuah fitur di Writebook untuk melihat cuplikan dari setiap halaman buku. Dari cuplikan ini, pembaca bisa sekilas melihat isi dari setiap halaman. Sekilas cuplikan ini nampak seperti thumbnail atau image statis. Namun sebenarnya konten di dalamnya adalah HTML sepenuhnya, dengan skala yang lebih kecil. Bagi yang pernah pakai Basecamp (produk dari 37Signals) pasti familiar dengan fitur ini.

Preview halaman ini responsive. Awalnya saya mengira ini dibuat dengan cara mendeklarasikan ulang CSS untuk setiap elemen di halaman tersebut. Artinya jika sebuah halaman buku didefinisikan dengan kelas .page , .section , dll. Saya mengira perlu membuat sub-sub kelas di situ. Misalnya .preview .page, .preview .section, dst. Tentunya cara ini tidaklah efisien dan ribet jika terjadi perubahan. Penasaran dengan ini, saya melakukan inspect pada elemen preview ini. Mari kita menguliknya.

Sepertinya ini adalah kelas yang bertanggungjawab terhadap fitur ini. Apa yang terjadi kalau aspect-ratio nya kita matikan?

Aha! Ternyata aspect-ratio ini yang mengunci dimensi thumbnail dengan ratio tertentu. Dikombinasikan dengan overflow: hidden, maka kontennya akan tersembunyi jika berlebihan.

Jika font font-size: clamp(0.5rem, 5cqi, 0.8rem) nya dimatikan, maka kita akan melihat konten tersebut dalam ukuran aslinya. Artinya ukuran dari setiap objek di dalam suatu halaman itu relatif terhadap font-size nya.

Berarti kunci utama fitur ini ada di CSS property clamp : https://developer.mozilla.org/en-US/docs/Web/CSS/clamp. Kalau kita lihat definisinya, kita dapat mengetahui bahwa ukuran font-size memiliki batas bawah, ukuran optimal dan batas atas:

The clamp() CSS function clamps a middle value within a range of values between a defined minimum bound and a maximum bound. The function takes three parameters: a minimum value, a preferred value, and a maximum allowed value.

Lebih jauh tentang fitur ini: https://css-tricks.com/snippets/css/fluid-typography/

Mari mengoprek!

Kamu suka mengoprek? Mau itu software, aplikasi, game, maupun hardware, semua sama serunya. Sepertinya saya tidak menemukan definisi mengoprek di KBBI, tapi menurut saya mengoprek identik dengan mengulik dan modifikasi:

meng.u.lik
mengusut; menyelidiki
https://kbbi.kemdikbud.go.id/entri/mengulik

mo.di.fi.ka.si
1. n pengubahan: ia setuju untuk melakukan beberapa – pada karangannya
2. n perubahan: rencana itu telah mengalami – dari keputusan sebelumnya
https://kbbi.kemdikbud.go.id/entri/modifikasi

Sebagai software engineer yang kesehariannya disibukkan oleh pekerjaan di kantor, mempelajari bagaimana perusahaan lain membuat aplikasi dapat memperluas perspektif kita dalam menganalisa sebuah problem. Apalagi perusahaan yang aplikasinya diintip adalah perusahaan yang menjadi tempat asal framework yang sering kita pakai. Mempelajarinya adalah sebuah kesempatan yang sangat berharga.

Kita dapat mengetahui bagaimana sebuah framework itu seharusnya digunakan. Seringkali kita menerima sebuah kodingan yang kita sendiri tidak tahu bagaimana dan mengapa kode itu ditulis. Apakah ada cara yang lebih baik? Metode mana yang cocok untuk situasi tertentu? Mengapa mereka tidak menggunakan Service Object yang sering digunakan oleh kebanyakan aplikasi Rails? Atau mengapa library ini dipilih?

Ada banyak praktik yang bisa dipelajari hanya dengan melihat kode sumbernya. Sebagai software engineer, tugas kita adalah menilai mana metode yang cocok dengan situasi tertentu dengan menimbang pros dan cons-nya.

I hope you have learned something new!

Tertarik untuk mengikuti postingan terbaru dalam bentuk Newsletter? Cukup masukkan email pada form berikut ini untuk berlangganan:

Tips VSCode untuk melihat source dari mounted drive

Awalnya saya tidak dapat melihat isi dari Docker image ini di dalam VSCode. Berhubung aplikasi ini berdomisili di dalam Docker image, kita perlu membuat link pada mounted drive tersebut:

ln -s /Users/didik/OrbStack/docker/containers/writebook/rails/ .