DataSource - dátový zdroj (entita a služba)
V SmartClient aplikáciĂ je DataSource popisom jednotky biznis modelu, v podobe kombinovanej Entity (definĂcia dátovĂ˝ch polĂ) a SluĹľby (volateÄľnĂ© metĂłdy sluĹľby).
Formátom je JavaScript, a v týchto definiciách sú konkrétne GUI nastavenia, alebo ich variácie.
DátovĂ˝ch zdrojov mĂ´Ĺľe byĹĄ mnoho (z rĂ´znych serverov) a musia maĹĄ unikátne ID a v prĂpade sluĹľieb zobrazujĂşcich dáta aj dataURL.
Ich samotný kód môžu generovať serverové aj klientské adaptéry-
DataSource teda vzniká z nejakého meta-modelu, a môže sa
ID | jednoznačný a povinný názov DataSource - napr. Zamestnanec, alebo firma_org_Jednotka (namiesto bodiek) |
metaID | nepovinný perzistentný nemenný identifikátor (podľa backendu) |
dataURL | url pre Službu (nastaviteľné aj pre jednotlivé metódy), napr. /service/{ID}/, /sluzba?_dataSource={SERVICE} , https://host:1234/invoke.php?service={SERVICE} |
javaClass | Fully qualified class name |
inheritsFrom | ID zdedeného DS |
interfaces | čiarkou oddelený zoznam zdielaných chovanà na server/klient, napr. auditable, version, status či document |
module | triedenie do package |
DataSource sa mĂ´Ĺľe stiahnuĹĄ z backendu on-demand. Skontroluje sa dediÄŤnosĹĄ a pouĹľitĂ© asociácie, a stiahnu sa tieĹľ (ak chĂ˝bajĂş). Potom sa zavolá callback. Naopak ak uĹľ je všetko k dispozĂcii, callback sa spustĂ ihneÄŹ.
// a/synchrĂłnne
Root.getDataSource('serverDS1', function(dataSource) {
// some callback ...
widget.setDataSource(dataSource);
});
DataSource.create({ // tvorba
ID: 'ds2',
metaID: 2,
inheritsFrom: 'serverDS1',
javaClass: 'sk.f4s.albiq.demo.DS1'
});
var ds1 = DataSource.get('ds2'); // referencia podla ID
var ds1 = DataSource.get(2); // referencia podla metaID
Fields
Objekt s názvom poÄľa ako kĺúčom, hodnotou ako vlastnosĹĄami. Poradie polĂ je danĂ© fyzickĂ˝m poradĂm, zdedenĂ© polia sa pripoja nakoniec (zmena poradia cez useParentFieldOrder). ZadanĂ© vlastnosti majĂş všeobecnĂ˝ charakter.
Viac o poliachNiektorĂ© polia majĂş špeciálny vĂ˝znam - naprĂklad nadpis (titleField), popis alebo hodnota.
Pre custom GUI potreby (detaily, formuláre, zoznamy...) je moĹľnĂ© zadávaĹĄ hybridnĂ© text/object polia, ktorĂ© sĂş dediÄŤnĂ© a rekurzĂvne (odkaz na ne je textovĂ˝, napr '$auditables'). Ak názov fieldSetu konÄŤĂ na 'Fields', na zobrazujĂşci komponent sa mĂ´Ĺľu, aplikovaĹĄ vlastnosti pod kľúčom ...Props.
DataSource.create({
ID: 'audit',
fields: {
id: {type:'integer', canEdit: false},
version: {type: 'integer', hidden: true}
},
// shared fieldSet
auditables: [ 'id', {name: 'version', hidden: false} ]
});
DataSource.create({
ID: 'Zamestnanec',
inheritsFrom: 'audit',
fields: {
celeMeno: {type: 'text', required: true, length: 32},
mzda: {type: 'float', canEdit: false},
vzhÄľad: {type:'longtext', detail: true}
}
// celĂ˝ zoznam
// celeMeno,mzda,id,-version
// polia pre zoznam ($ = vloĹľiĹĄ inĂ˝ fieldSet)
listFields: ['celeMeno,mzda', '$auditables' ],
// vlastnosti pre 'zoznam' komponent
listProps: {
canExpandRecords: true
}
});
fields | Object s poÄľami |
titleField | názov poľa pre textovú reprezentácia záznamu, nadpis (napr. priezvisko)) |
infoField | nieÄŤo ako podnadpis (napr. meno) |
dataField | najdôležitejšia netextová hodnota (napr. vek) |
descriptionField | bližšà popis záznamu (napr. pozĂcia) |
indexField | KtorĂ˝ field sa pouĹľĂva ako index (poradie) v rámci agregácie. Zapne zobrazenie indexu v prvom stÄşpci zoznamu (showRowNumbers, rowNumberField), vypne moĹľnosĹĄ zoraÄŹovania, ÄŤi zapne drag-reorder poradia riadkov. |
treeParent | ktoré pole je identifikátorom parenta (pre stromové štruktúry) |
isFolderProperty | ktoré pole určuje, či máme children (performance) |
listFields | polia pre použitie v zoznamoch, pridateľné polia sú ukryté cez showIf:'false' |
detailFields | polia pre detailné zobrazenie zázamu, aj editovateľné |
editFields | polia čisto pre editáciu záznamu |
pickFields | výber v pickList/comboBox |
assocFields | zobrazenie ako súčasť iného detailu |
*Fields | explicitnĂ˝ fieldSet pre custom prĂpady, alebo slúžiace na kompozĂcie |
*Props | pre daný fieldSet, vlastnosti aplikované na zobrazujúci komponent |
FieldSet include sa robà pomocou $ prefixu a názvu iného setu (aj v zdedených DS) ako sufixu. Pozor sa dáva na rekurzivitu a vkladanie polà optimalizované pre iné konktrétne použitie (napr. list vs detail).
FieldSet je array: objektov definĂciĂ obsahujĂşcich povinne name poÄľa; stringov ako ÄŤiarkou oddelenĂ˝ zoznam názvov názvov polĂ, priÄŤom za názovom a dvojbodkou mĂ´Ĺľe byĹĄ ešte typ poÄľa type
DataSource.create({
ID: 'FieldSetDemo',
fields: {
a: { ... },
-
z: { ... }
},
mainFields: ['a,b,c', {name:'d', colSpan: 2}],
valueFields: [{name:'total', canEdit:false}, 'f,g', 'h'],
pickFields: ['a:float,b:integer', 'h'],
listFields: ['$mainFields,$valueFields,i,j', 'k', {name:'m', showIf:'false'}],
editFields: ['$mainFields', 'h'],
detailFields: ['$editFields', '$valueFields', 'i,j,k']
});
Operácie
Operácie sĂş RPC (ale aj clientOnly) metĂłdy ponĂşkane Serverom na danom DS pre aktuálneho pouĹľĂvateÄľa. MajĂş definovanĂ© argumenty, návratovĂş hodnotu a prepisovateÄľnĂ© chovanie na GUI, v rámci lifecycle.
DS rozdeluje viditeľné operácie podľa spôsobu použitia na Zozname a Detaile (s možnosťou upresnenia):
listovacie | vracajú zoznam záznamov, napr. podľa filtra |
vytváracie | tieto operácie založia nový záznam, typu návratovej hodnoty |
detail | podÄľa primárneho kľúča zĂskavajĂşce kompletnĂ˝ záznam, pre zobrazenie na Detaile |
detail akcie | operácie nad konkrétnym záznamom |
masové akcie | operácie nad zoznamom záznamov |
ostatné | iné neurčiteľné operácie |
operations | array definĂciĂ |
DataSource.create({
ID: 'OperationsDemo',
field: {
id: {type:'integer', required: true},
nadpis: { colSpan: 2 }
},
operations: {
zmenNadpis: {
args: {
id: { dataSource: 'OperationsDemo', type: 'integer'}, // key
nadpis: {type: 'text' }
},
return: {type: 'OperationsDemo', dataSource: 'OperationsDemo'} // refresh
}
}
});
Lokalizácia
DataSource je vytvorenĂ˝ v jazyku pouĹľĂvateÄľa (anglicky, slovensky), prekladanĂ© sĂş aj názvy a popisy polĂ, operáciĂ a argumentov, ako aj syntetickĂ˝ch GUI poloĹľiek.
title | Nadpis triedy danĂ©ho záznamu - naprĂklad 'InternĂ˝ zamestnanec' |
pluralTitle | Nadpis pre službu alebo iné zoznamy - 'Internà zamestnanci' |
field.title | HlavnĂ˝ nadpis poÄľa |
field.short | Nadpis poÄľa v skrátenĂ˝ch prĂpadoch (tlaÄŤĂtko, list header) |
field.prompt | Popist poÄľa, tooltip |
locales | inak implemetovaná prekladová mapa názvov polà a ich popisov |
{
title: 'Firemné auto',
pluralTitle: 'Firemné autá',
fields: {
znacka: { title: 'EvidenÄŤnĂ© ÄŤĂslo', shortTitle: 'EÄŚV', prompt: 'Osadená zákonná znaÄŤka na vozidle' }
},
locales: {
poslednaEK: 'EK',
poslednaEK_prompt: 'Posledná emisná kontrola'
}
}
Ikony
DataSource pouĹľĂva vlastnĂ˝ systĂ©m ikon, ktorĂ˝ obchádza obsah a accessibility. PouĹľĂva na to I (HTML5 obsolete) tag, s urÄŤenĂm sady a ikony pomocou css class.
Icon font FontAwewome pouĹľĂva predponu 'fa', alebo vlastnĂ˝ set 'svg' definuje SVG ikony, pomocou zápisu <i class="svg svg-user"></> zobrazĂ ikonu
ficon | Vybraná ikona sa pouĹľĂva v menu a v nadpise DataSource |
field.ficon | Ikona poľa sa použije na detaile alebo formulári |
{
ficon: 'fa fa-users', // icon FontAwesome
ficon: 'img img-delete', // .png images
ficon: 'ifc ifc-confirm', // based on iconf-font custom
fields: {
iconedField: { ficon: 'fa fa-cog' }
},
fieldSet: [ {name:'userName', ficon: 'fa fa-user' } ]
}
Interfaces
Špeciálne server/klient chovani, ako čiarkou odelený zoznam v interfaces. Na GUI definuje upraviť chovanie alebo zobrazenie významných polà (napr. výrazne v title alebo tools častiach widgetov)
auditable | |
versionable | obsahuje pole version (server optimistic-locking). mohol by umoĹľniĹĄ merge poÄŤas konfliktu |
calendar | obsahuje údaje pre zobrazenie v čase (napr. v kalendári či dashboarde), potrebuje infoField/descriptionField a dátumy zatiatok, koniec a voliteľný kedy presne zobraziť. isEvent = legacy DS property |
document | okrem titleField, infoField a descriptionField mĂ´Ĺľe pridávaĹĄ Tagy alebo thumbnail image. HovorĂ, Ĺľe objekt má meta informácie pouĹľiteÄľne v HTML, SEO |
taggable | definuje kategorizáciu podľa Tagov |
discussion |
Server chovanie
Nastavenia pre samotnĂ© dáta, ktorĂ˝mi disponuje na klientovi tento DS. Dáta sa zĂskavajĂş zo servra alebo sĂş kalkulovanĂ© na klientovi, mĂ´Ĺľu byĹĄ statickĂ© alebo maĹĄ omedzenĂş platnosĹĄ.
clientOnly | true vypni volanie servra (staické/kalkulované dáta) |
cacheAllData | true naÄŤĂta všetky dáta a dá do cache, poÄŤas prvej potreby (cacheAllOperationId - alternatĂvna operácia na tieto účely) |
cacheData | statické alebo aktuálne data ako array záznamov |
cacheMaxAge | sekúnd do vypršania platnosti cache |
hasCompleteRecords | dáta pre zoznamy sú považované za kompletné, a pre detail nie je potrebné zavolať napr. findById |
GUI chovanie
hasDetail | false vypne možnosť zobrazovať záznam ako detail |
forceDetail | true vynĂşti zobrazenie Detail na split-screen hneÄŹ po otvorenĂ |
autoFetchData | false vypne automatickĂ© naÄŤĂtanie dát hneÄŹ po zobrazeni Listu |
canReuseDetail | false vypne moĹľnosĹĄ prepouĹľitia Detailu na editáciu pre operácie, ktorĂ© to umoĹľĹujĂş. |
canPrint | false vypne moĹľnosti tlaÄŤe SC |
canFilter | napriek operáciám, vypne server filter |
canDefineView | false vypne moĹľnost ukladaĹĄ nastavenĂ |
canSort | false vypne moĹľnost triedenia poradia |
canMultiSort | false vypne triedenie podÄľa viac ako jednej voÄľby |
defaultSort | -date,name default triedenie zoznamu záznamov |
canHilite | false vypne možnosti rozlišovania |
canExportData | false vypne export zoznamu/záznamu do súboru |
detailWindow | bool - open detail in popup window |
GUI rendrovanie
serviceDetailPosition | poloha bottom, top, left, right urÄŤĂ kde bude Detail voÄŤi Listu na split-screen. |
toolsDetailWidget | poloha toolbaru na Detaile |
toolsServiceWidget | poloha toolbaru na Zozname |
autoFilterEditor | automaticky zobrazovať filter editor v Liste (ak podporuje hľadacia operácia) |
autoFilterEditor | automaticky zobrazovať filter editor v Liste (ak podporuje hľadacia operácia) |
hilites | farebnĂ© zvĂ˝razĹovanie riadkov |
MetĂłdy
copyRecord[s](recs) | skopĂruje record alebo pole recordov s pouĹľitĂm len dátovĂ˝ch kľúčov |
filterData(criteria,callback) | |
getField(name) | |
getFieldNames(noHidden) | |
getPrimaryKeyFieldName() | |
invalidateCache() | |
appendTitle | |
appendTools | |
optimizeDetailField(fld, widget) | |
optimizeEditField(fld, widget) | |
optimizeListField(fld, widget) | |
fieldLocale(key) | |
getTitleService() | |
getRecordTitle(rec) | |
getInheritedProperty(prop) | zĂskanie najbližšej hodnoty (dediÄŤnej) vlastnosti DS |
isInheritedFrom |
RĂ´zne
Hilites
FarebnĂ© zvĂ˝razĹovanie riadkov alebo buniek zoznamov sa dehe pomocou pola hilites.
DefinĂcia zvĂ˝raznenia obsahuje najÄŤastejšie podmienky aplikovania, zoznam stÄşpcov (inak celĂ©ho riadku), a CSS kĂłd.
criteria | Criteria výberu riadku, na ktorý sa Hilite aplikuje |
cssText | CSS štýly pre bunku/y |
fieldName | názov stĺpca, alebo pole názvov |
htmlAfter | HTML pred hodnotou |
htmlBefore | HTML za hodnotou |
title | názov pravidla (pre editovacie účely) |
textColor, backgroundColor | legacy color codes |
Farba textu alebo pozadia môže byť daná ako konštanta, ktorú aplikuje každý Skin:
$TITLEFIELD
['.TITLECOLOR', '.ACTIVE', '.DONE', '.WARN', '.ERROR', '.CANCEL']