j-Directory - Total.js

j-Directory je súčasťou client-side knižnice jComponent od Total.js. Viac informácií o tomto komponente môžete nájsť na webe componentator.com alebo v GitHub repozitári.

Jedná sa o singleton komponent, čo znamená, že ho v kóde musíme deklarovať len raz a následne ho môžeme používať koľkokrát potrebujeme. Tento komponent nám umožní zobraziť možnosti pre užívateľa, z ktorých si môže vybrať jednu alebo viac na základe našich nastavení. Môžeme ho použiť ako nezávislý komponent alebo v kombinácií s komponentom j-Input (ak sa chcete dozvedieť viac o použití v kombinácií s komponentom j-Input, prečítajte si prosím môj blog j-Input - Total.js part 2). Podporuje aj ovládanie dotykom a tmavý režim.

Ako používať j-Directory

Ako prvé je potrebné vedieť ako pracovať s knižnicou jComponent. Podrobnejšie som sa tomu venoval v predchádzajúcom blogu, pre viac informácií si ho odporúčam prečítať.

V tomto blogu si ukážeme ako používať nezávislý j-Directory.

Inicializácia

Ako prvé potrebujeme deklarovať komponent j-Directory v našom kóde. Keďže sa jedná o singleton komponent, tak to urobíme rovnakým princípom ako napríklad pri komponente j-Exec a deklarujeme si ho hneď na začiatku za otávracím body HTML tagom.

<ui-component name="directory" config="placeholder:Search..."></ui-component>

Ako môžeme vidieť, pridal som do konfigurácie nastavenie placeholder s hodnotou Search..., pretože to chceme mať použité ako zástupný text v inpute, ktorý slúži na vyhľadávanie v možnostiach pre užívateľa. Po tomto môžeme komponent využívať v celom kóde.

Pre tento príklad budeme potrebovať tiež komponent j-Exec, ak sa o ňom chcete dozvedieť viac, prečítajte si prosím môj starší blog.

Example:

<span class="exec" data-exec="?/click">Click</span>

Vytvoríme si span element s textom Click a po kliknutí naň chceme vyvolať funkciu s názvom click, ktorá je deklarovana v našom PLUGINe.

Vo funkcii click vyvoláme komponent j-Directory pomocou metódy SETTER.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    SETTER('directory/show', obj);
  };
});

V tejto časti kódu môžete vidieť funkciu click, ktorá obsahuje argument el, ktorý reprezentuje jQuery element, na ktorý sme klikli. Na konci funkcie môžeme vidieť metódu SETTER s dvomi argumentmi. Prvý argument je typu string s hodnotou 'directory/show', čo znamená, že metóda setter vyvolá metódu show z komponentu j-Directory. Druhý argument je objekt, ktorý obsahuje nastavenia pre náš komponent. V tomto príklade sme použili jediné nastavenie a to vlastnosť element, pretože teraz si ukážeme len zobrazenie komponentu. Argument el sme nastavili ako hodnotu pre vlastnosť element a tým dosiahneme, že sa nám komponent zobrazí na správnom mieste (na elemente s textom Click na našej stránke).

Ako môžeme vidieť náš j-Directory je prázdny, pretože sme doň nevložili žiadne možnosti. Môžeme tak urobiť jednoducho pridaním vlastnosti items do nášho objektu obj.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }]; // added property
    SETTER('directory/show', obj);
  };
});

Teraz máme 4 možnosti (Palo, Peter, Dodo a Marek) vo vlastnosti items. Táto vlastnosť potrebuje dáta v tvare poľa objektov, každý objekt obsahuje vlastnosť name, ktorá je použitá ako defaultná pre výpis hodnôt na stránke.

Teraz, keď máme možnosti, môžeme sa posunúť ďalej k spracovaniu zvolenej možnosti. Na to potrebujeme pridať ďašiu vlastnosť do nášho objektu obj a to callback. Callback je funkcia, ktorá sa vyvolá po kliknutí na zvolenú možnosť.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }];
    obj.callback = function(item) {
      console.log('item -->', item);  // added property
    };
    SETTER('directory/show', obj);
  };
});

Táto funkcia môže obsahovať viacero argumentov, no v tomto prípade budeme používať len prvý, ktorým je item. V ňom sa nám vráti objekt, na ktorý bolo kliknuté.

