jQuery plugins - Datepicker
szept 23

Datepicker

Dátumbevitel jQuery-vel

Verzió: 1.8.5
Kiadás dátuma: 2010
Fejlesztő: jQuery UI
Liszensz: MIT, GPL

Bevezető

A DatePicker a legjobb, leggyorsabb módja dátumok bevitelének. Egy jól meg írt plugin, rengeteg beállítási lehetőséggel, magyar nyelvi támogatással - ami valljuk be, közel sem nevezhető hétköznapinak!

Szintén a plugin mellett szól, hogy támogatja a ThemeRoller szolgáltatást, így az előre elkészített témák mellett mi magunk is könnyedén kialakíthatjuk saját verziónkat.

Implementálás

JavaScript

            <script type="text/javascript" src="js/jquery.js"></script>
            <script type="text/javascript" src="js/jquery.ui.core.js"></script>
            <script type="text/javascript" src="js/jquery.ui.datepicker.js"></script>
          

További, opcionális lehetőségek:

  • jquery.ui.datepicker-hu.js - magyar nyelvi csomag (további nyelvi csomagok: Google code)
  • jquery.effects.core.js - az effektek kezeléséhez szükséges
  • jquery.effects.blind.js - 'blind' effekt
  • jquery.effects.bounce.js - 'bounce' effekt
  • jquery.effects.clip.js - 'clip' effekt
  • jquery.effects.drop.js - 'drop' effekt
  • jquery.effects.explode.js - 'explode' effekt
  • jquery.effects.fade.js - 'fade' effekt
  • jquery.effects.highlight.js - 'highlight' effekt
  • jquery.effects.pulsate.js - 'pulsate' effekt
  • jquery.effects.scale.js - 'scale' effekt
  • jquery.effects.shake.js - 'shake' effekt
  • jquery.effects.slide.js - 'slide' effekt

Deklaráció

            $(document).ready(function(){
              $('#naptar').datepicker();
            });
          

Használat

A plugin használatba vételéhez elegendő a deklarációban megadott selector-ral létrehozni egy tetszőleges elemet. Ha ez az elem egy div blokk, akkor egy sima naptárat kapunk eredményül, ha azonban egy beviteli mező, akkor (ha a paraméterekből ezt külön nem bíráljuk felül) a plugin a beviteli mezőre klikkelve aktivizálódik.

Teljes paraméterlista

