Popis zdrojového kódu projektu

Na této stránce si můžete přečíst o zdrojovém kódu pro tento web, který je volně dostupný na GitHubu. Je mi úplně jedno zda se v tomto projektu něčím inspirujete nebo něco zkopírujete a použijete pro svůj vlastní projekt. Klidně si můžete zkopírovat i celý tento web (nemusíte ani upravovat design pokud nechcete) a přetvořit jej na web o něčem jiném. Byl bych spíš rád, že můj kód používáte, takže se nebojte úplně cokoliv z tohoto projektu vzít a případně si to upravit nebo vylepšit.

Jaké technologie jsou použity

V projektu jsou použity technologie, které popisuje následující tabulka.

Pokud tady na webu budete vytvářet tutoriál nebo článek, tak o TypeScriptu a Webpacku vůbec nemusíte vědět. V TypeScriptu je naprogramovaný systém pro ukázky kódu, který upravovat nebudete, a Webpack je již nakonfigurovaný. Pokud nebudete psát CSS styly, tak ani preprocesor Less nemusíte znát.

Souborová struktura projektu

V následující tabulce je popsáno, k čemu slouží kořenové složky projekty.

Kromě složek se v kořenové složce projektu nachází také pár souborů. Popisuje je následující ukázka.

Složka pages

Kořenová složka pages slouží k ukládání HTML stránek ve formě EJS souborů. Šablonovací jazyk EJS je použit, aby se nemusel kód, který se používá na více stránkách pracně ručně kopírovat. EJS totiž umožňuje do stránky vkládat obsah jiných souborů. Díky tomu nemusíme upravovat kód na desítkách různých místech, pokud chceme upravit nějaký kód, který je použit na více stránkách.

Následující tabulka popisuje složky a soubor, které složka pages obsahuje.

Každá stránka má EJS soubor pojmenovaný jako "index.ejs". Složka tutorial například obsahuje složky pro jednotlivé části tutoriálu a každá tento soubor obsahuje. Kromě toho se ještě ve většině složek (vlastně ve všech) nachází složka includes, kde se pro čistší HTML kód nachází kód pro různé ukázky kódu a slidery, které stránka používá. Díky tomu je samotný index.ejs soubor pro stránku relativně přehledný.

Složka less

Složka less obsahuje less soubory pro CSS styly. Obsahuje pár složek a hlavní soubor main.less, do kterého se importují všechny ostatní less soubory. Webpack tento soubor bere a generuje podle něj CSS soubor. Ostatní less soubory jsou rozděleny do složek podle 7-1 vzoru, o kterém si můžete více informací přečíst třeba zde. Také je dobré zmínit, že se pro psaní CSS stylů používá metodika BEM (Block Element Modifier). O té si můžete přečíst zde.

Následující tabulka alespoň krátce popisuje, co jednotlivé podsložky složky less uchovávají za soubory.

Složka ts

Složka ts obsahuje TypeScript soubory. Nachází se v ní dvě složky, které popisuje následující tabulka. Obě složky obsahují soubor main.ts, který je takovým hlavním souborem, který je zpracováván Webpackem a vytváří se podle něj JavaScript soubor.

Jak je nakonfigurován Webpack