Toto je základná funkcia komponentu j-Directory. Týmto spôsobom vďaka funkcii callback môžeme vytvoriť požadovanú funkcionalitu. Podporované je samozrejme aj vyhľadávanie v možnostiach.

Výber viacerých možností

Môžeme taktiež nastaviť náš komponent tak, aby mal užívateľ možnosť zvoliť si viacero možností. Na to je potrebné pridať vlastnosť checkbox do nášho objektu obj s hodnotou true.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.checkbox = true; // added property
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }];
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

S touto vlastnosťou sa nám pridajú zaškrtávacie políčka k našim možnostiam v zobrazenom j-Directory one. Po kliknutí na tieto možnosti zostane okno otvorené a môžeme si zvoliť ďaľšiu možnosť (prípadne odškrtnúť možnosť, ktorú zvolenú mať nechceme).

Ako môžeme vidieť v príklade po kliknutí na nejakú možnosť sa nám vyvolá callback funkcia a namiesto objektu sa nám v tomto prípade vráti pole objektov. Každý objekt obsahuje vlastnosti ako predtým s extra vlastnosťou, ktorou je selectedts. S touto vlastnosťou môžeme jednoducho zoradiť možnosti podľa času, kedy boli zvolené.

Zvýraznovanie možností

Ak chceme zvýrazniť niektorú z možností môžeme tak urobiť pridaním vlastnosti template do objektu možnosti, ktorú chceme zvýrazniť. Do tejto vlastnosti následne pridáme kód v Tangulari (šablóna ako alternatíva pre Handlebars alebo Mustache).

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.checkbox = true;
    obj.items = [{ name: 'Palo', template: '<b>{{ name }}</b>' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }]; // added property template to first object
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

V príklade sme použili len HTML tag b pre zvýraznenie prvej možnosti.

Ako môžeme vidieť, tak prvá možnosť Palo je napísaná hrubým písmom. Ak by sme chceli takto zvýrazniť všetky možnosti, môžeme tak urobiť jednoducho pomocou vlastnosti render pridanej do nášho objektu obj. Do tejto vlastnosti musíme pridať funkciu, ktorá vracia HTML kód.

Zobrazenie inej vlastnosti

Ak potrebujeme v možnostiach zobraziť dáta z inej vlastnosti ako defaultnej name, môžeme tak jednoducho urobiť pomocou vlastnosti key, ktorú pridáme do objektu obj. Do tejto vlastnosti zadáme ako hodnotu názov vlastnosti, ktorú chceme zobrazovať v možnostiach.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.key = 'text'; // added property
    obj.checkbox = true;
    obj.items = [{ text: 'Palo' }, { text: 'Peter' }, { text: 'Dodo' }, { text: 'Marek' }]; // changed name of properties
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

Pozícia a rozmery

Máme viacero možností, ktorými môžeme upravovať pozíciu a rozmery nášho komponentu. Prvé môžeme spomenúť vlastnosti align a position. Align je pre nastavenie horizontálnej pozície okna s hodnotami left, right a top a position pre nastavenie vertikálnej pozície s hodnotami top a bottom.

Ďalšou možnosťou je použitie vlastností offsetX a offsetY, tu je potrebné použiť číslo v pixeloch na posunutie okna v požadovanom smere.

Pre nastavenie rozmerov slúžia vlastnosti height, minwidth a maxwidth. V týchto vlastnostiach sa používajú taktiež čísla v pixeloch na nastvenie rozmerov okna j-Directory.

Lazy komponent

j-Directory je singleton komponent, ktorý podporuje funkcionalitu LAZY, takže môžeme použiť slovo LAZY v deklarácií. LAZY znamená "lenivé načítanie", čo znamená, že komponent bude načítaný len v tom prípade ak ho užívateľ potrebuje. Je vhodné ho použiť pre lepší chod stránky, pretože v prípade, že užívateľ nebude takýto komponent potrebovať, tak nebude stiahnutý.

<ui-component name="LAZY directory" config="placeholder:Search..."></ui-component>

Použiť takto komponent je veľmi jednoduché, jediné čo potrebujeme je napísať slovo LAZY pred meno zvoleného komponentu do vlastnosti name.

K dispozícií je aj video tutorial ku komponentu j-Directory v anglickom jazyku: