jComponent - Total.js

jComponent je client-side knižnica pre UI komponenty od Total.js. Aktuálne obsahuje viac než 300 komponentov, ktoré sú všetky open-source a je ich možné ihneď použiť vo vašich aplikáciách. Všetky komponenty si tak môžete upraviť podľa vlastných požiadaviek alebo vytvoriť svoje vlastné.

Kde môžete nájsť jComponent?

Všetky komponenty sa nachádzajú na webe componentator.com alebo v Total.js GitHub repozitári. Na týchto odkazoch môžete nájsť kompletné informácie o každom komponente spolu s ich možnosťami konfigurácie, podporovanými metódami, meta dátami, podporu komponentov pre tmavý režim, responzivitu, JavaScript kód, CSS štýly a príklad použitia s náhľadom v reálnom čase. Môžete si teda komponenty hneď vyskúšať alebo ich jednoducho stiahnuť ako HTML súbor a otestovať si ich funkcie. Pre podrobnejšie informácie o jComponentoch je dostupná dokumentácia.

Ako používať jComponent?

Ak chcete použiť jComponent vo vašej aplikácií, tak Total.js ponúka CDN, so všetkými komponentami, ktoré sú priebežne aktualizované.

Použitie jComponent je veľmi jednoduché a intuitívne, pre lepšie pochopenie si ukážeme príklad použitia jedného z najpoužívanejších komponentov - j-Input.

Inicializácia komponentu j-Input:

<ui-component name="input" path="common.email" config="type:email;required:1" default="'@'">Email</ui-component>

Takto inicalizovaný input zobrazený na webe:

ui-component je HTML značka používaná pre jComponent. V deklarácii môžete vidieť atribúty name, path, config a default, ktoré si vysvetlíme podrobnejšie.

Atribút name

Name je povinný atribút pri inicializovaní komponentu. Je to názov komponentu, ktorý chceme použiť. Ako v príklade vyššie, kde chceme použiť j-Input, tak do atribútu name použijeme názov input (ako ďalšie príklady môžeme uviesť napr. j-DataGrid — datagrid, j-Box — box, j-Swiper — swiper,...). Názov komponentu musí byť vždy písaný malými písmenami.

Atribút path

Atribút path nie je povinný, avšak niektoré komponenty ho na svoju správnu funkciu potrebujú. Path je vlastne cesta, na ktorej sú uložené alebo sa uložia dáta. Komponenty pracujú s absolútnymi cestami nastavenými v deklarácii komponentu. Data-binding funguje obojstranne, z modelu do komponentu a tiež z komponentu do modelu. Komponent vytvorí "poslucháča" a bude reagovať na zmeny na danej ceste. Aby komponenty vedeli o zmene, je potrebné použiť jednu z metód (SET(), UPD(), PUSH(), INC(), EXTEND()), ktoré upozornia všetky komponenty počúvajúce na túto cestu, že nastala zmena.

Existujú dva spôsoby, ako nastaviť cestu pre vaše komponenty, s pluginmi alebo bez nich.

Bez pluginov:

Použitie bez pluginov je rovnaké ako v príklade uvedenom vyššie. Dáta na ceste deklarované takto sa nachádzajú na ceste common.email resp. window.common.email.

S pluginmi:

<ui-plugin path="common">
  // tu môže byť nejaký kód
  <ui-component name="input" path="?.email" config="type:email;required:1" default="'@'">Email</ui-component>
  // tu môže byť ďalší kód
</ui-plugin>

V tejto ukážke kódu môžete vidieť použitie komponentu s pluginom. V atribúte path môžete vidieť otáznik. Tento otáznik sa na pozadí vymení za hodnotu atribútu path v plugine. To znamená, že cesta pre tento komponent bude taktiež common.email resp. window.common.email. Výhodou použitia pluginov je jednoduchšia orientácia v kóde a zjednodušená deklarácia ciest.

Pluginy podporujú taktiež vnorené pluginy. Napríklad ak by sme chceli rozšíriť náš príklad o adresu, môžeme tak urobiť pomocou vnoreného pluginu.

<ui-plugin path="common">
  // tu môže byť nejaký kód
  <ui-component name="input" path="?.email" config="type:email;required:1" default="'@'">Email</ui-component>
  // tu môže byť ďalší kód
  <ui-plugin path="address">
     <ui-component name="input" path="?.country" config="required:1" default="'Slovakia'">Country</ui-component>
     <ui-component name="input" path="?.city" config="required:1" default="'Banská Bystrica'">City</ui-component>
  </ui-plugin>
</ui-plugin>

Otáznik v atribúte path v každom komponente bude nahradený hodnotou z atribútu path nadradeného pluginu a ten bude doplnený hodnotami z atribútu path nadradených pluginov. Pre jednoduchšie pochopenie cesta pre input City bude vyzerať takto: common.address.city resp. window.common.address.city.

Model pre takýto kód by vyzeral nasledovne:

{"address":{"city":"Banská Bystrica","country":"Slovakia"},"email":"@"}

Atribút config

