jComponent - Ako na vlastný komponent #1

Séria Ako na vlastný komponent bude venovaná jComponentu. Ak neviete, čo je to jComponent, tak vám odporúčam článok od Petra Širku. V tejto časti si vytvoríme náš úplne prvý komponent. A potom z neho urobíme real-time hodinky.

Prečo vlastný komponent?

Toto je fakt dobrá otázka. Componentator.com obsahuje neuveriteľných 171 komponentov a je komponent už pomaly na všetko. No niekedy to nestačí. Možno sa vám žiadny do vášho projektu nehodí, možno taký ešte neexistuje a možno sa chcete posunúť ďalej. Prejsť z konzumenta na autora. Okrem vytvorenia úplne vlastnej komponenty je tu ešte jedna možnosť - obaliť existujúcu knižnicu jComponentom.

Obaliť existujúcu knižnicu jComponentom?

Prečo by ste to robil? Odpovedí je hneď niekoľko.

• jednotná práca v celom projekte
• lazy load/dynamické načítavanie
• zjednodušenie práce s knižnicou
• znovupoužiteľnosť v inom projekte (stačí tam pacnuť komponentu a môžete pracovať)
• pretože prečo nie?

My sme si takto obalili napríklad Fullcalendar v3 a CKEditor 4.

Predtým, než začneme

Áno. Už sa k tomu dostaneme. Už začneme robiť vlastný komponent. Prisahám Sľubujem. Len toto je dosť podstatné - nenechajte sa odradiť veľkou škálou možností. jComponent toho ponúka vážne veľa a to aj pri tvorbe komponenty. Čo sa snažím povedať je, že nemusíte používať a chápať všetko aby ste začali. (a už vôbec nie hneď od začiatku)

Začíname

Najjednoduchší spôsob ako začať je ísť na HTML5 Template, stiahnuť si ho a otvoriť vo svojom obľúbenom editore. Okrem toho si otvoríme jComponent dokumentáciu a to predovšetkým 05. Component.

Budeme potrebovať to najdôležitejšie - metódu COMPONENT

COMPONENT(name, [config], declaration, [dependencies]);
// @name {String}
// @config {String} A default configuration
// @declaration {Function(instance, config)}
// @dependencies {Array String} +v12.0.4 optional, can contain URL addresses (script, styles, etc.) to all dependencies

Takže do nášho webu si dáme

<script>
COMPONENT('mycomponent', function(self, config) {

});
</script>

Máme našu prvú vlastnú komponentu. Ale predtým, ako budeme pokračovať, by som vám chcel vysvetliť, že názvy parametrov vo funkcii (self a config) odporúčam zachovať. To, že inštanciu máme rovno z funkcie je super užitočná vec. Inak by pod každým komponentom bolo treba písať var self = this; takže sme ušetrili 12 znakov v každej komponente. No neberte to.

To je všetko?

Nie. Našťastie toto nie je všetko, čo jComponent umožnuje. Komponenta má vlastnosti (properties), metódy (methods) a delegácie (delegates). Vlastnosti a metódy asi netreba predstavovať. A delegácie sú funkcie, ktoré komponent spúšťa. Napríklad self.make sa spustí keď sa vytvára komponent. Upravíme náš komponent tak, že pri vytváraní komponenty vypíše správu do konzole.

<script>
COMPONENT('mycomponent', function(self, config) {
    self.make = function() {
        console.log('Ahoj');
    };
});
</script>

Dáme si to na web, refreshneme, otvoríme konzolu a... Nič. Konzola je prázdna. Samozrejme, že je prázdna. Komponent sme nikde nepoužili. Takže sa vrátime a niekde deklarujeme komponent:

<div data---="mycomponent"></div>

Ak by sme nakopírovali viacero deklarácií, tak budeme mať aj viacero správ v konzole.

DOM element

Čítanie dokumentácie je vždy polovica úspechu. Medzi vlastnosťami máme self.element ktorý nám vracia jQuery element. Ten obsahuje element našej deklarácie. Takže náš ďalší krok je vypísať Ahoj na stránke

<script>
COMPONENT('mycomponent', function(self, config) {
    self.make = function() {
        self.element.text('Ahoj');
    };
});
</script>

