jQuery plugins - DataTables
szept 18

DataTables

Professzionális plugin táblázatokhoz

Verzió: 1.7.1
Kiadás dátuma: 2010/08/22
Fejlesztő: Allan Jardine
Liszensz: GPL, BSD

Bevezető

A mostani ismertető elkészítése eléggé elhúzódott, de nem véletlenül... Az alábbi komponens kilóg a hétköznapi plugin-ok közül, mivel ezt kivételesen teljesen profi módon írták meg a fejlesztők. A profizmus megmutatkozik a plugin szolgáltatásaiban, a felhasználó számára biztosított beállítási lehetőségekben, a terméktámogatásban, a plugin dokumentációjában, szóval mindenben!

A rendelkezésre álló paraméterek és függvények alapból túlmutatnak egy átlagos plugin-on, szinte mindenre van lehetőség, ami szóba jöhet. Pont emiatt az ismertető eléggé terjedelmesre sikeredett, bár így is csak azokat a funkciókat ragadtam ki, amelyek esetleg egy "mezei" felhasználónak is fontosak lehetnek (aki a plugin-nal kapcsolatos további információkra éhezik, látogasson el a plugin honlapjára).

De a terjedelmes leírás és a rendelkezésre álló paraméterek kavalkádja senkit se riasszon el!

A rengeteg paraméter és függvény csak finomhangolásra szolgál, ugyanis egy szimpla deklarációt követően a plugin minden funkciót egyből a rendelkezésünkre bocsájt: sorba rendezés, szűrés, lapozó, stb.
Egyedül a "Nyelvi beállítások" szakasz az, amelyet célszerű átolvasni, mivel az ott részletezett paraméterekkel (js buherálás nélkül!) honosíthatjuk az amúgy angol nyelvű plugin-t.

Jellemzők

  • 'on-the-fly' szűrés
  • tetszőleges szempont (oszlop) szerinti sorba rendezés
  • változó nagyságú lapozó (pagination)
  • alternatív lapozók használata (pagination)
  • adatbeolvasás a legtöbb adatforrásból
    (DOM, JavaScript tömb, Ajax file- és szerver oldali folyamat, stb.)
  • nyelvileg teljesen személyre szabható
  • jQuery UI támogatott (ThemeRoller)
  • további beépülő modulok (TableTools, FixedHeader, KeyTable)
  • stabil működés (több, mint 1.300 adattal tesztelve)

Implementálás

CSS

              <link type="text/css" rel="stylesheet" href="demo_table.css" media="screen" />
          

JavaScript

              <script type="text/javascript" src="js/jquery.js"></script>
              <script type="text/javascript" src="js/jquery.dataTables.js"></script>
          

Deklaráció

            $(document).ready(function(){
              $('#tablazat').dataTable();
            });
          

Használat

A plugin megfelelő működéséhez elengedhetetlen, hogy a tábla felépítése az alábbi struktúrát
(thead és tbody) kövesse:

              <table id="tablam">
                <thead>
                  <tr>
                    <th>Fejléc 1</th>
                    <th>Fejléc 2</th>
                  </tr>
                </thead>
                <tbody>
                  <tr>
                    <td>Adat ...</td>
                    <td>Adat ...</td>
                  </tr>
                </tbody>
              </table>
          

Mivel a plugin igen összetett és rengeteg paraméter, funkció áll rendelkezésünkre melyek elnevezése igen változatos, ezért az alábbi listában segítségként összefoglaltam, hogy az egyes paraméterek elején lévő (prefix) jelölések mire utalnak:

  • n - node (csomópont)
  • o - object (objektum)
  • a - array (tömb)
  • s - string (sztring)
  • b - boolean (logikai)
  • f - float (lebegőpontos szám)
  • i - integer (egész szám)
  • fn - function (függvény)

Teljes paraméterlista