Opciók:

  • disabled: a plugin engedélyezése/tiltása - kizárólag inicializálás után (true | false)
    (alapértelmezett: true)
  • altField: a paraméter segítségével egy tetszőleges elem tartalmát frissíthetjük a datepicker aktuális értékével (értékként egy selector-t vár)
  • altFormat: a dátum formátuma, ahogy megjelenik az altField paraméterben megadott elemben (alapértelmezett: 'yy-mm-dd')
    Lehetséges értékek:
    y - év rövidítve (pl. 2010: '10')
    yy - év (pl. 2010: '2010')
    M - hónap neve rövidítve (pl. szeptember: 'Szep')
    MM - hónap neve (pl. szeptember: 'Szeptember')
    m - hónap számmal (egyjegyű szám egyjegyű számmal, pl. január: '1')
    mm - hónap számmal (egyjegyű szám kétjegyű számmal, pl. január: '01')
    D - nap neve rövidítve (pl. csütörtök: 'Csü')
    DD - nap neve (pl. csütörtök: 'Csütörtök')
    d - nap számmal (egyjegyű szám egyjegyű számmal, pl. elseje: '1')
    dd - nap számmal (egyjegyű szám kétjegyű számmal, pl. elseje: '01')
  • autoSize: a beviteli mező automatikus igazódása a tartalomhoz (true | false) (alapértelmezett: false)
  • appendText: tetszőleges szöveg beillesztése a beviteli mező mögé, pl. a kért formátum kijelzésére: '(éééé-hh-nn)' (ez az opció csak abban az esetben érvényes, ha a datepicker egy beviteli mezőhöz van rendelve)
  • showOn: alaphelyzetben akkor jelenik meg a naptár, ha a beviteli mezőre kerül a fókusz. A paraméter segítségével módosíthatjuk úgy, hogy egy gomb segítségével lehessen csak előhívni, illetve a két megoldást egyszerre is alkalmazhatjuk ('focus' | 'button' | 'both')
    (alapértelmezett: 'focus')
  • buttonImage: ha beviteli mező esetén egy képet kívánunk használni gombként a naptár aktiválásához, a paraméter segítségével definiálhatjuk a használni kívánt képet - útvonallal együtt
    (a kép/ikon használatához lásd még showOn és buttonImageOnly paramétereket)
  • buttonImageOnly: true érték esetén csak a buttonImage paraméterrel definiált kép látszik,
    a gomb nem (true | false) (alapértelmezett: false)
  • buttonText: a naptárt aktiváló gomb (lásd showOn paraméter) felirata (alapértelmezett: '...')
  • changeMonth: hónapválasztó lebomló lista engedélyezése/tiltása a naptár fejlécében (true | false)
    (alapértelmezett: false)
  • changeYear: évválasztó lebomló lista engedélyezése/tiltása a naptár fejlécében (true | false)
    (alapértelmezett: false)
  • yearRange: az évválasztó lista használatakor a választható évek meghatározása
    (szám:szám formátum)
    A választható tartomány definiálása történhet relatív módon, pl.:
                    $('#naptar').datepicker({
                      yearRange: '-4:+4' // aktuális év előtt és után 4 év
                    });
                  
    illetve történhet abszolút módon, pl.:
                    $('#naptar').datepicker({
                      yearRange: '2000:2010' // 2000 és 2010 közt
                    });
                  
    (alapértelmezett: 'c-10:c+10' - ahol c az aktuális év)
  • showButtonPanel: gombok aktiválása a naptár alján: 'bezárás' gomb,
    illetve egy az aktuális napra mutató gomb (true | false) (alapértelmezett: false)
  • closeText: a naptár alján lévő bezárás gomb felirata
    (a gombok aktiválásához lásd a showButtonPanel paramétert)
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • currentText: a naptár alján lévő, aktuális napra mutató gomb felirata
    (a gombok aktiválásához lásd a showButtonPanel paramétert)
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • dateFormat: a használt formátum beállítása (alapértelmezett: aktuális nyelvi csomagtól függ)
  • constrainInput: true érték esetén a beviteli mező csak a dateFormat paraméterben meghatározott formátum karaktereit fogadja el (true | false)
    (alapértelmezett: false)
  • dayNames: a napok neveit tartalmazó tömb, ahol az első nap a vasárnap
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • monthNames: a hónapok neveit tartalmazó tömb
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • dayNamesMin: a napok rövidített neveit (a naptár fejlécében szereplő rövidítéseket!) tartalmazó tömb, ahol az első nap a vasárnap
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • dayNamesShort: a napok rövidített neveit tartalmazó tömb, ahol az első nap a vasárnap
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • monthNamesShort: a hónapok rövidített neveit (a naptár fejlécében szereplő rövidítéseket!) tartalmazó tömb (alapértelmezett: aktuális nyelvi csomagtól függ)
  • defaultDate: a naptár első kinyitásakor az alapértelmezett nap beállítása. Ez az érték lehet bármely dátum, amely illeszkedik a definiált formátumhoz (dateFormat paraméter), illetve lehet számérték (pozitív és negatív egyaránt), amelyet az aktuális naptól számít, valamint sztringet is használhatunk, ez esetben a következő karakterek jöhetnek szóba:
    y - év
    m - hónap
    w - hét
    d - nap
    Például az alábbi kód esetén az alapértelmezett nap az aktuális naptól számítva 2 hétre és 3 napra tolódik:
                    $('#naptar').datepicker({
                      defaultDate: '+2w +3d'
                    });
                  
  • duration: a naptár megjelenítéséhez használt animáció sebessége
    (tetszőleges érték milliszekundumban | 'slow' | 'normal' | 'fast')
    (alapértelmezett: 'normal')
  • firstDay: a hét első napjának meghatározása (0 a vasárnapnak felel meg)
    (alapértelmezett: aktuális nyelvi csomagtól függ)
  • gotoCurrent: alapesetben, ha engedélyeztük a gombokat a naptár alján (showButton paraméter), akkor az aktuális napra mutató gomb az aktuális (mai) napra ugrik vissza. Ha jelenlegi paramétert engedélyezzük (true), akkor a gomb nem az aktuális napra, hanem a legutoljára kiválasztott napra fog mutatni (true | false) (alapértelmezett: false)
  • maxDate: a maximum választható dátum, mely lehet sztring az aktuális
    formátumnak (dateFormat paraméter) megfelelően, illetve számérték - a használható speciális karakterek megegyeznek a defaultDate paraméternél részletezett karakterekkel
    (alapértelmezett: null - nem definiált)
                    $('#naptar').datepicker({
                      maxDate: '+2w +3d'
                    });
                  
  • minDate: a minimum választható dátum, mely lehet sztring az aktuális
    formátumnak (dateFormat paraméter) megfelelően, illetve számérték - a használható speciális karakterek megegyeznek a defaultDate paraméternél részletezett karakterekkel
    (alapértelmezett: null - nem definiált)
                    $('#naptar').datepicker({
                      maxDate: '-1w'
                    });
                  
  • nextText: következő hónapra mutató gomb szövege - ThemeRoller téma esetén ikonra cserélődik (alapértelmezett: aktuális nyelvi csomagtól függ)
  • prevText: előző hónapra mutató gomb szövege - ThemeRoller téma esetén ikonra cserélődik (alapértelmezett: aktuális nyelvi csomagtól függ)
  • numberOfMonths: egyszerre megjelenített hónapok száma: egész szám, de kételemű tömbbel is definiálható - ez esetben első elem a sorok számát, második elem az oszlopok számát tartalmazza pl. [2, 3] esetén 6 hónapot jelenít meg, két sorban (alapértelmezett: 1)
  • showCurrentAtPos: ha több hónapot jelenítünk meg egyszerre (numberOfMonths paraméter), akkor az aktuális hónap pozícióját definiálhatjuk a paraméterrel. Az első hely a 0! (alapértelmezett: 0)
  • showOtherMonths: az aktuális hónap előtti és utáni hónap
    "átlógó" napjainak mutatása/elrejtése - az átlógó elemek nem aktívak! (true | false)
    (alapértelmezett: false)
  • selectOtherMonths: ha a showOtherMonths paraméterrel engedélyezve vannak az "átlógó" napok, akkor a paraméter segítségével aktívvá tehetők, illetve tilthatók (true | false)
    (alapértelmezett: false)
  • showAnim: az animáció típusa a naptár megjelenítéséhez. Ha szeretnénk animációt használni, ne felejtsük el implementálni a jquery.effects.core.js file-t, illetve a használni kívánt effekt js file-ját! Lehetséges értékek:
    'Show', 'Slide down', 'Fade in', 'Blind', 'Bounce', 'Clip', 'Drop', 'Fold', 'Slide', 'Pulsate', 'Shake', 'Highlight', 'Explode', 'Scale', ' ' - nincs animáció
    (alapértelmezett: 'Show')
  • showOptions: ha használunk animációt (showAnim paraméter), akkor a paraméterrel beállíthatjuk a használt animáció irányát, pl.:
                    $('#naptar').datepicker({
                      showAnim: 'Slide',
                      showOptions: { direction: 'up' }
                    });
                  
  • showMonthAfterYear: alapértelmezett esetben a naptár fejlécében a hónap, majd az év szerepel. A sorrendet a paraméter engedélyezésével felcserélhetjük (true | false)
    (alapértelmezett: false)
  • showWeek:a hetek számának mutatása (true | false) (alapértelmezett: false)
  • weekHeader: a hetek számának fejléce - ha a showWeek paraméter engedélyezve van (alapértelmezett: 'Wk')
  • stepMonths: a hónap léptetésének mértéke - hány hónapot lépjen a naptár az előző/következő gombok használatakor (alapértelmezett: 1)
  • yearSuffix: a naptár fejlécében az évszámhoz fűzhető tetszőleges sztring (alapértelmezett: ' ')

A plugin-nal kapcsolatos további információkat (pl. események, metódusok) a datepicker oldalán találsz.