XAML.cz Magazín moderních technologií založených na XAML

V minulém článku jsem ukázal jak zpřístupnit Silverlight aplikaci v HTML stránce a které techniky je k tomu možné použít. Zároveň jsem se zmínil, že upřednostňovaným způsobem je použití JavaScriptové knihovny umístené v souboru Silverlight.js. A právě na možnosti, které nám tato knihovna nabízí bych se rád podíval v dnešním článku.

Funkce v Silverlight.js

Soubor Silverlight.js poskytuje hned několik funkcí, které slouží ke zpřístupnění Silverlight aplikace stejně, jako k její kontrole. Funkci createObjectEx už jste mohli vidět v minulém článku, ale není to jediná a tak je zkusím představit všechny a to pěkně abecedně:

• buildPromptHTML – tato metoda vrátí HTML, které zobrazuje výzvu k instalaci Silverlight pluginu
• createObject – inicializuje a vytvoří Silverlight plugin
• createObjectEx – chová se stejně jako předchozí funkce, jen s tím rozdílem, že využívá JSON pro předání parametrů
• HtmlAttributeEncode – zajišťuje základní operace s textovými řetězci a je primárně určena pro interní použití uvnitř Silverlight.js souboru
• isInstalled – vrací hodnotu informující o tom, zda je nainstalována příslušná verze Silverlight pluginu

a to je vše, co byste mohli potřebovat pro vytvoření a inicializaci Silverlight pluginu a nahrání aplikace. Důležité tedy jsou především dvě zmíněné funkce createObject a createObjectEx, na které se podívám blížeji.

Vytvoření Silverlight pluginu

Jak jsem již zmínil, vytvořit Silverlight plugin je možné pomocí dvou funkcí a to createObject a createObjectEx. Tyto dvě funkce dělají to samé a createObjectEx ve výsledku volá metodu createObject. Viditelný rozdíl je však v předání parametrů do těchto metod, kdy createObjectEx používá pro předání parametrů JavaScript Object Notation (JSON), což se může jevit více popisně a tím pádem přehledněji.

Funkce createObjectEx potřebuje jako jeden z parametrů vytvořený HTML element, nejsnazší způsob jak toho docílit je tedy umístit volání této metody do tohoto hostitelského HTML elementu. Samozřejmě můžete využít i jiných možností. Tato funkce dále přijímá další parametry, které slouží k tomu, aby se Silverlight aplikace lépe integrovala do prostředí HTML stránky.

Integrace do stránky

Integrovat Silverlight aplikaci do stránky nemusí znamenat jen správné vizuální zakomponování, ale také zajistit požadované chování takové aplikace s ohledem na hostující stránku. To znamená zajistit tyto věci

• předat inicializační parametry
• reagovat správně na události, které plugin vyvolává
• začlenit Silverlight aplikaci do DOM HTML stránky
• zajistit výchozí vzhled

Inicializační parametry

Inicializační parametry si asi každý může představit různě, ale tyto parametry využívá snad každá aplikace a slouží k předání hodnot, které jsou dostupné hned při startu aplikace a na jejichž základě se odvíjí další chování. Například u aplikace Word je takovým parametrem název souboru, který má být otevřen v případě, že poklepáme na soubor doc/docx. Pokud tedy chceme předat nějaké hodnoty do Silverlight aplikace, můžeme k tomu využít pojmenovaného parametru initParams a pomocí textového zápisu předat klíč a hodnotu do naší aplikace nějak takto

klic1=hodnota, klic2=hodnota2, klic3=159

jednotlivé hodnoty jsou tedy odděleny čárkou a k hodnotám přísluší jejich klíč, pomocí něhož se k hodnotě dostaneme. Jediný rozdíl je v případě, že byste se rozhodli vyvíjet ještě pro první verzi Silverlightu, která neměla zápis v podobě klíč=hodnota, ale pouze seznam hodnot oddělených čárkou.

