Spletno stran Kako začeti izdelamo kot prvo dokumentacijsko podstran vzorčnega spletišča. Namenjena je razlagi osnovnih korakov za vključitev Bootstrapa, pripravi začetne HTML strukture, razumevanju prenosov, uporabi CDN povezav in pregledu osnovnih nastavitev.
Stran pripravimo s pomočjo že izdelane strani bootstrap.html. Iz nje naredimo kopijo z imenom zacetek.html, ki jo shranimo v mapo dokument. Nato stran prilagodimo dokumentacijski postavitvi z levim stranskim menijem in več vsebinskimi poglavji.
Pomni: Dokumentacijska stran mora biti posebej pregledna. Uporabnik jo pogosto bere zato, da hitro najde navodilo, primer kode ali razlago določenega pojma.
Osnovna pravila izdelave dokumentacijske strani
Dokumentacijska stran se razlikuje od predstavitvene strani. Njena glavna naloga ni samo predstavitev vsebine, ampak tudi razlaga postopkov, pojmov in primerov kode. Zato mora imeti jasno strukturo, stranski meni, urejene naslove, kratke razlage in pregledno zapisane primere.
| Področje | Priporočilo |
|---|---|
| Mapa dokumentacije | Dokumentacijske strani shranimo v ločeno mapo, na primer dokument. |
| Povezave do datotek | Ker je stran v podmapi, morajo biti poti do slik, CSS datotek in drugih strani ustrezno prilagojene. |
| Stranski meni | Meni naj vsebuje povezave na glavna poglavja znotraj strani. |
| Primeri kode | Koda naj bo kratka, pravilno zamaknjena in neposredno povezana z razlago. |
| Odzivnost | Postavitev naj se na manjših zaslonih spremeni v en stolpec. |
Pozor: Pri premiku strani v podmapo je treba popraviti relativne poti. Povezava css/slog.css na primer v podmapi ne kaže več na isto mesto kot na domači strani, zato jo zapišemo kot ../css/slog.css.
Predloga navigacije, naslova in noge spletne strani
V datoteki zacetek.html obdržimo glavo dokumenta, navigacijo, glavni naslov strani in nogo. Spremenimo naslov dokumenta, meta opis, besedilo glavnega naslova in uvodni opis, da ustrezajo dokumentacijski strani Kako začeti.
Ker je datoteka shranjena v mapi dokument, moramo povezave do slik in slogovnih datotek zapisati z ustrezno potjo. Zato je povezava do lastne slogovne datoteke zapisana kot ../css/slog.css, povezava do ikone spletišča pa kot ../slike/favicon.ico.
Predloga nove strani uporablja Bootstrap 5, enotno navigacijo in glavo z razredom page-hero:
<!DOCTYPE html>
<html lang="sl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Dokumentacija Bootstrapa: kako začeti.">
<meta name="keywords" content="Bootstrap, odzivno oblikovanje, mrežni sistem, komponente, dokumentacija">
<meta name="author" content="eNSA">
<title>eNSA | Spletišče: Kako začeti</title>
<link rel="icon" href="../slike/favicon.ico" type="image/x-icon">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../css/slog.css">
</head>
<body>
<nav class="navbar navbar-expand-lg navbar-light site-navbar sticky-top">...</nav>
<header class="page-hero">
<div class="container">
<h1>Kako začeti</h1>
<p class="lead mb-0">Osnovni koraki za vključitev Bootstrapa v projekt in razumevanje, kaj vsebuje ogrodje.</p>
</div>
</header>
<footer>...</footer>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>Pomni: Pri dokumentacijskih straneh so relativne poti zelo pomembne. Če se stran nahaja v podmapi, se morajo povezave do skupnih datotek začeti z ../.
Postavitev dokumentacije in stranski meni
Pod glavo strani vstavimo dokumentacijsko postavitev z dvema deloma: levo je stranski meni, desno pa vsebina. Stranski meni vsebuje povezave do posameznih poglavij na isti strani. Tako uporabnik lažje najde razlago, ki jo potrebuje.
Za postavitev uporabimo lastne razrede doc-layout, doc-sidebar in doc-content. Na večjih zaslonih sta meni in vsebina prikazana drug ob drugem, na manjših zaslonih pa se zložita v en stolpec.
Stranski meni vsebuje povezave na sidra posameznih poglavij znotraj iste strani:
<section class="py-5">
<div class="container">
<div class="doc-layout">
<aside class="doc-sidebar">
<h2 class="h5 mb-3">Vsebina strani</h2>
<a href="#uvod">Uvod</a>
<a href="#hiter-zacetek">Hiter začetek</a>
<a href="#prenos">Prenos</a>
<a href="#cdn">Bootstrap CDN</a>
<a href="#vsebina">Vsebina paketov</a>
<a href="#naprave">Brskalniki in naprave</a>
<a href="#javascript">JavaScript</a>
<a href="#opcije">Globalne opcije</a>
</aside>
<div class="doc-content">
...
</div>
</div>
</div>
</section>Primer slogov za dokumentacijsko postavitev:
.doc-layout{
display:grid;
grid-template-columns:280px 1fr;
gap:2rem;
}
.doc-sidebar{
background:#f8f9fa;
border-radius:1rem;
padding:1.25rem;
align-self:start;
}
.doc-sidebar a{
display:block;
padding:.35rem 0;
color:#553d7b;
text-decoration:none;
}
.doc-sidebar a:hover{
text-decoration:underline;
}
@media (max-width: 991px){
.doc-layout{
grid-template-columns:1fr;
}
}Pozor: Povezave v stranskem meniju morajo kazati na obstoječe elemente z enakimi vrednostmi atributa id. Če povezava kaže na #uvod, mora imeti ustrezno poglavje atribut id="uvod".
Vsebina: Uvod in Hiter začetek
V vsebinski del dodamo prva dva razdelka: Uvod in Hiter začetek. V uvodu pojasnimo, čemu je Bootstrap namenjen. V hitrem začetku prikažemo minimalen HTML dokument, v katerega sta vključeni Bootstrapova CSS in JavaScript datoteka.
Primer mora vsebovati HTML5 ogrodje, oznako viewport, povezavo do Bootstrapove CSS datoteke in povezavo do datoteke bootstrap.bundle.min.js. Tako uporabnik vidi najmanjšo potrebno strukturo za začetek dela.
<section id="uvod" class="mb-5">
<h2>Uvod</h2>
<p>Bootstrap je namenjen hitri pripravi odzivnih spletišč. Vključuje mrežni sistem, komponente, pomožne razrede in JavaScript dodatke.</p>
<p>Dobro je začeti z minimalno strukturo strani, nato pa postopno dodajati postavitev, komponente in lastne sloge.</p>
</section>
<section id="hiter-zacetek" class="mb-5">
<h2>Hiter začetek</h2>
<p>Najhitrejša pot je vključitev Bootstrap CSS datoteke v glavo dokumenta in Bootstrap JavaScript datoteke pred zaključno oznako body.</p>
<pre><code><!doctype html>
<html lang="sl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
<h1 class="container py-5">Pozdravljen, Bootstrap!</h1>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html></code></pre>
</section>Vsebina: Prenos in Bootstrap CDN
Naslednja razdelka pojasnita razliko med lokalnim prenosom datotek in uporabo CDN povezav. CDN omogoča hiter začetek, ker datotek ni treba shraniti v projekt. Prenos datotek pa je primeren takrat, ko želimo imeti več nadzora nad datotekami ali delati brez zunanjih povezav.
| Način | Značilnost | Primer uporabe |
|---|---|---|
| CDN | Datoteke se naložijo z zunanjega strežnika. | Učenje, hitri primeri, prototipi. |
| Lokalni prenos | Datoteke shranimo v mapo projekta. | Projekt, ki naj deluje tudi brez zunanjih povezav. |
| Paketni upravljalnik | Bootstrap namestimo kot paket, na primer z npm. | Večji projekti in sodoben razvojni potek. |
<section id="prenos" class="mb-5">
<h2>Prenos</h2>
<p>Če želimo delati brez zunanjih povezav, lahko prenesemo prevedene datoteke in jih dodamo v lasten projekt.</p>
<p>Pri tem moramo pravilno povezati datoteke CSS in JavaScript ter paziti na urejeno strukturo map.</p>
</section>
<section id="cdn" class="mb-5">
<h2>Bootstrap CDN</h2>
<p>CDN omogoča hiter začetek, saj datotek ni treba shranjevati lokalno.</p>
<p>V glavo dokumenta vključimo Bootstrapovo CSS datoteko, pred zaključno oznako body pa Bootstrapovo JavaScript datoteko.</p>
</section>Pomni: CDN je primeren za hiter začetek in učne primere. Pri večjih projektih je pogosto smiselno razmisliti o lokalnih datotekah ali namestitvi prek paketnega upravljalnika.
Vsebina: Vsebina paketov
V razdelku Vsebina paketov pojasnimo razliko med prevedenim paketom in izvorno kodo. Prevedeni paket vsebuje pripravljene datoteke CSS in JavaScript, ki jih lahko neposredno vključimo v projekt. Izvorna koda pa vsebuje tudi Sass datoteke in druge vire, ki so namenjeni prilagajanju in gradnji lastne različice.
<section id="vsebina" class="mb-5">
<h2>Vsebina paketov</h2>
<p>V prevedenem paketu najdemo predvsem datoteke CSS in JavaScript, ki jih lahko neposredno uporabimo v projektu.</p>
<p>Če potrebujemo več prilagoditev, lahko uporabimo izvorne datoteke in Bootstrap prilagodimo z orodji za gradnjo projekta.</p>
<pre><code>bootstrap/
├── css/
├── js/
└── icons/ (če jih dodamo posebej)</code></pre>
</section>Vsebina: Brskalniki in naprave
Razdelek Brskalniki in naprave poudari mobilno usmerjen pristop. Bootstrapova postavitev je zasnovana tako, da najprej upoštevamo manjše zaslone, nato pa postavitev postopno prilagajamo večjim zaslonom.
Pri dokumentaciji je smiselno poudariti, da samo uporaba Bootstrapa še ne zagotavlja dobre uporabniške izkušnje. Stran je treba preveriti v različnih brskalnikih in pri različnih širinah zaslona.
<section id="naprave" class="mb-5">
<h2>Brskalniki in naprave</h2>
<p>Bootstrap temelji na mobilno usmerjenem pristopu, zato se postavitev najprej prilagodi manjšim zaslonom.</p>
<p>Pri izdelavi strani je treba preveriti prikaz na telefonu, tablici in večjem zaslonu.</p>
<div class="doc-figure mt-3">
<img src="../slike/dokumentacija/devices.png" alt="Različne naprave">
</div>
</section>Pozor: Odzivnosti ne preverjamo samo z zmanjšanjem okna brskalnika. Priporočljivo je preveriti tudi dejanski prikaz na mobilni napravi ali z orodji za razvoj v brskalniku.
Vsebina: JavaScript
Razdelek JavaScript pojasni, da interaktivne Bootstrapove komponente potrebujejo JavaScript. Med take komponente spadajo na primer spustni meniji, zložljivi elementi, modalna okna, namigi in vrtiljaki.
Za večino osnovnih primerov je najpreprostejša vključitev datoteke bootstrap.bundle.min.js. Ta datoteka vključuje Bootstrapove JavaScript dodatke in podporo za Popper, ki jo potrebujejo nekatere komponente.
<section id="javascript" class="mb-5">
<h2>JavaScript</h2>
<p>Interaktivne komponente, kot so dropdown meni, collapse, modal, tooltip ali carousel, potrebujejo JavaScript.</p>
<p>V osnovnih projektih praviloma zadostuje ena bundle datoteka, ki vključuje vse potrebno za delovanje večine komponent.</p>
<pre><code><script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"></script></code></pre>
</section>Vsebina: Globalne opcije
V razdelku Globalne opcije pojasnimo osnovna pravila, ki vplivajo na celotno stran. Sem spadajo HTML5 ogrodje, oznaka viewport, pravilen vrstni red vključevanja datotek, dostopnost, semantična struktura in odgovorna uporaba pripravljenih razredov.
Bootstrap veliko osnovnih slogov ponudi že privzeto, vendar to ne pomeni, da lahko zanemarimo kakovost HTML strukture. Razvijalec mora še vedno skrbeti za pravilne naslove, smiselna nadomestna besedila, jasne povezave in dobro razporeditev vsebine.
<section id="opcije" class="mb-5">
<h2>Globalne opcije</h2>
<p>Pri vseh komponentah je smiselno paziti na dostopnost: pravilne oznake, uporabne nadomestne opise, kontrast besedila in razumljivo strukturo vsebine.</p>
<p>Bootstrap veliko od tega ponudi že privzeto, vendar mora razvijalec vseeno skrbeti za ustrezno uporabo razredov in semantičnih elementov.</p>
</section>Priporočila za izdelavo dokumentacijske strani
- Dokumentacijsko stran shrani v ustrezno mapo in prilagodi relativne poti.
- V stranskem meniju uporabi povezave do glavnih poglavij na strani.
- Naslovi poglavij naj bodo kratki, jasni in zapisani v pravilnem zaporedju.
- Primere kode zapiši pregledno in jih neposredno poveži z razlago.
- Pri hitrem začetku prikaži minimalno delujočo strukturo HTML dokumenta.
- Razlikuj med CDN vključitvijo, lokalnimi datotekami in paketnim upravljalnikom.
- Pri interaktivnih komponentah preveri, ali je vključena Bootstrapova JavaScript datoteka.
- Stran preveri na manjših in večjih zaslonih.
Pogoste napake
- Po premiku strani v podmapo relativne poti do CSS datotek, slik ali povezav niso popravljene.
- Stranski meni vsebuje povezave na sidra, ki na strani ne obstajajo.
- V dokumentu manjka meta oznaka
viewport, zato se stran na mobilnih napravah ne prikazuje pravilno. - Bootstrapova JavaScript datoteka ni vključena, zato interaktivne komponente ne delujejo.
- Primeri kode so predolgi ali niso neposredno povezani z razlago.
- V isti strani so uporabljeni primeri kode iz različnih različic Bootstrapa.
- Dokumentacijska stran nima jasne razdelitve na poglavja.
- Slike in povezave nimajo dovolj razumljivih opisov.