Webpack je nastavený tak, že pomocí příkazu "npm run dev", si můžete web spustit pro vývoj (v prohlížeči se vám automaticky otevře stránka, nebo můžete navštívit http://localhost:3000/), nebo si web můžete sestavit pro produkci do složky "dist" spuštěním příkazu "npm run build". Pokud rozumíte Webpacku, tak se můžete podívat do souborů webpack.common.js, webpack.dev.js a webpack.prod.js, jak je pro projekt nakonfigurovaný. Pokud ale ne, tak bych to tu chtěl jen krátce popsat.

Webpack po spuštění příkazu "npm run build" dělá následující věci:

• V kořenové složce vytvoří složku dist, ve které bude sestavený web pro produkci.
• Vytvoří HTML stránku pro domovskou stránku webu.
• Vytvoří HTML stránky pro stránky tutoriálu.
• Vytvoří HTML stránky pro stránky v sekci "Další tutoriály".
• Vytvoří HTML stránku popisující zdrojový kód projektu.
• Vytvoří CSS soubor podle less souborů (tento soubor je automaticky připojen na každou HTML stránku).
• Vytvoří JavaScript soubor podle souboru main.ts, který se nachází ve složce ts/common. Tento soubor se automaticky připojuje na každou HTML stránku.
• Vytvoří JavaScript soubor podle soubor main.ts, který se nachází ve složce ts/tutorial-page. Tento soubor se automaticky připojuje na každou HTML stránku s tutoriálem.
• Zkopíruje složku static do složky dist.
• Podle souboru main.js, který se nachází ve složce icons vytvoří SVG sprite, který umístí do složky static.

Chtěl bych jen upozornit, že pro spuštění webu na svém PC budete potřebovat mít nainstalovaný Node.js. Před spuštěním příkazu "npm run dev" nebo "npm run build" je také potřeba nejdříve nainstalovat NPM balíčky specifikované v souboru package.json příkazem "npm install".

Další věc, na kterou bych chtěl upozornit je ta, že pokud přidáváte do složky dalsi-tutorialy (nebo složky tutorial) novou stránku a máte spuštěný Webpack pro vývoj, tak je potřeba Webpack restartovat, aby se stránka přidala. Také bych chtěl zmínit, že občas Webpack může vypisovat chybu ohledně less souborů. V takovém případě je nutné nějaký less soubor přeuložit. Nepodařilo se mi přijít na to, proč se to děje.

Jak fungují ukázky kódu

Na webu se nachází spousta ukázek kódu. Některé se zobrazují jen v jednoduchém boxu, jiné mohou být zase zobrazené jako součást nějakého projektu. Pokud jste si tutoriál četli, nebo si jej jen letmo prohlédli, tak asi víte co tím myslím. Tyto ukázky se mohou skládat z následujících komponent (ne všechny se pro každou ukázku používají):

• Code box - Element, který představuje celou ukázku.
• Elementy s kódy - Code box může obsahovat jeden či více elementů s kódy (ukázky kódu).
• File elementy - Code box může kromě elementů s kódy obsahovat také soubory, které se nedají zobrazit, ale lze je stáhnout (např. obrázky).
• Složky projektu - Pokud je code box (ukázka) zobrazen jako projekt, tak může obsahovat element, který definuje složky projektu.
• Container s příkazy - Pokud je code box (ukázka) zobrazen jako projekt, tak může obsahovat příkazy, které se mají pro ukázku vykonat (například smazání souboru, atp.).

Nejprve si projdeme jednotlivé komponenty ukázky, popíšeme si různé atributy, které jim můžeme nastavit, a tak podobně. Až poté si ukážeme příklady vytvoření ukázky.

Code box

Code box je element, který vlastně představuje celou ukázku. Pokud elementu nastavíme atribut "data-code-box" nebo "data-project", tak tím nastavujeme, že se jedná o ukázku.

<div data-code-box>
    /* ... */
</div>

Následující tabulka popisuje také další atributy, které můžeme pro code box nastavit.

Elementy s kódy

Uvnitř code boxu se může nacházet jedna nebo více ukázek kódu (elementů s kódy). Ukázku představuje pre element, který má jako podelement element code a nastavený atribut data-code.

<div data-code-box>
    <pre data-code="main.js"><code class="language-javascript">let x = 1;
let y = 2;

console.log(x + y);</code></pre>
</div>

Následující tabulka popisuje, co všechno můžeme pro ukázku kódu nastavit.

Podle toho, co za kód zobrazujeme, musíme v code elementu specifikovat CSS třídu, aby se nám kód správně zvýrazňoval. V současné době je podporován jazyk HTML, XML, Java, JavaScript, CSS, SQL, LESS, TypeScript a JSON. Podporu pro více jazyků je ale možno přidat změněním souboru highlight.min.js ve složce static/js. Následující seznam popisuje CSS třídy, které můžeme code elementu nastavit:

• language-html - HTML
• language-xml - XML
• language-java - Java
• language-javascript - JavaScript
• language-css - CSS
• language-sql - SQL
• language-less - LESS
• language-typescript - TypeScript
• language-json - JSON
• no-highlight - vypne zvýrazňování kódu

File elementy

Code box může kromě elementů s kódy obsahovat také soubory, které se nedají zobrazit, ale mohou být staženy (např. obrázky). Takové soubory představují elementy, které mají jako atribut nastavený atribut data-file.

<div data-code-box>
    <div data-file="../../static/download/Picture.png">Picture.png</div>
</div>

Název souboru se nastavuje jako obsah file elementu. Následující tabulka popisuje, co dalšího můžeme pro file elementy nastavovat pomocí data atributů.

Složky projektu

Pokud je code box zobrazen jako projekt, tak může obsahovat ul element, který definuje adresářovou strukturu projektu. Tento element musí obsahovat atribut data-project-folders. Následující ukázka ukazuje příklad takového elementu.

<div data-project="1">
    <ul data-project-folders>
        <li>
            src
            <ul>
                <li>
                    main
                    <ul>
                        <li data-java-packages-folder>java</li>
                        <li>resources</li>
                        <li>webapp</li>
                    </ul>
                </li>
                <li>
                    test
                    <ul>
                        <li>java</li>
                        <li>resources</li>
                    </ul>
                </li>
            </ul>
        </li>
        <li>target</li>
    </ul>
</div>

Následující tabulka popisuje kromě atributu data-project-folders ještě dva další atributy, které se nastavují na li elementy představující složky.

Container s příkazy

Pokud je code box zobrazen jako projekt, tak může obsahovat různé příkazy, které se mají vykonat. Můžeme například nastavit, aby se smazal nějaký soubor, otevřela se nějaká složka, a tak podobně. Příkazy se definují v ul elementu, který má nastavený data-project-commands atribut. Následující ukázka ukazuje, jak to může vypadat.

<div data-project="2" data-project-extends="1">
    <ul data-project-commands>
        <li data-command-create-folder>src/main/webapp/WEB-INF</li>
        <li data-command-open-folder-to-root>src/main/webapp/WEB-INF</li>
    </ul>
    <pre data-code="web.xml" data-folder="src/main/webapp/WEB-INF" data-active><code class="language-xml">&lt;web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" 
id="WebApp_ID" version="3.0"&gt;
&lt;/web-app&gt;</code></pre>
</div>

Co všechno můžeme použít za příkazy popisuje následující tabulka.

Příklady tvorby ukázky

V předchozích tabulkách jste si mohli prohlédnout, co se dá různým komponentám ukázky nastavovat za atributy. Teď si pár ukázek zkusíme vytvořit.

Začneme tím, že si zkusíme vytvořit úplně jednoduchou ukázku, která zobrazuje jen nějaký kód bez žádných tlačítek ani postranního panelu. Jak to můžeme udělat ukazuje následující ukázka. Elementu, který chceme použít jako ukázku nastavujeme atribut data-code-box a také mu nastavujeme atribut data-no-buttons, aby se nezobrazili žádná tlačítka.

<div data-code-box data-no-buttons class="u-mb-2">
    <pre data-code><code class="language-javascript">let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));</code></pre>