Dalším inicializačním parametrem, který občas můžete využít je pojmenován jako context a slouží k jednoznačné identifikaci daného Silverlight pluginu na stránce. Toho využijete především v případech, kdy budete mít na stránce více jak jeden instancovaný plugin a budete je tedy chtít rozlišit.

Zpracování událostí vyvolaných pluginem

V průběhu startu Silverlight pluginu jsou vyvolány události, na které můžeme reagovat a podle toho také reagovat ještě z HTML stránky. Těmito událostmi jsou onLoad a onError. Přihlášení se k odběru k těmto událostem je možné přes definovaný subobjekt events tak jak je naznačeno níže:

Silverlight.createObjectEx({
...
events: {
onLoad: SL_Load,
onError:SL_Error
}
});

Samozřejmě není nutné se k těmto událostem vždy přihlašovat a obsluhovat je, pokud bychom však chtěli dát detailní zprávy uživateli a to asi především při zpracování chyb, budou nám tyto události ku prospěchu.

Ale začnu pěkně po pořádku, událost onLoad je vyvolána v okamžiku, kdy dojde k nahrání Silverlight aplikace a my tak můžeme informovat uživatele, případně zpracovat vstupní údaje o této nahrané aplikaci. Tyto informace jsou předány do metody obsluhující tuto událost a to v tomto pořadí

• sender – je odkazem na samotný Silverlight plugin
• context – jak už jsem napsal výše, jedná se o unikátní identifikátor zprostředkovaný vývojářem
• source – představuje root element pro daný plugin, jak taktéž bylo zmíněno výše

K vyvolání této události však nemusí docházet vždy, to může zapříčinit hned několik věcí mezi něž patří třeba špatný odkaz na soubor aplikace, nebo v okamžiku, kdy máme nějakou chybu v samotném volání metody createObjectEx. To by nás mohlo vést k tomu, že v takovýchto případech dojde k vyvolání události onError, což však neplatí a tato událost je vyvolána jen v případě, že dojde k úspěšnému nahrání Silverlight aplikace.

Událost onError je tedy vyvolána v okamžiku, kdy máme nahranou aplikaci, avšak v ní dojde k neošetřené výjimce. Některé chyby však nelze ani v managed kódu zachytit a právě to je správné místo pro použití JavaScriptového ošetření těchto chyb. Pokud se tedy chceme dozvědět bližší informace o chybě, budeme potřebovat znát strukturu těchto informací v předaných parametrech do metody obsluhující tuto chybu. Metoda přejímá dva parametry:

• sender – který je odkazem na samotný Silverlight plugin
• errorArgs – jenž představuje strukturu detailních informací, která publikuje tento interface
  • ErrorCode – číselný kód chyby
  • ErrorMessage – textový popis chyby
  • ErrorType – představuje kategorii chyby
  • Name – je jménem objektu, který vyvolal chybu

Díky zpracování chyb tak můžeme zjistit bližší informace o chybách, ke kterým dochází v aplikaci a které není možné ošetřit na vyšším stupni.

Začlenění Silverlightu do DOM

Již tedy víte, jak předat inicializační parametry do aplikace, jak ošetřit události, ke kterým dochází při startu a nebo v průběhu běhu aplikace, ale vlastně ještě nevíte, jakým způsobem dostat tu aplikaci na klienta a jak ji začlenit do stránky.

Prvním parametrem, který je vlastně nejdůležitější, a který jste mohli vidět hned v úvodních ukázkách je předání zdroje aplikace. Jak vidíte, zmiňuji se o zdroji aplikace, byť asi nejčastější bude, že budete předávat odkaz na .xap soubor, takovýto způsob se nazývá Packed. Dalším typem zdroje může být odkazovat se přímo na xaml soubor a pak můžeme hovořit o tzv. Loose způsobu. Poslední možností je to, že budeme definovat xaml přímo na úrovni nějakého elementu, který bude mít jednoznačné ID, pak budeme odkazovat přímo na tento element a můžeme hovořit o tzv Inline stylu.

