Guide zur Entwicklung von Windows Live Gadgets · Bitte beachten Sie: Dieses Dokument wurde für...

10.07.2006

© Copyright 2006 Microsoft Deutschland GmbH. Alle Rechte vorbehalten. Bitte beachten Sie: Dieses Dokument wurde für MicrosoftGadgets.de erstellt. Dieses Dokument beruht auf die zum Zeitpunkt der Erstellung gegebenen technischen Spezifikationen (z.B. Beta-Stadium des Windows Live Gadget SDKs). Microsoft kann keine Garantie dafür übernehmen, dass alle Angaben zu jeder Zeit vollständig, richtig und aktuell sind. Bitte informieren Sie sich online auf www.microsoftgadgets.de oder www.microsoftgadget.com.

Seite 1 von 18

GUIDE ZUR ENTWICKLUNG VON WINDOWS LIVE GADGETS Dieser Guide beschreibt die ersten Schritte zur Erstellung eines Windows Live Gadgets.

brought to you by MicrosoftGadgets.de

Autor: Axinom GmbH

http://www.microsoftgadgets.de/

10.07.2006


Seite 2 von 18

I. Einleitung Für die Entwicklung von Windows Live Gadgets (im Folgenden nur noch Gadgets genannt) gibt es einige wenige Voraussetzungen.

Dies ist zum einen ein Webserver, der optimalerweise lokal läuft. In diesem Guide beschreiben wir die Entwicklung unter Nutzung des IIS. Es ist jedoch auch mit jedem anderen Webserver möglich, der XML, JavaScript und CSS Dateien ausliefern kann.

