spaghettify

Spaghetti

Spaghettify mengubah situs HTML statis apa pun menjadi Aplikasi Halaman Tunggal dengan navigasi berbasis AJAX dan fitur persistensi elemen DOM. Untuk melakukan hal ini, ia mengimplementasikan pencegat DOM dan prosesor corong middleware yang menangkap peristiwa klik tautan, mengambil setiap dokumen yang diminta melalui XHR dan mencerna respons dengan mengalirkannya melalui serangkaian fungsi middlware sebelum menyegarkan dokumen browser.

Fungsi-fungsi middleware ini adalah pengendali I/O yang dapat dicolokkan yang mematuhi Prinsip Tanggung Jawab Tunggal dan menyesuaikan serangkaian langkah-langkah, yang dapat dikategorikan ke dalam hook middleware onBeforeComplete , yang TIDAK mengubah DOM halaman saat ini, dan hook middleware onAfterComplete yang menerapkan perubahannya (karenanya bermutasi) langsung pada DOM halaman saat ini setelah disuntikkan.

Keseluruhan proyek dibangun di atas TypeScript dan mengimplementasikan beberapa polyfill dan strategi pengkodean untuk memperluas dukungan ke browser lama, seperti MSIE11.

Menyiapkan lingkungan Anda

Persyaratan minimum untuk menjalankan proyek ini, baik pada mode pengembangan atau produksi, dan skrip pengembangannya adalah node v12.16.0 dan npm v.6.14.15 , atau versi yang lebih baru. Mungkin proyek ini akan berjalan lancar di node dan npm versi lama tetapi kami menyarankan menggunakan versi LTS terbaru.

Proyek ini mengandalkan BabelJS dan Webpack untuk mengkompilasi kode dalam mode dev, menjalankan build, melayani file situs demo, dan menangani optimasi kode.

Semua interaksi dengan BabelJS dan Webpack telah diabstraksikan dalam skrip npm khusus untuk kenyamanan Anda.

Menginstal dependensi

Sebagai langkah pertama untuk menelurkan lingkungan pengembangan atau produksi, jalankan yarn atau npm install untuk menarik semua dependensi yang diperlukan untuk proyek ini.

Membangun proyek untuk produksi

Silakan jalankan yarn build atau npm run build dari jendela terminal Anda.

Pemaket proyek akan menavigasi seluruh pohon aplikasi dan akan membangun artefak JavaScript ke dalam folder /dist , yang dibundel sebagai spaghettify.js . Paket bermanfaat lainnya juga akan disimpan di sana untuk kenyamanan Anda.

Bisakah saya mengambil Spaghettify dari registri npm? Pada saat penulisan ini, prioritas proyek adalah meningkatkan cakupan pengujian sedikit lebih jauh dan memperluas kemampuan API dengan dukungan yang diperluas untuk hook middleware yang disediakan pengguna. Untuk saat ini, Spaghettify dimaksudkan untuk digunakan sebagai ketergantungan browser, namun mendistribusikannya sebagai paket NPM sedang dalam rencana. Silakan periksa kembali segera untuk mengetahui pembaruan.

API Spagettifikasi

Anda dapat membuat instance dan berinteraksi dengan Spaghettify melalui API yang mudah digunakan dengan tombol alih global, pencegat rute, pengecualian dan tanda atribut persistensi status, dan yang tak kalah pentingnya, memuat indikator dan penangan kemajuan.

Setelah Anda berhasil mengkompilasi Spaghettify, Anda dapat mengimpor dan membuat instance ke dalam aplikasi Anda sebagai berikut:

 < script type =" text/javascript " src =" /dist/spaghettify.js " > </ script >
< script type =" text/javascript " >
  new Spaghettify ( {
    enabled : true ,
    routes : [ '*.html' , 'content/*' ] ,
    excludeByAttr : 'no-spa' ,
    loadProgress : true ,
    persistAttr : 'data-persist' ,
  } ) ;
</ script >

Seperti yang Anda lihat, Spaghettify dapat mengambil objek konfigurasi saat instantiasi. Harap dicatat bahwa semua bidang bersifat opsional dan bahkan seluruh objek konfigurasi itu sendiri juga opsional. Jika tidak disediakan, Spaghettify akan dibuat dengan opsi default seperti dijelaskan pada tabel di bawah.

API pengaturan Spaghettify

Objek pengaturan konfigurasi Spaghettify dapat diringkas sebagai berikut:

Bidang	Jenis	Bawaan	Keterangan
enabled	Boolean	true	Mengaktifkan atau menonaktifkan Spaghettify saat instantiasi
routes	String[]	['*']	Menentukan pola rute yang akan dicegat dan dilayani melalui Spaghettify. Mendukung token glob.
excludeByAttr	String	undefined	Mendefinisikan token atribut data pengecualian (dengan atau tanpa awalan data- ). Tautan yang dihiasi dengan atribut ini akan dilewati oleh Spaghettify
loadProgress	Function Boolean	false	Mengaktifkan bilah kemajuan bawaan atau tidak. Ini juga dapat mengambil pengendali fungsi yang akan menerima persentase kemajuan bilangan bulat saat dimuat.
persistAttr	String	undefined	Mendefinisikan atribut data tanda persistensi status UI (dengan atau tanpa awalan data- ). Elemen yang dihiasi dengan atribut ini akan mempertahankan statusnya di seluruh navigasi halaman.