Jellemzők:

  • bAutoWidth: automatikus oszlopszélesség-számítás engedélyezése/tiltása (alapértelmezett: true)
  • bFilter: adatszűrési/keresési funkció engedélyezése/tiltása. A szűrő több szó (szóközzel elválasztva) alapján is képes megtalálni azokat a sorokat, melyekben az adott kifejezések szerepelnek (abban az esetben is, ha azok nem a megadott sorrendben szerepelnek)
    (alapértelmezett: true)
  • bInfo: a táblázat alján az információs rész megjelenítésének engedélyezése/tiltása (alapértelmezett: true)
  • bJQueryUI: a jQuery UI ThemeRoller támogatás engedélyezése/tiltása.
    Ennek használatához a táblázat HTML felépítése megkövetel néhány módosítást
    (alapértelmezett: false)
  • bLengthChange: a lebomló menü engedélyezése/tiltása, mellyel a megjelenítendő sorok számát (10,25,50 és 100) szabályozhatjuk - engedélyezése esetén szükséges a lapozó (bPaginate) használata (alapértelmezett: true)
  • bPaginate: lapozó engedélyezése/tiltása (alapértelmezett: true)
  • bProcessing: a 'betöltés folyamatban' ('processing') megjelenítésének engedélyezése/tiltása. Ez a funkció nagyobb mennyiségű adatok esetén lehet hasznos, ahol az adatokkal való munka - beolvasás, rendezés, stb. - kicsit több időt igényel (alapértelmezett: false)
  • bSort: az oszlopok szerinti sorba rendezés engedélyezése/tiltása (alapértelmezett: true)
  • bSortClasses: a .sorting_1,.sorting_2 és .sorting_3 osztályok engedélyezése/tiltása. Ez a funkció lassíthatja az adatfeldolgozás menetét, így nagyobb mennyiségű adatok esetén célszerű kikapcsolni (alapértelmezett: true)
  • bStateSave: az aktuális állapot (megjelenített sorok száma, szűrő, lapozó, stb.) mentésének engedélyezése/tiltása. A funkció működéséhez szükséges, hogy a böngészőben engedélyezve legyen a cookie-k használat (alapértelmezett: false)
  • sScrollX: horizontális görgetés engedélyezése/tiltása. A tábla vízszintes nagy kiterjedése, vagy nagyszámú oszlophasználat esetén (jobb átláthatóság miatt) célszerű használni.
    Értéke lehet bármilyen CSS mértékegység (pl. százalék), vagy egy egész típusú szám (ez esetben a mértékegység pixel-ben értendő), amellyel a táblázat viewport-jának szélességét definiáljuk
  • sScrollY: vertikális görgetés engedélyezése/tiltása. A funkció használata alternatíva lehet a lapozó kiváltására (de akár együttesen is használhatók).
    Értéke lehet bármilyen CSS mértékegység (pl. százalék), vagy egy egész típusú szám (ez esetben a mértékegység pixel-ben értendő), amellyel a táblázat viewport-jának magasságát definiáljuk