Für die Entwicklung kann Notepad oder jeder andere Editor genutzt werden. Für eine höhere Produktivität bietet sich allerdings das Visual Studio 2005 oder Visual Web Developer Express an. Hierfür existiert auch schon eine vorgefertigte Projektvorlage (unter http://microsoftgadgets.com/livesdk/docs/projtemplate.htm).


http://microsoftgadgets.com/livesdk/docs/projtemplate.htm

10.07.2006


Seite 3 von 18

II. Einrichtung der Entwicklungsumgebung Um Gadgets entwickeln zu können, müssen ein paar Vorbereitungen getroffen werden.

Dateisystem An einem beliebigen Ort auf der Festplatte kann ein Verzeichnis angelegt werden, in dem später das G adget abgelegt w ird. D ies kann beispielsw eise „C :\Projects\S am pleG adget“ sein.

Lokalen Webserver einrichten Zur einfacheren Entwicklung und für diese Guide wird ein lokaler IIS Webserver genutzt.

Für diesen Zweck wird ein virtuelles Verzeichnis in der Standardwebseite angelegt. Dies geschieht am einfachsten über die IIS Management Konsole:

Bild 1 Neues Virtuelles Verzeichnis anlagen

Hier muss der Name des Verzeichnisses eingegeben werden, über das der Browser darauf zugreifen kann. Es bietet sich an, denselben Verzeichnisnamen für den IIS und im Dateisystem zu wählen – also „S am pleG adget“. Im nächsten S chritt w ird als Dateisystemverzeichnis das im letzten Schritt angelegte gewählt. Von den Berechtigungen


10.07.2006


Seite 4 von 18

genügt ein Lesezugriff. Falls auch asp oder aspx Seiten ausgeführt werden sollen, muss die O ption „R un S cripts“ m it ausgew ählt sein.

Stellen Sie jetzt sicher, dass Sie mit einem Browser die URL „http://localhost/SampleGadget/“ aufrufen können (es m üsste die M eldung „D irectory Listing denied“ kom m en).

Browser Einstellungen vornehmen In den normalen Sicherheitseinstellungen des Internet Explorers ist es nicht möglich, dass Internetseiten auf den lokalen Webserver Zugriff erhalten. Für die Entwicklung von Gadgets ist dies jedoch für die S eiten „http://*.live.com “ und „http://*.start.com “ nötig. D aher m üssen diese Seiten in die Liste der vertrauenswürdigen Seiten aufgenommen werden:

Bild 2 Sicherheitseinstellungen anpassen

D iese E instellungen sind über „T ools > Internet O ptions“ erreichbar.

Es muss außerdem noch die Sicherheitseinstellung für die Internetzone angepasst werden, damit Datensourcen über Domains hinweg genutzt werden können:


10.07.2006


Seite 5 von 18

Bild 3 Datensourcen über Domains hinweg nutzen

A uch diese E instellung ist über „T ools > Internet Options… “ erreichbar. Dazu muss auf den „S ecurity“ T abulator gew echselt w erden. D ort w ird die Internetzone ausgew ählt und anschließ end auf den B utton „C ustom e Level“ geklickt. In den erscheinenden Sicherheitseinstellungen die oben markierte Einstellung wie dargestellt ändern.

Damit beim Testen immer die aktuellste Version angezeigt wird, sollte das Caching des Internetexplorers deaktiviert werden:


10.07.2006


Seite 6 von 18

Bild 4 Internet Explorer Caching deaktivieren

A uch dieser P unkt kann unter “T ools > Internet O ptions… ” geändert w erden. D azu w ie oben dargestellt im T ab „G eneral“ auf „S ettings… “ klicken und den P unkt „E very visit to the page“ auswählen.

Für den Firefox ist es leider aufgrund von Sicherheitseinschränkungen nicht möglich, Datensourcen vom lokalen Webserver zu nutzen. Das Verhalten und Aussehen der Gadgets im Firefox und anderen Browsern kann nur getestet werden, indem man das Gadgt auf einen externen Webserver kopiert, der im Internet erreichbar ist.


10.07.2006


Seite 7 von 18

III. Anlegen des ersten Gadgets

Notwendige Dateien Ein Gadget besteht aus den folgenden drei Dateien:

Gadget Manifest

Diese XML-Datei beschreibt die Eigenschaften des Gadgets. Hier wird beispielsweise der Titel, die URL zum Gadget Script File sowie die URL zum Gadget Stylesheet hinterlegt.

Gadget Script File

In dieser Datei steht der JavaScript Code, um das Gadget zu erzeugen.

Gadget Style Sheet

Die CSS Style Angaben für das Gadget können in dieser Datei hinterlegt werden. Diese Datei ist optional.

Gadget Manifest Im Gadget Manifest wird das Gadget beschrieben. Für das erste Gadget legen Sie bitte die Datei SampleGadget.xml im Gadget Verzeichnis an. In diese Datei muss das folgende XML eingefügt werden:

<?xml version="1.0"?> <rss version="2.0" xmlns:binding="http://www.live.com"> <channel> <title>Sample Gadget</title> <description>Eine kurze Beschreibung des Gadgets.</description> <language>de-de</language>  <binding:type>Company.Team.Feature.SampleGadget</binding:type> <item>  <link>http://localhost/SampleGadget/SampleGadget.js</link> </item> <item>  <link binding:type="css"> http://localhost/SampleGadget/SampleGadget.css</link> </item> <icons>  <icon height="32" width="32"> http://localhost/SampleGadget/logo.gif</icon> </icons> </channel> </rss>

10.07.2006


Seite 8 von 18

Die einzelnen Punkte betreffen:

title den Titel des Gadgets

description eine kurze Beschreibung

language Sprache als Locale

binding:type Dies ist der vollständige Name der Gadget JavaScript Klasse. Dieses setzt sich im obigen B eispiel aus dem N am ensraum „C om pany.T eam .F eature“ und dem eigentlichen Klassennamen „S am pleG adget“ zusam m en.

Item und link hier wird der Pfad zur JavaScriptDatei bzw. zur optionalen CSS Datei eingegeben. In der JavaS cript D atei m uss die unter „binding:type“ angegebene K lasse definiert sein.

Icons und icon Dieses Icon wird vor dem Titel des Gadgets auf Live.com angezeigt, wenn es in einer Seite eingebunden wurde.


10.07.2006


Seite 9 von 18

Gadget Script File Die Aktionen eines Gadgets sind im Script File in der Sprache JavaScript hinterlegt. Für unser kleines Beispiel sieht die Datei SampleGadget.js folgendermaßen aus. Das folgende XML muss in dieser Datei neben der obigen XML Datei abgelegt werden:

// der Namensraum des Gadgets wird registriert registerNamespace("Company.Team.Feature"); // Konstruktor des Gadgets, wie im Manifest vorgegeben Company.Team.Feature.SampleGadget = function(p_elSource, p_args, p_namespace) { // initializeBase muss vor allem anderen aufgerufen werden Company.Team.Feature.SampleGadget.initializeBase(this, arguments); // private Membervariablen var m_this = this; var m_el = p_elSource; // initialize wird nach Objektinstanziierung aufgerufen this.initialize = function(p_objScope) { // Basis muss immer zuerst initialisiert werden... Company.Team.Feature.SampleGadget.getBaseMethod( this, "initialize", "Web.Bindings.Base").call(this, p_objScope); // ... dann die eigenen Initialisierungen m_el.innerText = "Hello, world!"; } this.dispose = function(p_blnUnload) { // alle events detachen // alle membervariablen auf null setzen m_this = m_el = null; // die Basis dispose Methode muss als letztes aufgerufen werden Company.Team.Feature.SampleGadget.getBaseMethod( this, "dispose", "Web.Bindings.Base").call(this, p_blnUnload); } } Company.Team.Feature.SampleGadget.registerClass( "Company.Team.Feature.SampleGadget", "Web.Bindings.Base");


10.07.2006


Seite 10 von 18

Auch hier folgt eine Beschreibung der wichtigen Teile:

registerNamespace("Company.Team.Feature"); Diese Zeile registriert den Namensraum unseres Gadgets. Dies sollte immer am Anfang der Datei geschehen.

Company.Team.Feature.SampleGadget In dieser Zeile wird der Konstruktor gebildet. Dieser bekommt als Parameter p_elSource das DIV Element, welches den Inhalt des Gadgets bildet, p_args mit einigen Membervariablen und den Namensraum.

this.initialize Hier findet die Initialisierung des Gadgets statt. Sämtlicher Code, der für die Erstellung des Gadgets notwendig ist wird von hier ausgeführt. Im Beispiel oben wird für das Gadget der T ext „H ello, w orld!“ in das D iv geschrieben.

this.dispose Das Gegenteil der initialize Methode. Hier finden die Aufräumarbeiten statt, nachdem ein Gadget nicht mehr angezeigt werden soll. Es ist wichtig, alle Membervariablen auf null zu setzen und alle Events zu detachen, um Speicherlecks im Browser zu vermeiden.

Gadget Style Sheet Diese Datei steuert das Aussehen des eigenen Gadgets. In diesem Beispiel wird die Schriftart und der Innenabstand des Gadgets gesetzt:

.Company_Team_Feature_SampleGadget .main { padding: 5px; font-family: Verdana; }

Der CSS-Klassenname des Gadgets setzt sich aus dem Namespace und dem (JavaScript-) Klassennamen zusammen – die Punkte müssen dabei durch Unterstriche ersetzt werden.

Der obige Inhalt wird für unser Beispiel in der D atei „S am pleG adget.css“ gespeichert und ebenfalls zu den anderen beiden gelegt.

Testen des Gadgets Um sicherzugehen, dass alle oben genannten Schritte erfolgreich waren, testen wir das Gadget jetzt.

T esten S ie, ob die D atei „H elloW orldG adget.xm l“ im Browser aufrufbar ist mit folgender U R L: „http://localhost/SampleGadget/SampleGadget.xml“.

Wenn die Datei im Browser sichtbar ist, rufen S ie die S eite „http://www.live.com/“ auf. S ollte dies Ihr erster Besuch sein, können Sie die Seite mit dem rechten Button anpassen (Stand


http://localhost/SampleGadget/SampleGadget.xml

http://www.live.com/

10.07.2006


Seite 11 von 18

28. Juli 2006). A nschließ end können S ie über „Inhalte hinzufügen“ und „E rw eiterte O ptionen“ das SampleGadget hinzufügen. Dazu kopieren Sie bitte die URL „http://localhost/SampleGadget/SampleGadget.xml“ in das zw eite F eld und klicken S ie auf „abonnieren“. W enn der S chritt erfolgreich w ar, müssen Sie das Einbinden gegebenenfalls noch bestätigen und sehen anschließ end den T ext „H ello , world!“.