</div>

Následující ukázka je výsledkem kódu v předchozí ukázce.

let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));

Teď si zkusíme vytvořit ukázku, ve které bude více ukázek kódu a uživatel se mezi nimi bude moci přepínat pomocí tlačítek. Následující ukázka ukazuje, jak takovou ukázku můžeme vytvořit.

<div data-code-box class="u-mb-2">
    <pre data-code="výpočet"><code class="language-javascript">let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));</code></pre>
    <pre data-code="spojování řetězců"><code class="language-javascript">let retezec1 = "Toto je";
let retezec2 = " řetězec.";

console.log(retezec1 + retezec2);</code></pre>
</div>

Následující ukázka je výsledkem kódu v předchozí ukázce.

let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));

let retezec1 = "Toto je";
let retezec2 = " řetězec.";

console.log(retezec1 + retezec2);

Nyní si zkusíme vytvořit ukázku ve formě projektu. Následující ukázka pro ni ukazuje kód.

<div data-project="1" data-project-name="muj-projekt" class="u-mb-2">
    <ul data-project-folders>
        <li data-opened>js</li>
        <li>css</li>
    </ul>
    <pre data-code="main.js" data-folder="js" data-active><code class="language-javascript">let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));</code></pre>
</div>

Následující ukázka je výsledkem kódu v předchozí ukázce.