Parametr, kterým se předává odkaz na Silverlight aplikaci je pojmenován jménem source a jednotlivé možnosti je tak možné zapsat následovně:

source: "ClientBin/MySilverlightApp.xap"
source: "/folder/page.xaml"
source: "#xamlId"

Myslím, že se asi nejvíce budete potkávat hned s prvním případem, jelikož ten umožňuje využít managed vývoje.

Dalším parametrem, který je třeba naplnit je parametr parentElement a je to odkaz na element, nikoliv tedy jen samotný název – ID - elementu, který bude obsahovat náš Silverlight plugin. Do tohoto elementu pak bude vložen Silverlight plugin pomocí elementu object v případě Internet Exploreru a FireFoxu a pomocí elementu embed v případě Safari.

Tomuto nově vytvořenému elementu je pak předán název, který je specifikován v parametru nazvaném id. Tento název opět musí být unikátní, tak jak to vyžaduje DOM a poté je možné s tímto objektem manipulovat pomocí HTML DOM.

Zajištění výchozího vzhledu

V okamžiku, kdy je Silverlight plugin inicializován, je třeba mu předat výchozí hodnoty k určení toho, jak tento plugin bude zobrazen. Těchto vlastností je hned několik a já se pokusím je zde všechny představit.

Vlastnosti height a width budou asi nejčastěji používanými a představují velikost regionu do kterého bude aplikace zobrazena. Tento region je prezentován obdelníkem o výšce a šířce a tyto hodnoty mohou být prezentovány jak v hodnotách pixelů tak i procentním vyjádřením.

V případě, že definujeme nějaký viditelný region, budeme chtít, aby tento měl nějaký výchozí podklad, který je prezentován vlastnosti background. Výchozí hodnotou je hodnota null, která odpovídá bílé barvě. Samozřejmě je jen na vývojáři, jakou barvu zvolí a tu může zapsat jak pomocí hexadecimálního zápisu tak i pomocí pojmenovaných barev. Zajímavou možností je pak nastavení barvy pozadí na transparent, což samozřejmě může dávat zajímavé efekty a Silverlight aplikace bude i nadále viditelná, bude to mít však vliv na samotný výkon obzvláště pak v případě přehrávání videa nebo při náročnějších animacích.

V případě, že zvolíte transparentní barvu, je třeba též vzít v potaz další vlastnost, která je pojmenována isWindowless. Nastavení této vlastnosti určuje, zda obsah zobrazovaný pod Silverlight aplikací bude přes transparentní části aplikace viditelný. Ve výchozím stavu je hodnota nastavena na false a znamená to, že je nad všemi prvky. Po nastavení na hodnotu true je pak aplikován transparentní efekt.

Vhodnou kombinací těchto dvou vlastností pak můžete Silverlight aplikaci do stránky různým způsobem a s různým efektem.

Další vlastnost, kterou můžeme na Silverlight pluginu nastavit je nazvána frameRate a představuje maximální počet frame, které je možné zobrazit za vteřinu. Výchozí hodnotu představuje číslo 60 a je to číslo dostatečné a přesahující možnosti různých médií. V případě, že chcete vědět, jaký je aktuální frame rate, pak je možné toto zjistit pomocí nastavení vlastnosti enableFrameRateCounter na hodnotu true – toto platí pouze pro IE.

Pomalu se dostávám od vizuálních vlastností k těm nevizuáním. Při vývoji asi budete chtít využívat pokud možno poslední verzi Silverlight pluginu, abychom pak zajistili minimální běhové prostředí, měli bychom tuto verzi specifikovat při inicializaci a to pomocí vlastnosti version. Pokud pak uživatel nebude mít příslušnou minimální verzi instalovanou, dostane se mu výzvy k instalaci této minimální verze.

