Felhasználói felület demó: dokumentáció

A ProForm célja

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 mibenléte

A ProForm tehát egy kidolgozott eszközcsoport, egy alkalmazási mintákkal megfogalmazott szabálygyűjtemény.

A ProForm korlátai

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 JavaScript interfésze

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.

Űrlap (proform)

A legtöbbet használt és legtöbb funkcióval rendelkező modul maga az alap űrlapkezelés. Ezt kell leginkább ismerni.

Alapvetű funkciók

proform.initForm

proform.initForm(sId, fOnBeforeSubmit); Beállítja egy űrlapra a ProForm futását.

proform.config

proform.setConfig( sConfig, sValue ); Beállít egy bizonyos tulajdonságot.

Globális működési beállítások:

Ezen beállítások csak globálisan, az egész űrlapra állíthatóak be.

Blokk színtű működési beállítások:

Ezen beállítások csak globálisan és egy csoporta is beállíthatóak (felüldefiniálhatóak).

CSS osztályok:
Szövegek ill. fordítások:
proform.translateStrings

proform.translateStrings(oConfig); A fordítási szövegeket egyben lehet átadni, nem kell külön-külön a setConfig-gal fordítgatni.

proform.addGoup

proform.addGroup({ id, elements, validate, processor, repeat, repeatMin, repeatMax, insertId, alter, config}); Beállít egy csoportot és ellenőrzését.

proform.init

proform.init(); A ProForm indítása a szükséges beállítások után.

proform.addRepetitionBlock

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).

proform.removeRepetitionBlock

proform.removeRepetitionBlock(elReference); Egy blokkot töröl egy ismételhető csoportból.

proform.moveRepetitionBlock

proform.moveRepetitionBlock(elReference, nDirection); Egy létező blokk felfelé ill. lefelé mozgatása (az indexelés ezzel együtt változik).

Ellenőrzések

proform.condition.checkFormat

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:

proform.condition.addFormat

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).

proform.condition.warning

proform.condition.warning(bCondition, aEl, aErrorMessage); Hibásan kitöltött mező vizsgálata és kijelezése.

proform.condition.required

proform.condition.required(bCondition, aEl); Kötelező de nem kitöltött mező vizsgálata és kijelezése.

proform.condition.totalize

proform.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.

Kiegészítők

proform.helper.activeForm.disableElement

proform.helper.activeForm.disableElement(bValue, el); IE kompatibilitási megoldás, mely egy elemet letilt.

proform.helper.activeForm.update

proform.helper.activeForm.update(elRoot); Új elem generálása után inicializálja rá az activeForm-t (csak IE).

proform.helper.XMLHttpRequest.markUpdate

proform.helper.XMLHttpRequest.markUpdate( el ); Megjelöli, hogy egy mező módisítva lett a háttérben (animáció).

proform.helper.XMLHttpRequest.markUpdateOk

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).

Összevonási űrlap (proform.merging)

proform.merging.initForm

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.merging.addGroup

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 funkció paraméterei nagyban hasonlítanak a proform.addGroup funkcióra, az eltérések:

proform.merging.init

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

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ó.

Lista (pager)

pager.setOrderbyCode

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).

pager.moveCursor

pager.moveCursor( el, nDirection ); A pager oldalai közti gyors-lapozást végzi.

filter.hideFilter

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).

filter.showFilter

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 }
                } );

filter.removeFilter

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).

A ProForm alapvető JavaScript alkalmazása

Az ProForm alkalmazására számos példa adott. Az alapvető használata a következő:

Ugyanilyen elven kell indítania az összevonási űrlapot is.

A ProForm alkalmazása és testre szabása (XHTML, CSS)

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.

ProForm bedolgozók kezelése és együttműködés más modulokkal

Bedolgozók

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:

datepicker

A 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.

richtext

A richtext egy túlhaladott komponens. A 'richtex' CSS osztállyal lehet indítani.

textareaAutoHeight

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

Bedolgozók JavaScript interfésze

A bedolgozók – természetesen – azonos JavaScript interfésszel rendelkeznek:

proform.plugin.[pluginnév].init

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

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

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

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.

Együttműködők

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.

xmlTree

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

TinyMCE

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ó...)

800×600 1024×768