Rozšíření šablony pomocí vlastních filtrů

kap-modelova-implementace.tex

@@ -15,7 +15,34 @@ Pro správu obsahu i šablon a statických souborů byl zvolen systém Git. Hlav
 
 \section{Tvorba šablony}
 
-\begin{lstlisting}[caption="Shortcode pro přidání videa a volitelných metadat."]
+\section{Rozšíření šablony}
+
+Ve výchozím stavu generátor neumí vklládat nic jiného, než je uvedeno ve specifikaci CommonMark\footnote{\url{https://commonmark.org/}}. Dle požadavků modelového webu je nutné, aby generátor uměl vkládat videa přímo do stránky. Taková funkce není soušástí specifikace CommonMark a je tedy potřeba rozšířit funkcionalitu generátoru. Nejvhodnějším způsobem přidání vlastní funkce je využití vlastních filtrů, které se v rámci generátoru nazývají \uv{shortcode}.
+
+Principem vlastních filtrů je to, že uživatel si vytvoří vlastní šablonu, kterou lze vyvolat speciální řídící sekvencí přímo z obsahu. Každý tento shortcode může pracovat s libovolným množstvím proměnných a po zpracování vloží do místa vyvolání zkompilovaný HTML kód. Lze tedy tvrdit, že shortcode je v své podstatě imperativní funkce, která umí pracovat  s parametry.
+
+Pro tvorbu těchto filtrů je v generátoru Zola určena složka \texttt{templates/shortcodes}, která obsahuje jejich HTML šablony. Název HTML souboru definuje název vlastního filtru. Vytvoříme-li soubor \texttt{templates/shortcodes/video.html}, budeme schopni využívat vlastní filtr s názvem \texttt{video}.
+
+V následujícím příkladu bude filtr očekávat atribut \texttt{src} a bude vracet jednoduchý HTML kód pro vložení videa do stránky.
+\begin{lstlisting}
+<video controls><source src="{{ src }}"></video>
+\end{lstlisting}
+
+Tento filtr lze vyvolat kdekoliv v obsahu, tedy v kterémkoliv souboru s koncovkou \texttt{.md}.
+
+\begin{lstlisting}
+{{ video(src="video.webm") }}
+\end{lstlisting}
+
+Výstupem této direktivy bude následující HTML kód.
+
+\begin{lstlisting}
+<video controls><source src="video.webm"></video>
+\end{lstlisting}
+
+Součástí požadavků pro modelový web jsou i citace přiložených souborů a videí. Existující filtr je tedy třeba rozšířit o možnost přiložení různých metadat. Tato metadata ovšem nejsou pro vložení videa povinná. Ve specifikaci vlastních filtrů lze využívat všechny operátory, které generátor nabízí. Nejlepším přístupem k tomuto problému je tedy využití jednoduchých podmínek, které kontrolují, zda je každá z hodnot zadána jako parametr a v případě že ano, vepíše se do obsahu. V následujícím příkladu jsou přidány tři podmínky pro kontrolu a případné vložení, jimiž jsou název videa (\texttt{title}), jméno autora (\texttt{author}) a datum vytvoření (\texttt{date}).
+
+\begin{lstlisting}
 {% if title %}
 	<div class="title">{{ title }}</div>
 {% endif %}
@@ -28,6 +55,27 @@ Pro správu obsahu i šablon a statických souborů byl zvolen systém Git. Hlav
 {% endif %}
 \end{lstlisting}
 
+Pouze atribut \texttt{src} je podle tohoto filtru povinný. Filtr lze opět vyvolat pomocí stejné direktivy kdekoliv v obsahu, ovšem nyní lze libovolně přidat parametry pro metadata.
+
+\begin{lstlisting}
+{{ video(
+	src="video.webm",
+	title="Nazev videa",
+	author="Jmeno autora",
+	date="2020-03-22"
+) }}
+\end{lstlisting}
+\todo[inline]{Opravit háčky a čárky v blocích kódu.}
+
+Výtupem toho filtru bude tedy následující HTML.
+
+\begin{lstlisting}
+<div class="title">Nazev videa</div>
+<video controls><source src="video.webm"></video>
+<div class="metadata">Jmeno autora</div>
+<div class="metadata">2020-03-22</div>
+\end{lstlisting}
+
 \section{Optimalizace}
 
 \section{Požadavky na rozšíření}