Jednoduché, no nie? Teraz sa posunieme k našej dnešnej úlohe.

Zobrazenie času

Ako som už na začiatku spomínal, v tomto dieli si urobíme hodinky. Začneme od toho jednoduchšieho - zobrazíme čas.

<script>
COMPONENT('mycomponent', function(self, config) {
    self.make = function() {
        self.element.text(new Date());
    };
});
</script>

Už to vyzerá ako hodinky. Ale nič sa s nimi nedeje - čas sa neposúva. Asi budeme potrebovať timer. Najlepšie na JavaScripte je to, že každá vec sa dá zapísať veľa spôsobmi.

<script>
COMPONENT('mycomponent', function(self, config) {
    self.make = function() {
        setInterval(self.timer, 1000);
    };
    
    self.timer = function() {
        self.element.text(new Date());
    };
});
</script>

Wuala, už máme real-time hodinky. Môžme si ho deklarovať koľkokrát chceme a bude to fungovať krásne. Ale niečo tomu chýba...

Čtateľný zápis

Tu si pomôžeme zase jComponentom

<script>
COMPONENT('mycomponent', function(self, config) {
    self.make = function() {
        setInterval(self.timer, 1000);
    };
    
    self.timer = function() {
        var time = new Date().format('HH:mm:ss'); // Naformátujeme dátum
        self.element.text(time);
    };
});
</script>

No, už je to super. Alebo nie? Čo ak by som chcel niekde zobraziť aj dátum? Alebo iba minúty a sekundy?

Konfigurácia

Budeme sa musieť vrátiť na začiatok. Pozrieme si metódu COMPONENT a jej parametre. Hneď druhý parameter je voliteľný config. Tento config je default a zápis vyzerá takto key1:value1;key2:value2.

<script>
COMPONENT('mycomponent', 'format:HH\\\:mm\\\:ss', function(self, config) {
    self.make = function() {
        setInterval(self.timer, 1000);
    };

    self.timer = function() {
        var time = new Date().format(config.format); /// config máme zase ako parameter vo funkcii aby sme nemuseli stále písať `self.config`
        self.element.text(time);
    };
});
</script>

Čo do pekla je \\\:? No, v našom configu použijeme znak : ale ten oddeľuje key od value. Takže ho musíme encodovať. Ale v html stačí encodovať iba \:. Rovno si to môžme ukázať

<div data---="mycomponent"></div>
<br>
<div data---="mycomponent__null__format:mm\:ss"></div>
<!-- https://wiki.totaljs.com/jcomponent/05-component/#configuration -->

Konfigurácia bez default hodnoty

Ide nám to nádherne. Takže si pridáme ešte voliteľný text ktorý sa pridá pred dátum. Komponent ešte premenujeme

<script>
COMPONENT('actualtime', 'format:HH\\\:mm\\\:ss', function(self, config) {
    self.make = function() {
        setInterval(self.timer, 1000);
    };

    self.timer = function() {
        var time = new Date().format(config.format);
        if (config.text)
            time = '{0}: {1}'.format(config.text, time);
        self.element.text(time);
    };
});
</script>

Teraz sme nepridali nič do default konfigurácie lebo premennú upravíme iba vtedy, ak deklarácia komponentu obsahuje v configu kľúčové slovo text. Zostáva nám to už iba otestovať

<div data---="actualtime__null__format:mm\:ss"></div>
<br>
<div data---="actualtime"></div>
<br>
<div data---="actualtime__null__text:Dnešný dátum;format:dd MMM yyyy"></div>
<br>
<div data---="actualtime__null__format:ss;text:Sekundy"></div>

Na záver

Dnes sme si urobili veľmi jednoduchý komponent s vlastnou konfiguráciou. Neobsahuje nič zložité. Dal by sa ešte vylepšiť. Napríklad pridať možnosť killnuť interval - čo by mohla byť taká vaša domáca úloha. V ďalšiom dieli si urobíme komponentu na odpočet. Tam na tieto znalosti nabalíme ďalšie a ďalšie. Hlavne nezabudnite čítať dokumentáciu a experimentovať.