http://localhost/SampleGadget/SampleGadget.xml

10.07.2006


Seite 12 von 18

IV. Gadgetentwicklung Nachdem das erste Gadget jetzt erfolgreich eingerichtet wurde, könnte – zumindest nach einer Weile – der T ext „H ello, w orld!“ doch anfangen langw eilig zu w erden.

Daher werden in diesem Abschnitte Möglichkeiten vorgestellt, um ein Gadget mit Inhalten unterschiedlicher Art zu befüllen.

Inhalt direkt einfügen Diese Art, Inhalt einzufügen haben Sie bereits im obigen Beispiel kennen gelernt:

m_el.innerText = "Hello, world!";

Dies beschränkt sich nicht nur auf reinen Text. So ist es auch möglich, HTML Inhalte einzubinden (Achtung: es wird nicht wie vorher das Attribut innerText sondern innerHTML gesetzt!):

m_el.innerHTML = "Das ist unser <b>SampleGadget Logo</b>: <img src=\"logo.gif\" alt=\"SampleGadget Logo\" />";

Eine externe Seite einbetten Eine weitere Möglichkeit ist es, eine dynamische Seite komplett innerhalb eines IFrames in das Gadget einzubinden.

var url = "http://localhost/SampleGadget/SampleGadgetPage.aspx"; m_el.innerHTML = "<iframe src=\"" + url + "\" frameborder=\"0\" scrolling=\"no\" />"