Harap perhatikan bahwa semua opsi konfigurasi (dan opsi payload itu sendiri) bersifat opsional dan akan mengambil nilai default jika tidak dinyatakan secara eksplisit.

Membuang Spaghettify setelah digunakan

Spaghettify berinteraksi dengan dokumen Anda saat ini dengan mengikat event handler secara internal ke tautan yang memenuhi syarat. Untuk mencegah kebocoran memori atau jika Anda ingin menghentikan Spaghettify hingga diaktifkan kembali, Anda sebaiknya menghancurkannya dengan cara berikut:

 < script type =" text/javascript " >
  // First, we instantiate Spaghettify
  const spa = new Spaghettify ( ) ;
  // Then we dispose it after use
  spa . destroy ( ) ;
</ script >

Tip: Tidak termasuk tautan agar tidak disadap oleh Spaghettify

Semua tautan dikonfigurasikan oleh Spaghettify sebagai subjek untuk disadap. Mesin pengelola peristiwa internal akan menilai apakah tautan tersebut memenuhi syarat untuk diperlakukan sebagai permintaan AJAX atau tidak dengan menguji nilai tautan href terhadap token glob routes .

Namun, kita dapat melewati langkah ini terlebih dahulu dengan mengonfigurasi opsi excludeByAttr dengan nilai atribut, baik dengan awalan data- atau tidak.

Meskipun demikian, dan demi semantik, Spaghettify hanya akan mempertimbangkan elemen tautan yang dikonfigurasi dengan atribut lengkap.

 < script type =" text/javascript " >
  new Spaghettify ( {
    excludeByAttr : 'skip-me' ,
  } ) ;
</ script >

<!-- Spaghettify will disregard the following link -->
< a href =" foo.html " data-skip-me > Skip this link </ a >

Atribut yang dikonfigurasi dapat diisi dengan nilai apa pun atau tidak sama sekali. Spaghettify akan mengabaikan nilai itu.

Tip: Mengonfigurasi penangan beban khusus

Seperti yang telah kita lihat, opsi konfigurasi loadProgress dapat mengambil nilai primitif Boolean atau fungsi handler .

 < script type =" text/javascript " >
  new Spaghettify ( {
    loadProgress : true ,
  } ) ;
</ script >

Jika tidak dikonfigurasi secara eksplisit, atau disetel ke false , tidak ada indikator bilah kemajuan yang akan ditampilkan. Jika diberikan sebagai true , Spaghettify akan menampilkan indikator bilah kemajuan animasi berwarna merah di atas area pandang. Bilah kemajuan menunjukkan kemajuan pengunduhan sebenarnya.

Namun, konsumen mungkin ingin menerapkan solusi visual mereka sendiri untuk menampilkan informasi kemajuan pengunduhan. Spaghettify menutupinya dengan menyediakan pengendali kemajuan pemuatan yang mengharapkan parameter nilai bilangan bulat dalam tanda tangannya, yang akan mengambil nilai dari 0 hingga 100 saat halaman diminta dan diunduh melalui HXR.

 < script type =" text/javascript " >
  new Spaghettify ( {
    loadProgress : function onLoad ( progress ) {
      console . log ( progress ) ; // Will log values from 0 to 100
    } ,
  } ) ;
</ script >

Tip: Status tetap ada di seluruh navigasi

Spaghettify mengimplementasikan API eksperimental untuk mempertahankan status di node DOM yang dipilih dan diberi anotasi di seluruh navigasi halaman. Untuk melakukannya, Anda hanya perlu mengonfigurasi token nilai dalam opsi persistAttr dan kemudian memberi anotasi pada elemen DOM yang statusnya ingin Anda pertahankan dengan atribut data- yang setara dengan masing-masing nilai unik:

 < script type =" text/javascript " >
  new Spaghettify ( {
    persistAttr : 'persist-id' ,
  } ) ;
</ script >

< input type =" text " data-persist-id =" my-input " />

Anda dapat secara eksplisit mengawali nilai dengan data- atau tidak, namun Spaghettify akan mengharuskan Anda memberi anotasi pada elemen DOM agar tetap menggunakan sintaks atribut data lengkap.

Harap diperhatikan : Nilai atribut dimaksudkan agar unik. Spaghettify akan memunculkan pengecualian jika lebih dari satu elemen bertipe berbeda dikonfigurasi dengan nilai atribut yang sama.

Perlu digarisbawahi bahwa persistensi akan diterapkan pada basis DOM Node penuh, sehingga tidak hanya mencakup HTML bagian dalam elemen tetapi juga status asli yang disentuh untuk kontrol input. Dan semua ini terlepas dari perubahan pada HTML luar.

Menjalankan Spaghettify dalam mode pengembangan

Anda dapat membuat lingkungan pengembangan dengan menjalankan yarn dev atau npm run dev di konsol.