V případě, že již má uživatel nainstalovánu verzi Silverlightu a má povoleno, aby docházelo k aktualilzacím, při požadavku na vyšší veri se mu tato nainstaluje. Samozřejmě jen do doby, než toto v konfiguračním dialogu zakáže. V okamžiku, kdy pak používá systém s UAC, tak bude dotázán na poskytnutí potřebných credentials pro instalaci nové verze.

S instalací pak souvisí i další vlastnost, kterou můžeme nastavit a tou je inplaceInstallPrompt, která při nastavení na hodnotu true dovoluje nainstalovat Silverlight bez toho, aniž by uživatel opustil aktuální stránku.

Jak jistě asi sami dobře víte, ne všichni používají jen ty nejrozšířenější prohlížeče a ne všechny prohlížeče je možné otestovat dokonale a tak by bylo dobré, pokud by existovala nějaká vlastnost, která dovolí určit, že naše aplikace bude hostována jen v takovém prohlížeči, který je podporován a otestován se Silverlightem. Taková vlastnost skutečně existuje a nazývá se ignoreBrowserVer a v případě, že ji nastavíme na hodnotu false, což je také výchozí hodnota, tak se Silverlight spustí jen v podporovaných prohlížečích. V opačném případě bude možné spustit Silverlight aplikaci i v jiném, oficiálně nepodporovaném, prohlížeči.

Dostal jsem se pomalu ke konci výčtu všech vlastností, které je možné nastavit. Poslední vlastnost je nazvaná enableHtmlAccess a specifikuje možnosti, které budeme mít z prostředí manage kódu ve vztahu  k přístupu HTML DOM. Ve výchozím stavu je tento přístup umožněn v případě, že máme Silverlight aplikaci hostovanou na stejné doméně a zakázán v případě, že hostujeme aplikaci na různých doménách tzv. cross domain hosting. Toto nastavení samozřejmě můžeme změnit a nastavit vlastnost na hodnotu true, čímž povolíme přístup k HTML DOM i při hostování aplikace přes domény, byť toto již není považováno za bezpečné.

Závěrem

V dnešním poněkud delším článku jsem se snažil představit všechny možnosti, které jako vývojáři máme při inicializaci a zakomponování Silverlight aplikace do HTML stránky. Téměř vše výše popsané je samozřejmě možné realizovat i prostým zápisem HTML elementů, ale jak je vidět, bez JavaScriptu se i tak v některých případech neobejdeme a tak určitě bude snazší vše definovat na této úrovni.

Výsledný JavaScript tak může vypadat následovně a může sloužit třeba jako šablona pro vaše další projekty, kdy budete chtít vložit Silverlight aplikaci do HTML stránky:

Silverlight.createObjectEx({
source: "ClientBin/MySilverlightApp.xap",
parentElement: document.getElementById("mySilverlightHost"),
id: "mySilverlightControl",
properties: {
height: "100%",
width: "100%",
background: "orange",
isWindowless: "true",
frameRate: "30",
inplaceInstallPrompt: true,
version: "4.0",
ignoreBrowserVer: "true",
enableHtmlAccess: "true"
},
events: {
onLoad:SL_Load,
onError:SL_Error
},
initParams: "klic1=hodnota1, klic2=hodnota2, keyN=159",
context: "6e8a0ae5-2e3c-45ab-95ff-4a2cfc400b8a"
});
function SL_Error(sender, errorArgs)
{
errorType = errorArgs.ErrorType;
if (errorType == "ImageError" || errorType == "MediaError")
return;
alert("Neočekávaná chyba.\r\n" + errorArgs.ErrorMessage);
}
function SL_Load(sender, context, source)
{
alert("Silverlight nahrán!");
}

Příště se již dostanu dále od JavaScriptu, i když ne tak moc daleko, ale již zahrnu do článku XAML kód.