let x = 1;
let y = 2;

console.log("výsledek: " + (x + y));

Na závěr si vyzkoušíme vytvořit ukázku ve formě projektu, rozšířením jiné ukázky ve formě projektu. To uděláme pomocí atributu data-project-extends, kde specifikujeme ID ukázky, kterou chceme rozšířit. Rozšíříme si předchozí ukázku a přidáme do ní nový CSS soubor. Následující ukázka ukazuje, jak na to.

<div data-project="2" data-project-extends="1" class="u-mb-2">
    <ul data-project-commands>
        <li data-command-open-folder>css</li>
    </ul>
    <pre data-code="style.css" data-folder="css" data-active><code class="language-css">h1 {
    font-size: 16px;
    color: red;
}</code></pre>
</div>

Následující ukázka je výsledkem kódu v předchozí ukázce.

h1 {
    font-size: 16px;
    color: red;
}

Pro pochopení jak ukázky kódu fungují to pravděpodobně stačilo. Klidně se ještě můžete podívat na kód ukázek přímo ve zdrojovém kódu projektu.

Jak fungují slidery

Slidery jsou vytvářeny za použití knihovny Splide. Následující ukázka ukazuje příklad tvorby slideru. Používá se lazy loading. Pro první dva obrázky se nastavuje atribut src, ale pro další už atribut data-splide-lazy.

<div data-slider class="splide u-mb-2" role="group" aria-label="Vyřešení Javadoc chyby v Eclipse IDE">
    <div class="splide__track">
        <ul class="splide__list">
            <li class="splide__slide">
                <div class="slider-page">
                    <img src="../../static/img/sliders/eclipse-javadoc-error/eclipse-javadoc-error-part1.png" alt="Vyřešení Javadoc chyby v Eclipse IDE - část 1" class="slider-page__image">
                    <div class="slider-page__description">
                        <p class="paragraph">Po otevření pom.xml vidíme, že nám Eclipse hlásí chybu.</p>
                    </div>
                </div>
            </li>
            <li class="splide__slide">
                <div class="slider-page">
                    <img src="../../static/img/sliders/eclipse-javadoc-error/eclipse-javadoc-error-part2.png" alt="Vyřešení Javadoc chyby v Eclipse IDE - část 2" class="slider-page__image">
                    <div class="slider-page__description">
                        <p class="paragraph">V horním menu klikneme na "Window" a vybereme "Preferences".</p>
                    </div>
                </div>
            </li>
            <li class="splide__slide">
                <div class="slider-page">
                    <img data-splide-lazy="../../static/img/sliders/eclipse-javadoc-error/eclipse-javadoc-error-part3.png" alt="Vyřešení Javadoc chyby v Eclipse IDE - část 3" class="slider-page__image">
                    <div class="slider-page__description">
                        <p class="paragraph">Otevřelo se nám okno, ve kterém vybereme "Maven" a zaškrtneme "Download Artifact Javadoc". Poté klikneme na tlačítko "Apply and Close".</p>
                    </div>
                </div>
            </li>
        </ul>
    </div>
</div>

Kód z předchozí ukázky vytváří následující slider.