Sistem akan menghasilkan semua artefak dan menyajikan situs sandbox (detail lebih lanjut di bawah) dari http://localhost:3000 (atau port lain pilihan Anda jika Anda menambahkan parameter --port=PORT ke perintah dev , di mana PORT adalah port yang diinginkan) dalam mode jam tangan , sehingga aplikasi akan dikompilasi ulang jika terjadi perubahan pada kode sumber.

Situs kotak pasir

Situs sandbox adalah aplikasi web kecil dan sangat sederhana yang berfungsi sebagai taman bermain dan arena pengujian untuk debugging Spaghettify di lingkungan langsung. Ini menampilkan gaya yang cukup sederhana, melalui serangkaian halaman hierarki berbeda yang menggambarkan fitur-fitur utama berikut:

• index.html utama berisi instance Spaghettify inline untuk tujuan demo. Semua dokumen lain menerapkan contoh seperti skrip yang diimpor. Anda tidak perlu mengimpor Spaghettify pada setiap dokumen, cukup entri saja. Namun, ini memungkinkan untuk menjalankan Spaghettify dari dokumen apa pun setelah memuat ulang jendela browser untuk tujuan demo. Dalam skenario produksi nyata, Spaghettify dapat (dan harus) diimpor dan dibuat instance-nya hanya sekali di lokasi masuknya.
• Tautan ke Halaman B dikonfigurasi untuk melewati Spaghettify dan memaksa pemuatan halaman penuh. Karena diimpor ke sana, Spaghettify akan mengambil alih navigasi dari sana.
• Konten tersebar di antara tingkat akar /sandbox dan subfolder anak /sandbox/content sehingga kontributor dapat bermain-main dengan pemilih tautan yang menunjuk ke subfolder, jika perlu.
• Bagian utama berisi teks tiruan dengan sedikit variasi untuk memastikan transisi halaman terlihat jelas.
• Menu samping berisi beragam kontrol masukan untuk memvalidasi persistensi status di seluruh halaman yang dinavigasi.
• Laman A dan laman di dalam /sandbox/content memiliki fitur JavaScript khusus sebaris atau impor yang akan dicerna, dimasukkan kembali, dan dijalankan oleh Spaghettify bila diperlukan.
• Spaghettify mendukung navigasi riwayat maju dan mundur. Jelajahi sekitar dan cobalah!

Linting kontribusi kode Anda

ESLint saat ini diaktifkan di basis kode Spaghettify dan audit linting akan dipicu saat membangun proyek. Anda dapat mengonfigurasi IDE agar secara otomatis memberikan penilaian linting saat Anda melakukan perubahan. Selain itu, Anda dapat memicu linting kode kapan saja dengan menjalankan npm run lint atau yarn lint di konsol terminal Anda.

Menguji kontribusi kode Anda

Anda dapat memperkenalkan pengujian dalam basis kode atau menjalankan pengujian yang sudah ada dengan menjalankan npm test atau yarn test di konsol terminal Anda. Data cakupan kode dikumpulkan dan disimpan dalam dokumen dengan format mudah di /coverage/lcov-report . Untuk pelaporan cakupan di layar, harap tambahkan parameter --coverage ke perintah test .

Anda juga dapat memeriksa laporan cakupan tes komprehensif secara online di Coveralls.

Didistribusikan di bawah Lisensi MIT

Hak Cipta 2021 Pablo Deeleman

Izin dengan ini diberikan, secara gratis, kepada siapa pun yang memperoleh salinan perangkat lunak ini dan file dokumentasi terkait ("Perangkat Lunak"), untuk menggunakan Perangkat Lunak tanpa batasan, termasuk namun tidak terbatas pada hak untuk menggunakan, menyalin, memodifikasi, menggabungkan , mempublikasikan, mendistribusikan, mensublisensikan, dan/atau menjual salinan Perangkat Lunak, dan mengizinkan orang yang menerima Perangkat Lunak untuk melakukan hal tersebut, dengan tunduk pada ketentuan berikut:

Pemberitahuan hak cipta di atas dan pemberitahuan izin ini akan disertakan dalam semua salinan atau sebagian besar Perangkat Lunak.

PERANGKAT LUNAK INI DISEDIAKAN "APA ADANYA", TANPA JAMINAN APA PUN, TERSURAT MAUPUN TERSIRAT, TERMASUK NAMUN TIDAK TERBATAS PADA JAMINAN KELAYAKAN UNTUK DIPERDAGANGKAN, KESESUAIAN UNTUK TUJUAN TERTENTU, DAN TIDAK ADA PELANGGARAN. DALAM KEADAAN APA PUN PENULIS ATAU PEMEGANG HAK CIPTA TIDAK BERTANGGUNG JAWAB ATAS KLAIM, KERUSAKAN, ATAU TANGGUNG JAWAB LAINNYA, BAIK DALAM TINDAKAN KONTRAK, HUKUM ATAU LAINNYA, YANG TIMBUL DARI, ATAU SEHUBUNGAN DENGAN PERANGKAT LUNAK ATAU PENGGUNAAN ATAU HAL-HAL LAIN DALAM PERANGKAT LUNAK.