Susunan folder
Unduhan berisi dua jenis berkas: halaman jadi yang Anda buka di browser, dan sumber tempat halaman itu dirakit.
| Lokasi | Isinya |
|---|---|
*.html | Halaman jadi berbahasa Inggris, misalnya index.html. Dibuat oleh perakit — jangan disunting. |
id/ | Halaman jadi berbahasa Indonesia, dengan nama berkas yang sama. Dibuat oleh perakit — jangan disunting. |
assets/css/ | selaras.css — seluruh gaya Selaras. Semua kelas template berawalan sl-, jadi tidak pernah bertabrakan dengan Bootstrap atau CSS Anda sendiri. |
assets/js/ | selaras.js berjalan di setiap halaman (sidebar, panel pengaturan tampilan, grafik, pembantu bersama). Skrip lainnya milik satu aplikasi atau halaman dan hanya dimuat di tempat yang membutuhkannya. |
assets/vendor/ | Pustaka pihak ketiga dan font, satu folder per pustaka beserta lisensinya — lihat Pustaka & lisensi. Ditulis oleh tools/vendor.mjs dari daftar di vendor.json. |
assets/i18n/ | id.js — kamus Indonesia untuk teks yang ditulis JavaScript. Dibuat dari i18n/id.json. |
src/layout*.html | Kerangka halaman: layout.html (dasbor dan aplikasi, dengan sidebar dan bilah atas), layout-auth.html (halaman masuk), layout-error.html (404 dan 500), dan layout-store.html (toko untuk pembeli). |
src/partials/ | Potongan yang dipakai bersama oleh kerangka halaman: head.html (tag meta, font, stylesheet, dan skrip tema), symbols.html (tanda logo), customizer.html, kepala dan kaki halaman tanpa sidebar, serta panel merek halaman masuk (showcase-*.html). |
src/pages/ | Isi setiap halaman — satu berkas per halaman, diawali komentar pengaturan. |
i18n/ | id.json (kamus Indonesia), docs-id.json (kamus serupa untuk halaman dokumentasi ini), dan missing-id.txt (laporan teks yang belum punya terjemahan). |
tools/i18n/ | Pembantu Python untuk menambah terjemahan — lihat Bahasa. |
tools/check-contrast.py | Pemeriksaan kontras untuk tema warna — lihat Tema & tampilan. |
tools/vendor.mjs | Menyalin pustaka yang terdaftar di vendor.json ke assets/vendor/ — lihat Memperbarui pustaka. |
build.mjs | Skrip perakit. Di dalamnya juga ada menu sidebar dan daftar tema. |
Ubah sumbernya, bukan halamannya
Setiap halaman jadi adalah gabungan satu kerangka halaman, potongan bersama, dan satu berkas dari src/pages/. Sidebar, bilah atas, panel pengaturan tampilan, dan <head> ditulis sekali lalu dipakai ulang oleh setiap halaman, jadi perubahan di sana sampai ke semua halaman pada perakitan berikutnya.
Setiap kali dijalankan, semua berkas *.html di folder template dan di id/ ditulis ulang. Apa pun yang Anda ubah langsung di berkas itu hilang pada perakitan berikutnya — lakukan perubahannya di src/.
CSS dan JavaScript tidak dirakit: sunting berkas di assets/css/ dan assets/js/ secara langsung. Satu-satunya pengecualian adalah assets/i18n/id.js, yang ditulis perakit dari i18n/id.json.
Merakit halaman
Jalankan perakit dari folder template. Yang dibutuhkan hanya Node.js 18 atau lebih baru:
node build.mjs Untuk setiap berkas di src/pages/, perakit:
- membaca komentar pengaturan di baris pertama dan memilih kerangka halamannya;
- mengisi judul, breadcrumb, menu sidebar, serta stylesheet dan skrip tambahan;
- mengubah penanda kode menjadi potongan kode dengan tombol Salin;
- menulis halaman Inggris di sebelah
build.mjsdan halaman Indonesia keid/.
Perakit mencetak satu baris per halaman dan ringkasan di akhir. Teks yang belum punya terjemahan Indonesia dicatat di i18n/missing-id.txt, beserta halaman tempat teks itu muncul.
Merakit satu bahasa
Tambahkan --lang untuk merakit halaman Inggris saja atau Indonesia saja:
node build.mjs --lang en
node build.mjs --lang id Dengan --lang en, folder id/ dibiarkan apa adanya dan laporan terjemahan tidak ditulis. Dengan --lang id, hanya id/, assets/i18n/id.js, dan laporan terjemahan yang ditulis.
Menambah halaman
- Buat berkas di
src/pages/, misalnyasrc/pages/reports.html. Namanya menjadi nama halaman jadi (reports.htmldanid/reports.html). - Awali dengan komentar pengaturan, lalu tulis isi halamannya — hanya yang masuk ke area isi, tanpa
<html>,<head>, atau sidebar. - Opsional: tambahkan halaman ke menu sidebar (lihat Menu sidebar).
- Jalankan
node build.mjslalu bukareports.html.
<!--meta {"title":"Reports","active":"reports","crumbParent":"Pages","crumbHref":"pages-profile.html","crumb":"Reports","crumbIcon":"ti-report-analytics","scripts":["assets/js/reports.js"]} -->
<div class="sl-page-head">
<div>
<h1 class="sl-page-title">Reports</h1>
<p class="sl-page-sub">Monthly figures for the whole team.</p>
</div>
</div>
<section class="sl-card">
<div class="sl-card-head"><div><h2 class="sl-card-title">This month</h2><p class="sl-card-sub">Updated daily</p></div></div>
<!-- your content -->
</section> Salin komponennya dari UI Kit › Komponen — setiap contoh di sana punya tombol Lihat kode. Skrip yang Anda cantumkan di scripts dimuat sesudah selaras.js, jadi bisa memakai pembantunya.
Perakit juga menulis id/reports.html. Selama terjemahannya belum Anda tambahkan, teksnya tetap berbahasa Inggris dan dicatat di i18n/missing-id.txt — lihat Bahasa.
Pengaturan halaman
Baris pertama setiap berkas halaman adalah komentar yang diawali <!--meta dan berisi objek JSON. Isinya harus JSON yang sah: tanda kutip ganda di sekeliling setiap kunci dan teks, serta garis miring terbalik sebelum tanda kutip di dalam teks (lihat contoh di bawah). Inilah semua opsi yang dikenali perakit:
| Opsi | Fungsinya |
|---|---|
title | Wajib. Judul tab browser, diikuti “· Selaras Admin” (“· Selaras Store” di halaman toko). |
layout | Kerangka halaman: app (bawaan), auth, error, atau store — lihat di bawah. |
active | key item sidebar yang ditandai sebagai halaman yang sedang dibuka. |
crumb | Halaman saat ini di breadcrumb bilah atas. Diperlukan di halaman app. |
crumbIcon | Kelas ikon Tabler di depan crumb, misalnya ti-report-analytics. Diperlukan di halaman app. |
crumbParent | Bagian pertama breadcrumb. Bawaan: Dashboards. |
crumbHref | Tujuan tautan bagian pertama breadcrumb. Bawaan: index.html. |
actions | HTML yang ditaruh di bilah atas, sesudah tombol standar — misalnya tombol utama. Hanya di halaman app. |
scripts | Daftar URL skrip, dimuat di akhir halaman sesudah selaras.js. |
styles | Daftar URL stylesheet, dimuat sebelum selaras.css agar tampilan Selaras mengalahkan gaya bawaan pustaka. |
showcase | Hanya bersama "layout":"auth": panel merek di samping formulir — product, signup, atau security (dari src/partials/showcase-*.html). |
nav | docs menampilkan menu dokumentasi sebagai ganti menu utama. Dipakai oleh halaman dokumentasi ini. |
Contoh dengan tombol di bilah atas, diambil dari halaman Faktur:
<!--meta {"title":"Invoices","active":"invoices","crumbParent":"Apps","crumb":"Invoices","crumbIcon":"ti-file-invoice","actions":"<a class=\"sl-btn sl-btn-primary\" href=\"app-invoice-edit.html\"><i class=\"ti ti-plus\"></i><span>New invoice</span></a>","scripts":["assets/js/invoices.js"]} --> Kerangka halaman
| Tata letak | Dipakai untuk |
|---|---|
app | Dasbor, aplikasi, dan sebagian besar halaman: sidebar, bilah atas dengan breadcrumb, pencarian, tombol ganti bahasa, dan panel pengaturan tampilan. Memuat Bootstrap, ApexCharts, dan selaras.js. |
auth | Halaman masuk, daftar, dan sandi: tanpa sidebar, formulir di satu sisi dan panel merek opsional di sisi lain. Juga memuat auth.js. |
error | Halaman 404 dan 500: tanpa sidebar, isi di tengah. Juga memuat error.js. |
store | Toko untuk pembeli: kepala, keranjang, dan kaki halamannya sendiri sebagai ganti sidebar admin. Juga memuat ecommerce.js dan store.js. |
Potongan bersama disisipkan ke berkas kerangka halaman dengan {{> name}} di barisnya sendiri, yang memasukkan src/partials/name.html. Berkas halaman tidak bisa menyisipkan potongan bersama.
Menu sidebar
Sidebar didefinisikan sekali, di konstanta NAV dekat bagian atas build.mjs, lalu ditulis perakit ke setiap halaman app — jadi tidak mungkin ada dua halaman dengan menu yang berbeda. NAV adalah daftar grup; setiap grup punya label dan daftar items. Garis pemisah antargrup digambar otomatis.
Untuk menambah tautan, tambahkan item ke grup tempatnya:
{ label: 'Pages', items: [
{ key: 'profile', href: 'pages-profile.html', icon: 'ti-user-circle', text: 'Profile', keys: 'account me my user activity' },
// your new item:
{ key: 'reports', href: 'reports.html', icon: 'ti-report-analytics', text: 'Reports', keys: 'analytics monthly figures' },
…
]}, | Isian | Fungsinya |
|---|---|
key | Nama unik. Halaman yang pengaturan active-nya sama dengan kunci ini menandai item tersebut sebagai halaman yang sedang dibuka. |
href | Halaman tujuan tautan item. |
icon | Kelas ikon Tabler, misalnya ti-report-analytics. Semua ikon tercantum di UI Kit › Ikon. |
text | Label item, sekaligus tooltip tautannya. |
keys | Opsional. Kata pencarian tambahan untuk pencarian halaman di halaman 404 (“login” menemukan Sign in). |
popular | Opsional. true menampilkan halaman ini di halaman 404 sebelum pengunjung mengetik apa pun. |
sitemap | Opsional. false mengeluarkan halaman ini dari pencarian di halaman 404. |
soon | Opsional. true menampilkan item dalam keadaan nonaktif, dengan lencana “Soon”. |
Untuk mengganti nama, mengubah urutan, atau menghapus item menu, sunting NAV dengan cara yang sama lalu rakit ulang. Pencarian halaman di halaman 404 dibangun dari daftar yang sama, jadi selalu cocok dengan menunya. Menu dokumentasi yang Anda lihat di halaman ini adalah daftar terpisah, DOCS_NAV, di berkas yang sama.
Di halaman Indonesia, label menu baru tetap berbahasa Inggris sampai terjemahannya Anda tambahkan ke kamus.
Cache-busting
Perakit menambahkan versi ke setiap tautan stylesheet dan skrip lokal, misalnya assets/css/selaras.css?v=1a2b3c4d. Versinya diambil dari isi berkas, jadi hanya berubah kalau berkasnya berubah. Dengan begitu browser selalu memuat berkas baru sesudah pembaruan, bukan salinan lama dari cache-nya.
Ini berlaku untuk tautan di src="…" dan href="…" yang diawali assets/css/, assets/js/, atau assets/vendor/ — termasuk skrip dan stylesheet di pengaturan halaman Anda. Bila Anda mengubah berkas CSS atau JS, rakit ulang supaya halaman memakai versi barunya.
Potongan kode dan contoh hidup
Dua penanda di berkas halaman mengubah kode menjadi blok yang rapi. Setiap penanda berada di barisnya sendiri:
- Potongan kode —
<!--code Label-->, kodenya, lalu<!--/code-->. Perakit menampilkan kode dengan pewarnaan sintaks, labelnya (misalnyaHTMLatauTerminal), dan tombol Salin. Kode yang diawali tag diwarnai sebagai HTML; selebihnya sebagai JavaScript, CSS, atau shell. - Contoh hidup —
<!--demo-->, HTML-nya, lalu<!--/demo-->. Perakit menampilkan HTML itu sebagai contoh yang berfungsi dan menambahkan tombol Lihat kode dan Salin. Kode yang ditampilkan diambil dari contoh itu sendiri, jadi keduanya tidak pernah berbeda. Kelas tambahan untuk kotak contoh boleh ditulis sesudah katademo.
Tombol-tombol itu membutuhkan assets/js/components.js di scripts halaman. Bila perlu, tambahkan <p class="visually-hidden" id="cxLive" aria-live="polite"></p> ke halaman agar pembaca layar mengumumkan “Kode tersalin”.