A ProForm megalkotásakor az volt a cél, hogy egy jól átgondolt felhasználói felület minta alakuljon ki webes alkalmazások számára, amely könnyen alkalmazható, egységes megjelenésű.
A ProForm tehát egy kidolgozott eszközcsoport, egy alkalmazási mintákkal megfogalmazott szabálygyűjtemény.
Fontos körülmény, hogy a jelenlegi JavaScript interfész egy form
elemet enged meg kezelni az oldalon
belül. Továbbá azt is fontos mérlegelni, hogy a CSS kidolgozás vízszintesen adott két méretre van tervezve.
A ProForm viselkedés szempontjából sok belső függvénnyel rendelkezik, ezek közül az alábbiakat kell a fejlesztőnek ismernie kezelői szinten.
A legtöbbet használt és legtöbb funkcióval rendelkező modul maga az alap űrlapkezelés. Ezt kell leginkább ismerni.
proform.initForm(sId, fOnBeforeSubmit);
Beállítja egy űrlapra a ProForm futását.
sId
– String
, az űrlap id
paramétere, melyre alkalmazzuk
a ProForm-ot.fOnBeforeSubmit( elForm )
– Function
, egy metódus, mely azután fog meghívódni,
hogy az űrlap elküldhetőnek lett nyilvánítva. Egy paramétert kap meg ez a függvény, magát az űrlap elemet.proform.setConfig( sConfig, sValue );
Beállít egy bizonyos tulajdonságot.
Ezen beállítások csak globálisan, az egész űrlapra állíthatóak be.
repetitionSeparatorNameBefore
: '['
– a mezők többszörözésekor alkalmazott
elválasztó előtag a name
attribútumonrepetitionSeparatorNameAfter
: ']'
– a mezők többszörözésekor alkalmazott
elválasztó utótag a name
attribútumonrepetitionRegExpName
: /\[([\d]+)\]$/
– a name
attribútumra
illeszkedő kifejezésrepetitionSeparatorIdBefore
: ':'
– a mezők többszörözésekor alkalmazott
elválasztó előtag az id
attribútumonrepetitionSeparatorIdAfter
: ''
– a mezők többszörözésekor alkalmazott
elválasztó utótag az id
attribútumonrepetitionRegExpId
: /:([\d]+)$/
– az id
attribútumra illeszkedő
kifejezésidEnding
: '_[a-zA-Z0-9_]+'
– nem lézető id
esetén
megkeresett elemek végződése (összevonás is!)alertOnError
: true
– rendszerüzenet a nem elküldhető űrlap eseténalertOnIEDisabledOption
: true
– IE alatt (mely nem támogatja az option
elem disabled
paraméterét),
ha egy olyan elemet választunk ki, mely nem megengedett, legyen-e figyelmeztető üzenet (l. IEDisabledOptionAlert
)overwriteSubmit
: null
– az űrlap elküldésének szabályait figyelmen kívül
hagyja - ha nem null
- és az önmagával megadott értékkel tér vissza az isSendable
debug
: false
– true
esetén a warning
, required
, checkFormat
mindig
igaz értékkel tér vissza, vagyis az űrlap ellenőrzés nélkül elküldhetőEzen beállítások csak globálisan és egy csoporta is beállíthatóak (felüldefiniálhatóak).
autoFocus
: true
– lap indulásakor és új blokk beszúrásakor az első
elem megkapja-e a fókuszt? errorFocus
: true
– hibás kitöltés után van-e fókusz?autoInsertText
: true
– az insertText
legyen-e automatikusan
beszúrva, ha konfiguráláskor nem lett megadva?insertBlockPosition
: 'before'
– a beszúrt blokk elhelyezkedése a kezdeményező
blokkhoz képes ('before'
vagy 'after'
)showRepetitionPanel
: true
– a többszörözési panel megjelenjen-e? disableButtonAdd
: false
– a panel hozzáadás kezelőgombjának kikapcsolásadisableButtonRemove
: false
– a panel törlés kezelőgombjának kikapcsolásadisableButtonMoveup
: false
– a panel felfelé mozgatás kezelőgombjának
kikapcsolásadisableButtonMovedown
: false
– a panel felfelé mozgatás kezelőgombjának
kikapcsolásadisableOnInit
: false
– teljesítmény-optimalizáció: az onInit
esemény ellenőrzése kimarad-e?onlyFocusOut
: false
– teljesítmény-optimalizáció: csak a mező elhagyásakor van esemény (csak szövegmezők!)onlyFireElement
: false
– teljesítmény-optimalizáció: csak azt az elemet
adjuk át ellenőrzésre, amely kiváltotta az eseményt (névhivatkozás, összefüggések vizsgálata nem lehetséges)proform
: 'proform'
– maga a ProForm CSS térrequired
: 'required'
– kötelezőség jelzésewarning
: 'warning'
– hibás kitöltés jelzésepanel
: 'panel'
– az ismétlődés paneladd
: 'add'
– ismétlődés panel hozzáadás gombjaremove
: 'remove'
– ismétlődés panel törlés gombjamoveup
: 'moveup'
– ismétlődés panel mozgatás felfelé
gombjamovedown
: 'movedown'
– ismétlődés panel mozgatás lefelé gombjainsert
: 'insert'
– generált/megadott beszúrási szöveginsertNonVisible
: 'insert-nonvisible'
– ismétlődés nem látható eleme,
amely vagy a beszúró szöveg, vagy a táblázatsubmitError
: 'Az adatok rögzítéséhez a megjelölt mezők helyes kitöltése szükséges.'
–
nem elküldhető űrlapIEDisabledOptionAlert
: 'A kért elem nem kiválasztható!'
– l. alertOnIEDisabledOption
insertText
: 'A mező beillesztéséhez kattintson ide.'
– beszúró szövegaddTitle
: 'új blokk hozzáadása'
– panel szövegremoveTitle
: 'aktuális blokk törlése'
– panel szövegmoveupTitle
: 'blokk mozgatása felfelé'
– panel szövegmovedownTitle
: 'blokk mozgatása lefelé'
– panel szövegproform.translateStrings(oConfig);
A fordítási szövegeket egyben lehet átadni, nem kell külön-külön
a setConfig
-gal fordítgatni.
Object
, mely rendre tartalmazza az összes fordítható beállítást. proform.addGroup({ id, elements, validate, processor, repeat, repeatMin, repeatMax, insertId, alter, config});
Beállít
egy csoportot és ellenőrzését.
id
– String
, kötelező: a csoport azonosítója (az elrendezéstáblázat id
-je)
– ha nem létező azonosító, akkor eldobja a csoportot a proform (nincs róla hibaüzenet)elements
– Array
, kötelező: a csoporthoz tartozó elemek azonosítói (id),
az alábbi egyszerűsítés szerint:
normál: valami |
merge: valami:a |
|
---|---|---|
sima | valami |
valami:a |
választógomb | * |
*:a |
kiegészítő | valami_xyz |
valami_xyz:a |
ismétlődő sima | valami:0 |
valami:a:0 |
ismétlődő választógomb | *:0 |
*:a:0 |
ismétlődő kiegészítő | valami_xyz:0 |
valami_xyz:a:0 |
validate
– Boolean
, opcionális: kérjük-e a megadott azonosítók ellenőrzését
ill. megkeresését? Általában minden elemet az elements
-ben a saját id
-ével kell megadni,
úgy hogy az ne tartalmazza az ismétlődési elemeket. Ez alól kivétel a választógomb (input type=radio
),
amit a name
értékkel
kell megadni; az id
-ket automatikusan megtalálja ezt funkció hozzá. Ha egy olyan azonosító van megadva,
amely nem létezik, akkor megpróbálja megkeresni azokat az elemeket amelyek végződésükkel illeszkednek erre az
azonosítóra(tipikusan ilyenek a több tagból álló mezők: text_1
, text_2
...): kiegészítő
illeszkedés. processor
– Function
, kötelező: a csoport ellenőrzését végző funkció,
mely három értéket kap meg:
oT
– Object
, egy objektum, mely a elements
-ben megjelölt
objektumokat adja vissza az adott blokkra vonatkozóan saját nevükön (id
),sEventId
– String
, egy szöveges azonosító, amely jelöli, hogy az
ellenőrzést milyen esemény váltotta ki. Ezekre speciális esetben lehet szükségünk. Ennek lehetséges értékei:
'onInit'
,'onAddRepetitionBlock'
,'onRemoveRepetitionBlock'
,'onMoveRepetitionBlock'
,'onModify'
,'onFocusOut' (select)
,'onIsSendable
,'onMergingModify'
)sFireId
– String
, az eseményt kiváltó objektum azonosítója, hasonlóan
mint az első paraméternél; ennek csak akkor van értelme, ha az esemény egy mező módosításából ered (vagyis
ha a sEventId
értéke onModify
vagy onFocusOut
) más esetekben null
lesz
az értéke.repeat
– Boolean
, opcionális: ismételhető-e a csoport?repeatMin
– Number
, opcionális: a minimális csoportismétlés (alapértelmezett: 0
)repeatMax
– Number
, opcionális: a maximális csoportismétlés (alapértelmezett: Number.MAX_VALUE
)insertId
– String
, opcionális: a beszúrást jelző szöveg azonosítója
(csak ha repeatMin = 0
)alter
– Object
, opcionális: ismétlődő adatcsoportok esetén a blokkokkal
kapcsolatos három eseményhez (hozzáadás, törlés, mozgatás) lehet olyan kiegészítő metódusokat kapcsolni, amelyekkel
magát a blokkot tudjuk módosítani szükség esetén. Három elemfüggvényt lehet kapcsolni hozzá:
onAddRepetitionBlock( elTable, elTBody, oT )
, onRemoveRepetitionBlock( elTable, elTBody, oT )
, onMoveRepetitionBlock( elTable, elTBody, oT )
.elTable
– maga az egész csoport (table
),elTBody
– pedig maga a blokk (tbody
), amely kiváltotta az eseményt.config
- Object
, opcionális. A csoportra vonatkozó
beállítási lehetőségek, lehetséges felülkonfigurálások:
autoFocus
,errorFocus
,autoInsertText
,insertBlockPosition
,showRepetitionPanel
,disableButtonAdd
,disableButtonRemove
,disableButtonMoveup
,disableButtonMovedown
,disableOnInit
,onlyFocusOut
,onlyFireElement
,insertText
,addTitle
,removeTitle
,moveupTitle
,movedownTitle
.proform.config
-ot.proform.init();
A ProForm indítása a szükséges beállítások után.
proform.addRepetitionBlock(elReference);
Egy újabb blokk példányt készít egy ismételhető csoport
sablonjából és hozzáadja azt a csoporthoz (lásd még: insertBlockPosition
).
elReference
- DOMElement
, az az elem, amelynek kontextusában kell új
blokkot hozzáadni; ez külső meghívás esetén lehet egy table
elem (ha nincs még egyetlen csoport
sem hozzáadva) illetve egy tbody
elem... proform.removeRepetitionBlock(elReference);
Egy blokkot töröl egy ismételhető csoportból.
elReference
- DOMElement
, az az elem, amelyet törölni szeretnénk; külső
meghívás esetén tbody
proform.moveRepetitionBlock(elReference, nDirection);
Egy létező blokk felfelé ill. lefelé mozgatása
(az indexelés ezzel együtt változik).
elReference
- DOMElement
, az az elem, amelyet mozgatni kívánunk, külső
meghívás esetén ez tbody
nDirection
- Number
, amely kifejezi a mozgatás irányát, -1
esetén
felfelé, más esetben lefeléproform.condition.checkFormat(sType, arg1[, arg2])
Ellenőrzi, hogy a megadott argumentumok megfelelnek-e
a megadott formátumnak (sType
), majd igaz vagy hamis értékkel tér vissza. Az alábbi formátumokat kezeli:
number
, email
, phone
, ip
range
(4 argumentumot vár)datetime
, local-datetime
, date
, mont
, week
, time
(3
argumentumot vár, a 3. argumentum az elem className
-je, ami alapján eldönti az ellenőrzés során
a dátumformátum esetleges lokalizált voltát)proform.condition.addFormat(sName, oRe, sFormat);
Új ellenőrző dátumformátum hozzáadása, vagy bármelyik
jelenlegi formátum felüldefiniálása (hozzáadni, csak lokalizált dátumformátumokat lehet).
sName
– String
, kötelező: a formátum neve. Lokalizált dátumformátum
esetén illeszkednie kell az alábbi kifejezésre: (datetime|local-datetime|date|month|week|time)-[a-z]{2}
–
így egy dátumtípus altípusát hozzuk létre, amelyet a mező className
-jében, ahol hivatkozni akarunk
erre a formátumra, kell alkalmaznunkoRe
– Object RegExp
, kötelező: Egy reguláris kifejezés, mellyel az
illeszkedést vizsgáljuksFormat
– String
, nem kötelező: Erre csak dátumformátum megadásánál
van szükség, ezt használja a datepicker
beépülő a forma visszaadásának leírására. Továbbiakat lásd
ott.proform.condition.warning(bCondition, aEl, aErrorMessage);
Hibásan kitöltött mező vizsgálata és kijelezése.
bCondition
– Boolean
, a feltétel visszatérési értéke, pl. /[\w]+/test(
exaple.value )
aEl
– Array
, az elemek azonosítóiaErrorMessage
– Array
, az elemek hibaüzenetei (sorrendben)proform.condition.required(bCondition, aEl);
Kötelező de nem kitöltött mező vizsgálata és kijelezése.
bCondition
– Boolean
, a feltétel visszatérési értékeaEl
– Array
, az elemek azonosítóiproform.condition.totalize(aCondition);
Kiértékeli a csoport feltételeinek megfelelőségét, majd igaz
vagy hamis értékkel tér vissza. A warning
és required
értékek összesítésére szolgál.
aCondition
- Array
, egy tömb, amely true
vagy false
értékeket
tartalmaz (warning
és required
összegyűjtött visszatérési értékeket).proform.helper.activeForm.disableElement(bValue, el);
IE kompatibilitási megoldás, mely egy elemet
letilt.
bValue
- Boolean
, aktiválás vagy tiltás jelzéseel
- DOMElement
, maga az űrlap elemproform.helper.activeForm.update(elRoot);
Új elem generálása után inicializálja rá az activeForm
-t
(csak IE).
elRoot
- DOMElement
, az elem, amelynek gyermekei között kell a frissítést
elvégezni, ha nincs semmi megadva, akkor a document
lesz ez a gyökér.proform.helper.XMLHttpRequest.markUpdate( el );
Megjelöli, hogy egy mező módisítva lett a háttérben
(animáció).
el
– DOMElement
, kötelező: ez az elem egy táblázat cella (TD
)
kell legyen (általában az űrlap elem szülője).proform.helper.XMLHttpRequest.markUpdateOk( el );
Megjelöli, hogy egy egysoros szöveges mező értéke
a háttérben zajló kommunikáció során helyesnek találtatott (pipa).
el
– DOMElement
, kötelező: ez az elem egy egyoros szövege mező kell
legyen ill. jelszómező. proform.initForm(sId, fOnBeforeSubmit);
Beállítja egy űrlapra a ProForm összevonási módban való futását. Teljesen
megegyezik a proform.initForm
funkcionalitásával.
proform.addGroup({ id, elements, validate, processor, repeat, required, changer});
Beállít egy összevonási
csoportot és annak ellenőrzését. Ügyelni kell arra, hogy itt egyszerre mindkét oldalt állítjuk be – mivel a két
oldal nem különbözik tartalmában.
FONTOS! A funkció úgy lett kialakítva, hogy a sima űrlap beállításokat könnyen át lehessen ültetni az összevonási űrlapra. Csupán más modult kell meghívni és néhány beállítást megváltoztatni. Viszont az elemek megadása és az ellenőrzés AZONOS, így azon általában semmit sem kell változtatni:
:a
és a :b
oldal
különbségét elnyomja a JS interfész, vagyis úgy látjuk az elemeket és úgy is kell hivatkoznunk rá mintha normál
elemek lennének (id, elements, processor)
a funkció átkonvertálja a beállításokat :a
és :b
oldalra. Pl. my_test:a
és my_test:b
helyett
csak my_test
.addGroup
, hanem az ellenőrzésekben figyeli, hogy
melyik oldal van kiválasztva. Technikaibb nyelven szólva, a required
és a warning
vizsgálatokat
kiegészíti egy további feltétellel: a megadott kapcsoló szerint az blokk ki van választva vagy sem (pl. oT.switch_mytest.value
== 1 &&
...) A funkció paraméterei nagyban hasonlítanak a proform.addGroup
funkcióra, az eltérések:
processor → sEventId → 'onMergingModify
' – ha kijelöljük az egyik oldalt, ezzel az azonosítóval
kapunk róla eseményt,repeat
– Boolean
, opcionális: ismételhető-e a csoport? Ha a csoport ismételhető,
akkor a két oldal elemei többszörösen kiválaszthatóak (akár az összes is), ellenkező esetben mindig csak az egyik
oldal.required
– Boolean
, opcionális: Ha a csoportból az egyik oldal mindenképpen
ki kell legyen választva. Inicializáláskor az :a
oldal ezért kiválasztásra kerül, és nem lehet a kiválasztást
levenni róla, csak áthelyezni a másik oldalra.changer
– String
, kötelező: Az a (rejtett) elem, kapcsoló, amely megmutatja
egy csoportban, hogy melyik oldal van kiválasztva. proform.merging.init();
A ProForm összevonási módban való indítása a szükséges beállítások után.
Nem azonos a proform.init
-tel.
proform.merging.selectSide(el, elOtherSide, sSideId);
A ProForm összevonási üzemmódjában az egyik
oldal teljes kijelölése. Figyeljünk arra, hogy a másik oldal blokkjairól csak akkor veszi le a kijelölést, ha nem
ismételhető csoportról van szó.
el
– DOMElement
, kötelező: a gomb maga, amivel kiváltjuk az eseményt
(legtöbb esetben: this
),elOtherSide
– DOMElement
, kötelező: a másik gomb,sSideId
– String
, kötelező: 'a'
vagy 'b'
-
amely jelzi, hogy melyt oldalt akarjuk kijelölni. pager.setOrderbyCode( el, nOrderByCode );
A pager rendezési oszlopát változtatja meg. E funkció
miatt fontos, hogy a pager előtt közvetlenül álljon a pager fejléce (ne legyen köztük a DOM fában más elem).
el
– DOMElement
, kötelező: maga fejléc cellája, amire kattintva kiváltódik
az eseményt (this
),nOrderByCode
– Number
, kötelező: egy szám, ami hordozza, hogy hányadik
oszlop szerint kell rendezni (pozitív szám esetén növekvő, negatív szám esetében csökkenő sorrendben). pager.moveCursor( el, nDirection );
A pager oldalai közti gyors-lapozást végzi.
el
– DOMElement
, kötelező: maga link vagy gomb, ami kiváltja az eseményt
(this
), nDirection
– Number
, kötelező: 1
vagy -1
a
lehetséges értékei, ennek megfelelően előre vagy hátra lapoz a lapozó választólista. filter.hideFilter(el);
A funkció elrejti a szűrőt és annak mentési területét is és helyette a beszúró szöveget
jeleníti meg (ill. azt le is cseréli: 'A szűrőfeltételek módosításához kattintson ide.'). E funkció miatt fontos,
hogy a szűrő és annak mentési területe közvetlen egymás után jöjjön (ne legyen köztük a DOM fában más elem).
el
– DOMElement
, kötelező: maga a (harmadlagos) gomb, amely kiváltja az esemény (this
). filter.showFilter( elTable );
A szűrőt láthatóvá teszi a mentési területével együtt. Ezt a funkciót
úgy kell alkalmazni, hogy a csoport definiálásakor (addGroup
) egy módosítót kell bekapcsolni az onAddRepetitionBlock
eseményre,
amely módosító ezt a funkciót hívja meg. Példa egy szűrő inicializálására:
proform.addGroup( { id : 'group_demo', repeat : true, repeatMin : 0, repeatMax : 1, insertId : 'proform-insert-filtration', elements : [ 'filter_target_demo' ], processor : function( oT ) { return true }, config : { showRepetitionPanel : false }, alter : { onAddRepetitionBlock : filter.showFilter } } );
elTable
– DOMElement
, kötelező: szűrő táblázata, amelybe új csoportként kerül a szűrő. filter.removeFilter();
A funkció kikapcsolja a szűrő kötelező elemeit és így kerül küldésre az űrlap (egy submit
gombra kell ültetni).
Az ProForm alkalmazására számos példa adott. Az alapvető használata a következő:
initForm
)addGroup
) - ekkor adjuk meg a feldolgozó metódust issetConfig, translateStrings, addFormat
)init
)Ugyanilyen elven kell indítania az összevonási űrlapot is.
A különböző típusú eszközök XHTML kódját és JavaScript inicializációját a példák mutatják be és írják elő. A példákból lehet megtanulni.
A CSS megvalósítás testreszabható. Javasolt módosítás az átszínezés, a konzisztencia megőrzése miatt a nagyobb mérvű változtatások nem javasoltak. A CSS állományok az eszközöknek megfelelően bizonyos fokig modulárisak, vagyis elég testreszabni az alkalmazni kívánt eszközöket.
A ProForm alap JavaScript eszközkészlet együtt tud működni más megoldásokkal. Ezek között van néhány kiemelt,
amelyet automatikusan is tud kezelni. Ez azt jelenti, hogy ezek inicializációjával és kezelésével nem kell külön
foglalkozni be van építve a proform.plugin
készletbe. Ilyen automatikus kezelésű bedolgozók:
textarea
elemek látványáhozA Calendar Widget 1.0-s verzióját alkalmazza. Mivel elég gyakori a dátum mező, úgy van tervezve, hogy automatikusan
felismerje a ProForm ezeket a mezőket. Letöltse a szükséges JS és CSS állományokat és inicializálja az összetevőt.
Mindössze egy className
helyes megadása szükséges az XHTML kódban. A támogatott formátumok a példaoldalon tekinthetők
meg. Lásd még: proform.condition.addFormat
.
A richtext egy túlhaladott komponens. A 'richtex'
CSS osztállyal lehet indítani.
Ez a kis apró komponens a textarea
mezők a tartalomnak megfelelő, automatikus, függőleges irányú
átméretezéséről gondoskodik. Csak a Gecko és az IE támogatott. Indításához a 'textareaautoheight'
CSS
osztyálnevet kell elhelyezni az elem className
leírójában, melyre automatikusan betöltődik a modul
és alkalmazódik az elemre. Példa
A bedolgozók – természetesen – azonos JavaScript interfésszel rendelkeznek:
proform.plugin.[pluginnév].init();
Megvizsgálja, hogy szükség van-e a bedolgozót betölteni. Ha talál egy olyan
elemet, amire be van állítva, akkor letölti a szükséges állományokat (JS, CSS).
proform.plugin.[pluginnév].start();
Az állományok betöltődése után elindítja a bedolgozót minden egyes elemre,
amelyre be lett állítva.
proform.plugin.[pluginnév].disable();
Kikapcsolja a bedolgozót. Ha ezt szeretnénk, akkor még az indulás előtt
kell megtenni, tehát a proform.initForm
környékén.
proform.plugin.[pluginnév].setConfig( sConfig, sValue );
Minden bedolgozónak vannak egyedi beállításaik, amelyek
módosítására időnként szükség lehet. A beállításokat a proform.plugin.[pluginnév].config
objektumban találjuk.
Működése hasonló a proform.setConfig
-ban leírtakkal.
Ezeken kívül a ProForm alkalmazva volt már az alábbi (automatikusan nem kezelhető) komponensekkel. A kapcsolat csupán az együttműködés. Minden modult önállóan kell kezelni, nincs semmilyen kapcsolatban a ProForm JavaScript megoldásaival.
Az xmlTree egy többcélú fakezelő megoldás, amely együtt tud működni a ProForm-mal. Mivel űrlapok adatainak faszerű megjelenítésére lett tervezve, gyakorlatilag a ProFrom moduljaként értelmezhető. Mivel a működése nagyobb testreszabási lehetőségeket biztosít önállóan kell indítani, nem rendelkezik automatikus inicializációval. Példa
Bár kívánatos lenne hogy a TinyMCE automatikus indítással is rendelkezzen, de a komponens belső felépítése ezt
nem teheti lehetővé. Az együttműködésen túl nincs más kapcsolat. (A warning
és a required
nem
megvalósítható...)