Tento atribút taktiež nie je povinný a používa sa na konfiguráciu nastavení pre daný komponent. Všetky možnosti nastavení pre každý komponent môžete nájsť na webe componentator.com.

Hodnota pre tento atribút má štruktúru "kľúč1:hodnota1;kľúč2:hodnota2;...", ako môžete vidieť, tak dvojbodka sa používa na priradenie hodnoty k nejakému kľúču a bodkočiarka sa používa na rozdelenie jednotlivých kľúčov.

V príklade vyššie som použil v atribúte config pre j-Input kľúč type s hodnotou email a required s hodnotou 1. To znamená, že tento komponent bude validovaný ako email a jeho vyplnenie je povinné.

V niektorých komponentoch je možnosť použiť v konfigurácií ako hodnotu aj funkciu. Zápis volania tejto funkcie sa môže líšiť podľa toho, či používame v našom kóde pluginy alebo nie.

Bez pluginov:

<ui-component name="input" path="common.test" config="ricon:ti ti-globe-world;riconclick:click;placeholder:Enter value">Test</ui-component>

function click() {
  console.log('click');
};

S pluginmi:

S použitím pluginu je potrebné deklarovať funkciu, ktorú chceme vyvolať v JavaScript PLUGINe. Táto funkcia bude teda "naviazaná" na cestu, ktorá bude rovnaká aj pre komponent. Na vyvolanie tejto funkcie sa do nastavení našho inputu použije hodnota "?/click", kde sa znovu na pozadí nahradí otáznik hodnotou z atribútu path z ui-pluginu a tým pádom sa bude volať takto nazvaná funkcia z JavaScript PLUGINu s rovnakou cestou (v tomto prípade common).

<ui-plugin path="common">
  <ui-component name="input" path="?.test" config="ricon:ti ti-globe-world;riconclick:?/click;placeholder:Enter value">Test</ui-component>
</ui-plugin>

PLUGIN('common', function(exports) {
  exports.click = function() {
    console.log('click');
  };
});

V oboch prípadoch bude funkcionalita nášho inputu rovnaká.

Atribút default

Tento atribút taktiež nie je povinný a slúži na zadanie predvolenej hodnoty pre komponenty, ktoré ju podporujú.

Použitie komponentu ako súčasť iného komponentu

Niektoré komponenty môžu používať iné komponenty na rozšírenie svojej funkcionality. Ako príklad si môžeme uviesť j-Input, ktorý na vyvolanie dropdown menu s preddefinovanými možnosťami používa komponent j-Directory.

<ui-component name="LAZY directory" path="null" config="placeholder:Search..."></ui-component>
<ui-plugin path="common">
    <ui-component name="input" path="?.country" config="dirsource:sk|Slovakia,cz|Czech republic,us|USA,uk|United Kingdom,france|France,spain|Spain;placeholder:Enter value">Country</ui-component>
</ui-plugin>

Na to aby nám takéto dropdown menu fungovalo musíme najprv deklarovať komponent j-Directory. Tento komponent je singleton, čo znamená, že ho deklarujeme len raz na začiatku a potom ho môžeme v našom kóde používať koľkokrát budeme potrebovať.

Singleton komponenty môžeme taktiež používať nezávisle na ostatných komponentoch a sú vyvolávané pomocou metódy SETTER.

Príklad nezávisleho použitia j-Directory:

Ako prvé si deklarujeme komponent j-Directory a potom pre tento príklad použijeme element "a" na vyvolanie JavaScript funkcie.

<ui-component name="LAZY directory" path="null" config="placeholder:Search..."></ui-component>
<div><a href="javascript:void(0)">Countries</a></div>

Vo funkcii musíme nastaviť parametre pre komponent j-Directory. V tomto príklade sme použili parametre element, items a callback (všetky možnosti nastavenia komponentu j-Directory môžete nájsť tu). Následne metódou SETTER vyvoláme komponent j-Directory aj s našimi nastaveniami.

$(document).on('click', 'a', function() {
  var opt = {};
  opt.element = $(this);
  
  opt.items = [];
  opt.items.push({ name: 'Slovakia' });
  opt.items.push({ name: 'Czech republic' });
  opt.items.push({ name: 'USA' });
  opt.items.push({ name: 'United Kingdom' });
  opt.items.push({ name: 'France' });
  opt.items.push({ name: 'Spain' });
  
  opt.callback = function(value) {
    console.log('CLICKED:', value);
  };
  
  SETTER('directory/show', opt);
});

j-Directory s týmito nastaveniami bude na webe vyzerať takto:

Ako môžete vidieť v príklade sme použili slovíčko LAZY v atribúte name komponenty j-Directory. LAZY znamená "lenivé načítanie", čo znamená, že komponent bude stiahnutý až v prípade potreby. Je to výhodné pre lepší chod webovej stránky, pretože ak používateľ nebude daný komponent potrebovať, tak nebude stiahnutý. Ďalšie komponenty, ktoré podporujú "lenivé načítanie" sú j-DatePicker, j-ColorPicker alebo j-Menu.

K dispozícií je aj video tutorial v anglickom jazyku: