EN

Berkas & perakitan

Susunan template, cara halaman dirakit, dan cara menambah halaman atau item menu.

Susunan folder

Unduhan berisi dua jenis berkas: halaman jadi yang Anda buka di browser, dan sumber tempat halaman itu dirakit.

LokasiIsinya
*.htmlHalaman 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*.htmlKerangka 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.pyPemeriksaan kontras untuk tema warna — lihat Tema & tampilan.
tools/vendor.mjsMenyalin pustaka yang terdaftar di vendor.json ke assets/vendor/ — lihat Memperbarui pustaka.
build.mjsSkrip 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.

Perakit menimpa halaman jadi

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:

Terminal
node build.mjs

Untuk setiap berkas di src/pages/, perakit:

  1. membaca komentar pengaturan di baris pertama dan memilih kerangka halamannya;
  2. mengisi judul, breadcrumb, menu sidebar, serta stylesheet dan skrip tambahan;
  3. mengubah penanda kode menjadi potongan kode dengan tombol Salin;
  4. menulis halaman Inggris di sebelah build.mjs dan halaman Indonesia ke id/.

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:

Terminal
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

  1. Buat berkas di src/pages/, misalnya src/pages/reports.html. Namanya menjadi nama halaman jadi (reports.html dan id/reports.html).
  2. Awali dengan komentar pengaturan, lalu tulis isi halamannya — hanya yang masuk ke area isi, tanpa <html>, <head>, atau sidebar.
  3. Opsional: tambahkan halaman ke menu sidebar (lihat Menu sidebar).
  4. Jalankan node build.mjs lalu buka reports.html.
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.

Salinan Indonesianya ikut dirakit

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:

OpsiFungsinya
titleWajib. Judul tab browser, diikuti “· Selaras Admin” (“· Selaras Store” di halaman toko).
layoutKerangka halaman: app (bawaan), auth, error, atau store — lihat di bawah.
activekey item sidebar yang ditandai sebagai halaman yang sedang dibuka.
crumbHalaman saat ini di breadcrumb bilah atas. Diperlukan di halaman app.
crumbIconKelas ikon Tabler di depan crumb, misalnya ti-report-analytics. Diperlukan di halaman app.
crumbParentBagian pertama breadcrumb. Bawaan: Dashboards.
crumbHrefTujuan tautan bagian pertama breadcrumb. Bawaan: index.html.
actionsHTML yang ditaruh di bilah atas, sesudah tombol standar — misalnya tombol utama. Hanya di halaman app.
scriptsDaftar URL skrip, dimuat di akhir halaman sesudah selaras.js.
stylesDaftar URL stylesheet, dimuat sebelum selaras.css agar tampilan Selaras mengalahkan gaya bawaan pustaka.
showcaseHanya bersama "layout":"auth": panel merek di samping formulir — product, signup, atau security (dari src/partials/showcase-*.html).
navdocs menampilkan menu dokumentasi sebagai ganti menu utama. Dipakai oleh halaman dokumentasi ini.

Contoh dengan tombol di bilah atas, diambil dari halaman Faktur:

HTML
<!--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 letakDipakai untuk
appDasbor, aplikasi, dan sebagian besar halaman: sidebar, bilah atas dengan breadcrumb, pencarian, tombol ganti bahasa, dan panel pengaturan tampilan. Memuat Bootstrap, ApexCharts, dan selaras.js.
authHalaman masuk, daftar, dan sandi: tanpa sidebar, formulir di satu sisi dan panel merek opsional di sisi lain. Juga memuat auth.js.
errorHalaman 404 dan 500: tanpa sidebar, isi di tengah. Juga memuat error.js.
storeToko 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.

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:

JavaScript
{ 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' },
  …
]},
IsianFungsinya
keyNama unik. Halaman yang pengaturan active-nya sama dengan kunci ini menandai item tersebut sebagai halaman yang sedang dibuka.
hrefHalaman tujuan tautan item.
iconKelas ikon Tabler, misalnya ti-report-analytics. Semua ikon tercantum di UI Kit › Ikon.
textLabel item, sekaligus tooltip tautannya.
keysOpsional. Kata pencarian tambahan untuk pencarian halaman di halaman 404 (“login” menemukan Sign in).
popularOpsional. true menampilkan halaman ini di halaman 404 sebelum pengunjung mengetik apa pun.
sitemapOpsional. false mengeluarkan halaman ini dari pencarian di halaman 404.
soonOpsional. 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 (misalnya HTML atau Terminal), 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 kata demo.

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”.