Ein Beispiel ist das MSDN Webcast Finder Windows Live Gadget, welches unter www.microsoftgadgets.de heruntergeladen werden kann. Dort wurde mittels ASP.NET eine Webseite entwickelt, um nach MSDN Webcasts suchen und filtern zu können. Dies ist beispielsweise bei größeren Datenmengen ratsam. Die zugrunde liegende XML-Datei ist in diesem Falle knapp ein Megabyte groß.). Damit muss nicht jeder Client die kompletten Daten herunterladen und parsen.

Inhalte aus einer XML-Datei einfügen Im obigen Punkt wurde ein Beispiel gezeigt, um XML-Dateien auf dem Server zu parsen und daraus eine komplette Webseite darzustellen. Dies kann (vorzugsweise bei kleineren XML-Dateien) auch im Client mittels JavaScript durchgeführt werden.



10.07.2006


Seite 13 von 18

Beispiel XML-Datei:

<?xml version="1.0" encoding="utf-8"?> <items> <item show="true">a</item> <item show="true">b</item> <item show="false">c</item> <item show="false">d</item> <item show="true">e</item> <item show="false">f</item> </items>

Auslesen der anzuzeigenden Elemente und ausgeben als HTML-Liste:

this.initialize = function(p_objScope) { Company.Team.Feature.SampleGadget.getBaseMethod( this, "initialize", "Web.Bindings.Base").call(this, p_objScope); function OnDownloadComplete(response) { if (response.status == 200) { if (response.responseXML) { p_elSource.innerHTML = "<ul>"; // query the xml file with an xpath expression var htmlNodes = response.responseXML.selectNodes("items/item[@show='true']"); for (var i = 0; i < htmlNodes.length; i++) { // get inner text of the item node and show it in an li-tag p_elSource.innerHTML += "<li>" + htmlNodes[i].text + "</li>"; } p_elSource.innerHTML += "</ul>"; } } } // download the xml file asynchronous var req = Web.Network.createRequest( Web.Network.Type.XML, "http://localhost/SampleGadget/items.xml", {proxy:"generic", numItems:5}, OnDownloadComplete); req.execute(); }

D ieses B eispiel ist schon etw as kom plexer. M it „W eb.N etw ork.createR equest” erzeugen w ir einen asynchronen Request, um die XML-Datei herunter zu laden.


10.07.2006


Seite 14 von 18

Dazu wird

der Typ der Ressource (Web.Network.Type.XML

Die URL zur XML-Datei

Optional: Ein Objekt welches an die Callback Methode nach übergeben wird, nachdem der Download beendet wurde.

Optional: Eine Methode, die nach dem Download der XML-Datei aufgerufen wird – in diesem F all „O nD ow nloadC om plete“.

Eine genaue Dokumentation zu createRequest befindet sich hier: http://microsoftgadgets.com/livesdk/docs/ApiRef.Web.Network.htm

Kurzer Exkurs:

Natürlich muss die zu downloadende XML-Datei nicht statisch sein. Es kann natürlich auch eine ASP.NET Seite (oder andere dynamische Webseite) aufgerufen werden, die eine XML-Datei erzeugt. Beim Request der XML-Datei können an die URL natürlich dann geeignete Parameter mit übergeben werden. Daher wäre beim vorangehenden Beispiel mit dem MSDN Webcast Finder eine Kombination aus Client-JavaScript und serverseitigen Webservices möglich. Der Client könnte mittels Webservice Aufrufen die Dropdownboxen mit allen Presentern, Technologiebereichen, Typen usw. befüllen. Bei einer Suche würde dann das Gadget dann eine Anfrage an den Webservice stellen und die gewählten Filter und Suchbegriffe übergeben. Zurückgegeben würden dann von den gefundenen Einträgen nur die zur Darstellung benötigten Felder als XML.

Nachdem der Download beendet wurde, wird – wie beim Erzeugen des Requests angegeben – die M ethode „O nD ow nloadC om plete“ aufgerufen. D arin w ird zuerst überprüft, ob der Download erfolgreich war (HTTP Statuscode 200) und ob es sich auch tatsächlich um XML handelt und nicht um eine Fehlermeldung oder ähnliches.

Dann werden mittels eines XPath Ausdrucks alle Item-Nodes geladen, die ein Attribut „show “ besitzen, w elches den W ert „true“ besitzt. D iese herausgesuchten N odes w erden anschließend in einer Schleife durchlaufen und als Liste ausgegeben.

Inhalte dynamisch einfügen In den vorangegangenen Beispielen wurde der auszugebende HTML Inhalt stets an das Ende des Wurzelelement (p_elSource) als Text angefügt. Inhalte können jedoch auch dynamisch mit JavaScript in den DOM-Baum (Document Object Model – Baum) - also an bestimmten Stellen in der HTML-Seitenstruktur - eingefügt werden:

// search label var elSpan = document.createElement("span"); elSpan.innerText = "Suchen nach: "; // input field - and attach events elSearch = document.createElement("input"); elSearch.attachEvent("onkeypress", DoReturn);


http://microsoftgadgets.com/livesdk/docs/ApiRef.Web.Network.htm

10.07.2006


Seite 15 von 18

// commercial content elCommercialCheckBox = document.createElement("input"); elCommercialCheckBox.id = "commercialCheckbox"; elCommercialCheckBox.type = "checkbox"; elCommercialCheckBox.checked = false; var contentLabel = document.createElement("span"); contentLabel.innerHTML = "kommerzielle/kostenpflichtige Inhalte zulassen"; contentLabel.style.whiteSpace = "nowrap"; contentLabel.style.paddingRight = "5px"; // submit button var submitButton = document.createElement("input"); submitButton.id = "submitButton"; submitButton.type = "submit"; submitButton.value = "Suchen"; submitButton.text = "Suchen"; submitButton.attachEvent("onclick", DoSearch); // add now the created elements under the root div element p_elSource.appendChild(elSpan); p_elSource.appendChild(document.createElement("br")); p_elSource.appendChild(elSearch); p_elSource.appendChild(submitButton); p_elSource.appendChild(document.createElement("br")); p_elSource.appendChild(elCommercialCheckBox); // define the search method: function DoSearch() { /* your code goes here */ }

In diesem B eispiel w erden über „docum ent.createE lem ent“ einzelne Html-Objekte erzeugt und deren Properties gesetzt und Methoden genutzt. Dem Suchbutton wird über „subm itB utton.attachE vent("onclick", D oS earch);” ein O nC lick -Event registriert. Bei einem K lick w ird dann die M ethode „D oS earch“ aufgerufen, w elche die eigentliche Suche durchführt.

Der oben abgebildete Code ist (leicht modifiziert) aus dem Codezone.de Windows Live Gadget 2.0 entnommen, welches ebenfalls unter www.microsoftgadgets.de herunter geladen werden kann. Das Codezone.de Gadget nutzt dabei die oben dargestellte Möglichkeit, HTML im Gadget zu erzeugen. Die Anzeige der gefundenen Ergebnisse geschieht durch eine ASP.NET Seite, die dynamisch in einen IFrame im Gadget eingebunden wird.

Weitere Möglichkeiten Es existieren noch viele weitere Möglichkeiten, mit JavaScript alleine bzw. mit JavaScript in Zusammenarbeit mit dynamischen Serveraufrufen (z.B. ASP.NET aber auch ASP, PHP, Java uvm.) ein Gadget zu entwickeln.

Es existieren beispielsweise RSS-Reader (siehe http://siteexperts.spaces.msn.com/blog/cns!CE6C50D25BFAAA73!1958.entry), und viele weitere Möglichkeiten.



http://siteexperts.spaces.msn.com/blog/cns!CE6C50D25BFAAA73!1958.entry

10.07.2006


Seite 16 von 18

V. Tipps und Hinweise Ein paar Tipps, die Kopfzerbrechen ersparen können:

Wenn es bei Ihrem Gadget Probleme mit der Größe gibt und Scrollbalken erscheinen, Teile abgeschnitten werden, dann rufen Sie nach dem Initialize und jeder Methode, welche die HTML Ausgabe beeinflusst die folgende Zeile am Ende auf: p_args.module.Resize();

Wenn das Gadget die Änderungen nicht übernommen hat, dann überprüfen Sie bitte, ob Sie für das Gadgetverzeichnis und Ihren Browser alle Schritte aus dem Kapitel „E inrichtung der E ntw icklungsum gebung“ durchgeführt haben (vor allem Browsercache und IIS Einstellung).

Bei größeren Gadgets, die auch häufiger auf einen Produktiven (oder Test-/Staging-) Server freigeschaltet werden, sollten Sie einen Release-Prozess einführen. Wichtig dabei sind vor allem die Verzeichnisse auch mit anzupassen von localhost auf IhreDomain.com


10.07.2006


Seite 17 von 18

VI. Deployment Das Gadget kann wie jede normale Webseite deployt - also auf einem produktiven Webserver eingerichtet werden. Dazu genügt es, im Visual Studio mit der rechten Maustaste im Solution Explorer auf das Website P rojekt zu klicken und „P ublish W ebsite“ auszuw ählen.

Dort den FTP, HTTP, lokalen oder entfernen Pfad eingeben, die gewünschten Optionen auswählen und OK zu drücken:

Bild 5 Gadget deployen


10.07.2006


Seite 18 von 18

Es ist allerdings sehr wichtig, darauf zu achten, dass alle Pfade angepasst werden. Dies betrifft mindestens bzw. meist:

Gadget Manifest:

o Den Pfad zur Gadget JavaScript-Datei

o Den Pfad zur zum Gadget Style Sheet

o Gegebenenfalls den Pfad zum Gadget Logo

Gadget JavaScript-Datei:

o Falls IFrames eingesetzt werden, die eine andere Domain framen, muss die korrekte URL gesetzt werden.

o Falls Bilder oder externe Ressourcen über absolute URLs angesprochen werden müssen diese geändert werden (sollte aber nur in Ausnahmefällen nötig sein).

Gadget Style Sheet:

o Dort sollten normal keine Änderungen erforderlich sein. Nur in wenigen Fällen dürfte es nötig sein, Styles bzw. Bilder von anderen Domains laden zu müssen.

Nach dem Deployment sollte das Gadget in den bekanntesten und meistgenutzten Browsern getestet werden. Wir wünschen viel Erfolg bei der Erstellung Ihres ersten Gadgets! Weitere Informationen finden Sie auch auf http://www.MicrosoftGadgets.de/

VII. Über den Autor:

Dieses Dokument wurde mit freundlicher Unterstützung der Axinom GmbH erstellt. Axinom hat sich zum Ziel gesetzt, seinen Kunden den Einstieg in die Welt der Microsoft Unternehmensplattform zu erleichtern und sie bei der Umsetzung und Pflege innovativer Lösungen auf Basis der Microsoft .NET Technologie zu unterstützen. Dabei bietet Axinom seinen Kunden sowohl Beratung und Unterstützung bei der Umstellung ihrer vorhandenen Systeme auf die zukunftsweisende .NET Technologie als auch die komplette Neuentwicklung und Betrieb kundenindividueller IT-Lösungen. Weitere Informationen: http://www.axinom.de/



http://www.axinom.de/

Guide zur Entwicklung von Windows Live Gadgets · Bitte beachten Sie: Dieses Dokument wurde für...

Documents

Transcript of Guide zur Entwicklung von Windows Live Gadgets · Bitte beachten Sie: Dieses Dokument wurde für...