Opciók:

  • aaSorting: ha a rendezés funkció (bSort) engedélyezve van, akkor a paraméter segítségével megadhatjuk, hogy kezdőállapotban (inicializáláskor) mely oszlop(ok) szerint történjék a sorba rendezés.
    A paraméter tömb formájában várja a rendezni kívánt oszlop(ok) sorszámát, illetve a sorba rendezés irányát:
                    $(document).ready( function(){
                      $('#tablazat').dataTable({
                        'aaSorting': [[2,'asc'], [3,'desc']]
                      });
                    })
                  
    Fenti kód először a harmadik oszlop szerint növekvő, majd a negyedik oszlop szerint csökkenő sorrendet definiál (az oszlopok sorszámozása 0-val kezdődik)
    (alapértelmezett: [ [ 0, 'asc' ] ])
  • aaSortingFixed: ez a paraméter az aaSorting-hoz hasonlóan a kezdő rendezést hívatott beállítani, azzal a különbséggel, hogy az itt beállított rendezést a felhasználó nem módosíthatja
  • aLengthMenu: a "megjeleníthető sorok száma" lebomló menü működését, tartalmát módosíthatjuk vele. Két paramétert vár: az első paraméter az értékeket (az options elem value attribútumát) jelenti, míg a második a lebomló menüben megjelenő szövegeket (címkéket). Ezeket 2 dimenziós tömbként adhatjuk át, de ha csak 1 dimenziós tömböt használunk, akkor mindkét paraméter az átadott tömb értékeit veszi fel.
    Példa 2 dimenziós tömb használatára:
                    $(document).ready( function(){
                      $('#tablazat').dataTable({
                        'aLengthMenu': [[10, 25, 50, -1], [10, 25, 50, 'Összes']]
                      });
                    })
                  
    Mint látható az összes elem megjelenítésére a -1 értéket használhatjuk.
    (alapértelmezett: [ 10, 25, 50, 100 ])
  • oSearch: kezdő globális szűrő beállítása. Három paramétert vár: sSearch, bRegex és bSmart.
    Az első paraméter kötelező (a kifejezés, melyre szűrni szeretnénk), a további paraméterek opcionálisak: a bRegex boolean típusú, amely ha true értéket vesz fel, akkor a szűrési feltétel, mint reguláris kifejezés lesz értelmezve, false érték esetén egyszerű sztring-ként
    (alapértelmezett: { "sSearch": "", "bRegex": false, "bSmart": true })
  • aoSearchCols: az oSearch paraméterhez hasonlóan a kezdeti szűrő beállítását végzi, csak itt minden egyes oszlopot külön definiálnunk kell. Paraméterként egy tömböt vár, amely minden eleme a táblázat soron következő oszlopával egyezik meg.
    Minden oszlopnál két paramétert kell beállítani: sSearch és bEscapeRegex (utóbbi használata nem kötelező). Definícióként a null értéket is használhatjuk, ebben az esetben adott oszlopra az alapértelmezett beállítások fognak vonatkozni.
                    $(document).ready( function(){
                      $('#tablazat').dataTable({
                        'aoSearchCols': [
                          null,
                          { 'sSearch': 'feltétel' },
                          null,
                          { 'sSearch': '^[0-9]', 'bEscapeRegex': false }
                        ]
                      });
                    })
                  
  • asStripClasses: CSS osztályok tömbje, amelyet a táblázat sorainak megjelenítéséhez használunk. Alapértelmezett esetben két osztályt tartalmaz (.odd és .even), azaz minden páros illetve minden páratlan sornak külön stílus van definiálva.
    A tömb tetszőleges számú elemet tartalmazhat, a plugin ennek megfelelően színezi majd a sorokat: a tömb elemein végig haladva újra és újra.
    Alábbi példában nem kétsoronként, hanem három soronként ismétlődnek a stílusok:
                    $(document).ready( function(){
                      $('#tablazat').dataTable({
                        'asStripClasses': [ 'sorStilus1', 'sorStilus2', 'sorStilus3' ]
                      });
                    }) 
                  
    (alapértelmezett: [ 'odd', 'even' ])
  • bScrollCollapse: ha a vertikális görgetés (sScrollY) engedélyezve van, akkor előfordulhat, hogy pl. szűrési feltételt alkalmazva kevesebb sor kerül megjelenítésre, mint amekkora a beállított táblázat (viewport) magasság. Ilyen esetben a táblázat alja (lapozó, információs sor) nincs a megjelenített sorokhoz igazítva. A paraméter engedélyezésével ez a probléma orvosolható
    (alapértelmezett: false)
  • iCookieDuration: a session információk tárolására használt cookie élettartama másodpercben (alapértelmezett: 7200)
  • iDisplayLength: lapozó használata esetén az egy oldalon megjelenő sorok száma. Amennyiben a bLengthChange engedélyezve van, akkor természetesen a lebomló menü használatával a felhasználó felülbírálhatja az itt beállított értéket (alapértelmezett: 10)
  • iDisplayStart: lapozó használata esetén a kezdőoldal beállítása. Fontos, hogy nem a lap, hanem a rekord sorszámát kell megadni!
    Pl. ha 10 rekord/oldal esetén a harmadik oldalt szeretnénk kezdőpontnak kiválasztani, ebben az esetben értékként a 20-at kell megadnunk (ne feledjük, a számozás 0-tól indul)
    (alapértelmezett: 0)
  • sAjaxSource: a paraméter segítségével egy külső file-t adhatunk meg a plugin (a táblázat) forrásaként
                    $(document).ready( function(){
                      $('#tablazat').dataTable({
                        'sAjaxSource': 'http://www.sprymedia.co.uk/dataTables/json.php'
                      });
                    })
                  
  • sCookiePrefix: a plugin által használt cookie nevének előtagját (prefix-ét) módosíthatjuk vele (alapértelmezett: SpryMedia_DataTables_)
  • sDom: a paraméterrel pontosan meghatározható, hogy a DOM-ba hova szeretnénk beszúrni a különböző kontroll elemeket (pl. ha a lapozót a táblázat tetejére szeretnénk helyezni). Aki a paramétert használni szeretné, az a fejlesztő oldalán bővebb információkat talál róla.
  • sPaginationType: a lapozó típusának beállítása. Két előre definiált típus közül választhatunk: a két gombos (two_button), amikor csak következő/előző gombok jelennek meg, illetve a teljes lapozó (full_numbers), amely egy úgymond "minden az egyben" megoldást biztosít
    (alapértelmezett: two_button)
  • sScrollXInner: a paraméter lehetővé teszi, hogy nagyobb szélességű táblázatot használhassunk, mint amelyet a horizontális görgetéssel elérhetünk.
    Értéke lehet bármilyen CSS mértékegység (pl. százalék), vagy egy egész típusú szám (ez esetben a mértékegység pixel-ben értendő)
                    $(document).ready(function(){
                      $('#tablazat').dataTable({
                        'sScrollX': '100%',
                        'sScrollXInner': '110%'
                      });
                    });
                  

Nyelvi beállítások:

Szerencsére a plugin fejlesztői gondoskodtak róla, hogy könnyedén, a deklaráció keretein belül teljesen átírhassuk a szöveges részeket, üzeneteket. Mindezt az oLanguage objektum paraméterein keresztül tehetjük meg (példát csak az első paraméterhez mellékelek, a többi értelemszerűen ennek szintaktikájára működik):

  • oLanguage.oPaginate.sFirst: a legelső oldalra mutató link szövege (full_numbers lapozó esetén)
    (alapértelmezett: 'First')
                    $(document).ready(function(){
                      $('#tablazat').dataTable({
                        "oLanguage": {
                          "oPaginate": {
                            "sFirst": "Első oldal"
                          }
                        }
                      });
                    });
                  
  • oLanguage.oPaginate.sLast: a legutolsó oldalra mutató link szövege
    (full_numbers lapozó esetén) (alapértelmezett: 'Last')
  • oLanguage.oPaginate.sNext: a következő oldalra mutató link szövege
    (full_numbers lapozó esetén) (alapértelmezett: 'Next')
  • oLanguage.oPaginate.sPrevious: az előző oldalra mutató link szövege
    (full_numbers lapozó esetén) (alapértelmezett: 'Previous')
  • oLanguage.sEmptyTable: üres táblázat esetén a "nincs adat" üzenet
    (alapértelmezett: 'No data available in table')
  • oLanguage.sInfo: az információs részen az aktuálisan megjelenített adatokról nyújt információt. Ehhez rendelkezésre álló változók: _START_, _END_ és _TOTAL_
    (alapértelmezett: 'Showing _START_ to _END_ of _TOTAL_ entries')
  • oLanguage.sInfoEmpty: az információs részen az üres tábla esetén megjelenő szöveg
    (alapértelmezett: 'Showing 0 to 0 of 0 entries')
  • oLanguage.sInfoFiltered: szűrési feltétel alkalmazása esetén az információs részen a megjelenített információhoz fűzött, a szűrésre vonatkozó szöveg. Az összes bejegyzésre vonatkozó változó: _MAX_
    (alapértelmezett: '(filtered from _MAX_ total entries)')
  • oLanguage.sInfoPostFix: az információs részen tetszőleges, mindig látható üzenet hozzáfűzése a megjelenített szöveghez (az sInfo tartalmához)
    (alapértelmezett: üres sztring)
  • oLanguage.sLengthMenu: a lapozóhosszt beállító menü testre szabása. Az aktuális hossz megjelenítésére a _MENU_ változó szolgál
    (alapértelmezett: 'Show _MENU_ entries')
  • oLanguage.sProcessing: üzenet, ha a táblázat feldolgozás alatt ál, pl. egy szűrési, vagy rendezési parancs során
    (alapértelmezett: 'Processing...')
  • oLanguage.sSearch: a szűrő mező címkéje
    (alapértelmezett: 'Search:')
  • oLanguage.sZeroRecords: sikertelen szűrés esetén megjelenített szöveg
    (alapértelmezett: 'No matching records found')
  • oLanguage.sUrl: a nyelvi paraméterek külső, JSON formátumú file-ból is beolvashatók, ennek az elérhetőségét lehet a paraméterrel megadni.
    (alapértelmezett: üres sztring)

A plugin biztosította lehetőségek bemutatása nem teljes körű, így aki további információra kíváncsi, látogasson el a plugin honlapjára!