FunTrackers Easter Special 2016 - Finished! » View News


Post Reply 
 
Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
[DE] ManiaPlanet ManiaLinks
» Das große Tutorial für alle Neulinge und Umsteiger von Forever
Author Message
Marcel Offline
ここにはコードがありません。
********
ClanLeader

Posts: 695
Joined: Aug 2007
Reputation: 22
Post: #1
[DE] ManiaPlanet ManiaLinks
Das große Tutorial für alle Neulinge und Umsteiger von Forever

ManiaLinks – Kleine Websiten, die direkt aus dem Spiel aufgerufen werden können. Wenn du schon immer mal einen eigenen ManiaLink erstellen wolltest, bist du am exakt richtigen Ort: Dieses Tutorial wird dich in die ManiaLinks und deren Erstellung einführen. Du kennst bereits die ManiaLinks von TrackMania Forever, und willst dein Wissen auf den neuesten Stand bringen? Auch dann wird dir dieses Tutorial weiterhelfen.

Dieses Tutorial besteht aus fünf weitestgehend unabhängigen Teilen, jeweils zu einem bestimmten Thema über die ManiaLinks. Der erste Teil ist für alle Neueinsteiger, die zuvor noch nie von ManiaLinks und deren Erstellung gehört haben, und bietet einen Einstieg beginnend bei grundlegensten Dingen wie XML über notwendiges Grundwissen, was für die Erstellung eines ManiaLinks benötigt wird. Wenn du bereits in TrackMania Forever gelernt hast, einen ManiaLink zu erstellen, starte mit dem zweiten Teil des Tutorials, welcher die Unterschiede zwischen TrackMania Forever und ManiaPlanet erklären wird. Der dritte Teil des Tutorials beinhaltet eine vollständige Referenz über alle Elemente, die in einem ManiaLink verwendet werden können, inklusive einer Auflistung aller Attribute zu jedem Element, und detaillierten Beschreibungen zu diesen. Der vierte Teil richtet sich an Experten, die bereits einige ManiaLinks erstellt haben, und nun die Elemente des ManiaLinks mit der ManiaScript-Sprache manipulieren wollen. Der fünfte und letzte Teil des Tutorials behandelt verschiedene Aspekte von ManiaLinks, welche für den ein oder anderen wichtig sein könnten, allerdings meistens schon fortgeschrittenes Wissen benötigen. Dieser letzte Teil kann als Sammlung all jener Themen gesehen werden, die nicht in die anderen Teile gepasst haben.

Obwohl sich die ManiaLinks in ManiaPlanet weitesgehend nicht von denen aus TrackMania Forever unterscheiden, bedarf es manchmal einer Unterscheidung zwischen den Versionen der ManiaLinks. Ich werde die Versionen dabei anhand der Spiele benennen, in denen sie ein geführt wurden, so bezeichnen die ManiaPlanet ManiaLinks eben jene ManiaLinks aus ManiaPlanet, während die Forever ManiaLink diejenigen aus TrackMania Forever benennen. Zusätzlich sind mit United ManiaLinks die allerersten ManiaLinks aus TrackMania United gemeint, deren Struktur sich grundlegend von der mitlerweile bekannten und der im Tutorial behandelten unterscheiden – Du brauchst diese nicht zu kennen, diese sind nur der Vollständigkeit halber mit aufgeführt Wink2

Übersicht über das Tutorial
    Teil 1: Einführung in die ManiaPlanet ManiaLinks
    Vom tiefsten Basiswissen zu den letzten Details der internen Mechanismen Teil 2: Unterschiede zu den Forever ManiaLinks
    Jedes Detail, was sich mit dem ManiaPlanet Upgrade geändert hat Teil 3: ManiaLink Elemente
    Eine vollständige Referenz von allen Elementen
    • <manialink>Wurzelknoten
    • <timeout>Deaktiviert das Cachen von ManiaLinks
    • <frame>Gruppiert Elemente
    • <format>Definiert Standard-Formatierungen
    • <quad>Zeigt Bilder und Formen
    • <label>Zeigt Texte und Buttons
    • <audio>Spielt eine Musik-Datei (mit Buttons)
    • <music>Spielt eine Musik-Datei (ohne Buttons)
    • <include>Importiert eine weitere XML-Datei
    • <entry>Einfaches Eingabefeld
    • <fileentry>Eingabefeld für Dateien
    • <dico>Macht den ManiaLink mehrsprachig
    • <script>Integriert ein ManiaScript
    Teil 4: ManiaScript in ManiaLinks
    Manipulation eines ManiaLinks mit ManiaScript Teil 5: Tipps & Tricks
    Ausgewählte Wissenswerte Themen

    © 2011-2012 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 06.02.2012 16:41 by Marcel.)
    21.09.2011 11:32
    Visit this user's website Find all posts by this user Quote this message in a reply
    Marcel Offline
    ここにはコードがありません。
    ********
    ClanLeader

    Posts: 695
    Joined: Aug 2007
    Reputation: 22
    Post: #2
    Teil 1: Einführung in die ManiaPlanet ManiaLinks
    Vom tiefsten Basiswissen zu den letzten Details der internen Mechanismen

    Das erste Kapitel des Tutorials wird sich mit den Grundlagen der ManiaLinks beschäftigen. Wenn du niemals zuvor einen eigenen ManiaLink geschrieben hast, ist dies der richtige Punkt zum Loslegen. Dieses Kapitel startet mit einem kurzen Crashkurs in die XML-Syntax, auf welcher die ManiaLinks basieren und somit notwendig ist, um einen ManiaLink zu erstellen. Anschließend werden die eigentlichen Grundlagen der ManiaLinks behandelt, um exakter zu sein die Positionierungssysteme, welches benötigt wird, um irgendein Element anzuzeigen.

    Falls du deinen ManiaLink für alle veröffentlichen willst, hilft dir der letzte Abschnitt dieses Kapitels mit der Registrierung eines Codes für deinen ManiaLink, sodass sich die anderen nicht die vollständige URL merken brauchen. Das einzige, was dieses Kapitel nicht erklärt und somit als Vorwissen voraussetzt, ist das eigentliche Hochladen von Dateien auf einen Webspave, um diese für andere verfügbar zu machen.

    Crashkurs in XML-Dateien und deren Syntax

    ManiaLinks verwenden den XML-Standard, um die Elemente zu definieren, die beim Aufruf angezeigt werden sollen. Wenn du bereits mit HTML vertraut bist, kennst du bereits wichtige Grundlagen von XML und somit von ManiaLinks, allerdings gibt es kleine Unterschiede zwischen HTML und dem strengerem XML.

    Was ist nunn eigentlich dieses XML? Die drei Buchstaben stehen für eXtensible Markup Language, und ist eine allgemeine Syntax zum Beschreiben von verschiedensten Dokumenten. Obwohl XML standardisiert ist, setzt es keine Einschränkungen auf die tatsächlich eingesetzten Elemente: Die Anwendung kann selbst entscheiden, welche Elemente benötigt werden, und was sie am Ende darstellen sollen. In diesem Abschnitt des Tutorials werde ich nur auf die Features von XML eingehen, die im Kontext der ManiaLinks wirklich gebraucht werden.

    Hallo Welt: Deine erste ManiaLink-Datei
    Eine XML-Datei ist einfach eine Textdatei, die meistens mit .xml endet, um anzuzeigen, dass es sich um XML handelt. Das bedeutet, dass you jeden beliebigen Texteditor nutzen kannst, um eine XML-Datei zu erstellen, nichtsdestotrotz ist es speziell für Neulinge hilfreich, einen Editor mit Syntax Highlighting zu nutzen, da dieses Feature die meisten Syntax-Fehler direkt durch falsche Farbformatierungen des folgenden Codes offenbaren. Ich selbst empfehle die Verwendung von Notepad++, einem schlanken Editor mit Syntax-Highlighting für zahlreiche Sprachen. Im folgenden werde ich annehmen, dass Notepad++ verwendet wird, allerdings sollten alle Schritte auch problemlos auf andere Editoren anwendbar sein.

    Nach dem Installieren und Öffnen von Notepad++, wähle im Sprachen-Menü den Eintrag XML aus, um die korrekte Hervorhebung des Codes zu aktivieren. Danach, gib folgendes ein:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <label text="Hallo Welt!" />
    </manialink>
    Bevor wir nun die Datei speichern, müssen wir sicherstellen, dass wir die korrekte Kodierung verwenden. Dies ist wichtig, sobald du irgendwelche Sonderzeichen wie Umlaute verwendest, da diese nicht korrekt auf dem ManiaLink angezeigt werden können, wenn die Datei falsch kodiert ist. Öffne hierfür in Notepad++ das Kodierung-Menü, und überprüfe die aktuelle Kodierung der Datei (sprich welcher Eintrag markiert ist): Wenn es nicht UTF-8 ohne BOM ist, verwende die Option Konvertiere zu UTF-8 ohne BOM etwas weiter unten im Menü um die Kodierung zu ändern. Überprüfe die Kodierung nochmal, um auf der sicheren Seite zu sein Wink2

    Wenn du die Datei nun speicherst, musst du darauf achten, sie wirklich als XML-Datei (also mit der Endung .xml) zu speichern, da Notepad++ dann automatisch erkennen wird, dass es sich um XML handelt, und dafür das entsprechende Highlighting auswählt. Um dies zu erreichen, kannst du entweder die Dateiendung direkt mit ins Eingabefeld für den Dateinamen mit eingeben, oder aus der Auswahlliste den Dateityp eXtensible Markup Language auswählen. Für die aktuellen Fall, gib einfach helloworld.xml als Dateinamen ein und speichere die Datei in den Ordner ManiaPlanet\Media\Manialinks\ in deinen Dokumenten.

    Gehe nun in ManiaPlanet und gib in die Adresszeile, die erscheint wenn du die Maus an den oberen Rand des Spiels bewegst, die Adresse file://Media/Manialinks/helloworld.xml ein. Wenn du nun ein weißes Hallo Welt! auf einem grauen Hintergrund siehst, hast du erfolgreich deinen ersten ManiaLink erstellt Biggrin (Falls du den ManiaLink-Browser wieder schließen willst, klicke entweder auf das linkeste Symbol in der Leiste oder drücke die Esc Taste Wink2 )

    Hinweis: Die file://-Methode zum Aufrufen von ManiaLinks funktioniert lokal auf deinem Rechner: Niemand sonst ist in der Lage, diesen ManiaLink aktuell aufzurufen. Wenn du die Datei auf einen Webspace hochlädst, kannst du die Datei wie bei Websites über ihre URL aufrufen. Bevor wir lernen, wie wir einen Code für einen ManiaLink registrieren, soll erstmal erklärt werden, wie XML im Detail funktioniert Wink2

    Ein genauerer Blick auf die Syntax: Der XML-Header
    Wenn du auf das Beispiel von oben schaust, siehst du in der ersten Zeile den sogenannten XML-Header. Dieser Header steht immer am Anfang einer XML-Datei, und sagt der Anwendung, dass es sich wirklich um XML handelt. Die einzelnen Werte des headers können als kleine Konfiguration der XML-Datei gesehen werden.

    Diese Zeile wird sich wohl niemals ändern, sodass du dir entweder die konkreten Werte einprägst, oder Copy&Paste sie in jede neue XML-Datei, die du erstellst Wink2 Der Grund ist recht naheliegend: Aktuell gibt es keine andere Version von XML als 1.0, das Verwenden von UTF-8 als Kodierung ist die beste Wahl, um einen ManiaLink kompatibel zu allen Sprachen zu machen, und was genau ein Standalone-Tag ist, werden wir später erfahren.

    Hinweis: Es ist sehr wichtig, dass das allererste Zeichen der Datei das < des XML-Headers ist. Es ist weder erlaubt, Leerzeichen oder Zeilenumbrüche, noch irgendwelche anderen Zeichen vor den XML-Header zu schreiben.

    Das Öffnen und Schließen von Tags
    Was ist nun mit den anderen drei Zeilen aus dem Beispiel? Diese bilden die eigentliche XML-Datei, und beschreiben unseren ManiaLink, wie er von ManiaPlanet dargestellt werden soll. Nun sehen wir die sogenannten Tags: Diese starten immer mit einer öffnenden spitzen Klammer < und enden mit einer schließenden <, und alles dazwischen gehört zu diesem Tag. (Bei dem Wort Tag handelt es sich im Kontext von XML um ein englisches Wort, also bitte auch englisch aussprechen... Wochentage interessieren uns aktuell nicht Ugly ) Mindestens der Name des Tags muss jeweils mit angegeben werden, entsprechend haben wir in unserem Beispiel zwei manialink-Tags und einen label-Tag.

    Wie du vielleicht schon siehst, gibt es drei verschiedene Typen von Tags: Ein öffnender Tag enthält keinen Slash /, und kommt auch niemals alleine. Immer wenn du einen öffnenden Tag hast, lässt sich zu diesem der dazugehörige schließende Tag finden, zu erkennen am gleichen Namen und an dem führenden / vor dem Namen, wie es im zweiten manialink-Tag der Fall ist.

    Zusätzlich kann ein öffnender Tag sogenannte Attribute besitzen, die entweder als name="value" oder als name='value' angegeben werden. Ob du nun einfache oder doppelte Anführungszeichen nimmst, ist weitestgehend egal, intern gibt es keinerlei Unterschiede zwischen ihnen. Zurück zu unserem Beispiel können wir erkennen, dass der öffnende manialink-Tag ein Attribut namens version besitzt, dessen Wert auf 1 gesetzt ist. Der label-Tag hat ebenfalls ein Attribut, hier ist es als text benannt und sein Wert ist Hallo Welt!, welches wir bereits in ManiaPlanet gesehen haben. Öffnende Tags können mehrere Attribute haben, soe können aber auch keine haben. Schließende Tags hingegen haben niemals Attribute.

    Der dritte Typ von Tags ist eher eine Kurform anstatt ein wirklich neuer Typ. Schau auf den label-Tag im Beispiel: Dieser hat den Slash / am Ende des Tags, und wird deshalb als Standalone-Tag bezeichnet. Er ist einfach eine kürzere Schreibweise von <label text="Hallo Welt!"></label> und kann immer genutzt werden, wenn zwischen dem öffnenden und schließenden Tag nichts steht.

    Ein öffnender und der dazugehörige schließender Tag formen, zusammen mit allem was zwischen ihnen steht, einen sogenannten Knoten oder englisch Node des XML-Dokuments. Ein Knoten startet immer mit einem öffnenden Tag und endet immer mit einem schließenden Tag mit demselben Namen, alles zwischen diesen Tags wird als Inhalr oder englisch Content des Knotens bezeichnet. (Im Falle eines Standalone-Tags bildet dieser alleine logischwerweise den gesamten Knoten.) Der Inhalt eines Knotens kann nun entweder einfacher Text sein, oder, was wir fast immer in ManiaLinks sehen werden, weitere Knoten, also weitere öffnende und schließende Tags. Dabei ist es wichtig, dass ein Knoten immer vollständig in einem anderen Knoten enthalten ist, wobei der äußere Knoten dann Elternknoten oder Parent Node und der innere Knoten Kindknoten oder Child Node genannt wird. Zurück zu unserem Beispiel haben wir also den label-Knoten als Kind des manialink-Knotens. Der label-Knoten selbst hat keinen Inhalt mehr, weshalb es uns möglich war, die kürzere Schreibweise als Standalone-Tag zu nutzen.

    Spezielle Tags: Wurzelknoten, Kommentare Und erneut der XML-Header
    Der manialink-Knoten ist nun ein spezieller Knoten: Dieser hat keinen Elternknoten, und wird deshalb Wurzelknoten oder Root Node genannt. Ein gültiges XML-Dokument muss immer exakt einen Wurzelknoten besitzen, welcher dann die gesamten Daten des Dokuments enthält, und somit auch als Dokument-Knoten oder Document Node bezeichnet wird. In ManiaLinks ist der Wurzelknoten stets ein <manialink>.

    Eine weitere Art von speziellen Knoten sind die Kommentarknoten oder Comment Nodes. Diese können immer dorthin platziert werden, wo auch andere Knoten platziert werden können, also achte darauf, dass sie weder außerhalb des Wurzelknotens noch innerhalb eines Tags, beispielsweise zwischen die Attribute, gesetzt wird. Wie der Name bereits sagt, können mit ihnen zusätzliche Kommentare in das XML-Dokument eingebaut werden, um etwa zu sagen, welche Rolle ein bestimmter Teil des Dokuments auf dem fertigen ManiaLink spielt. Diese Kommentare werden von den XML-Parsern per Definition ignoriert. Die Syntax von Kommentaren ist leicht anders als von den übrigen Tags:
    Code:
    <!-- Das ist ein Kommentar -->
    Wie zu sehen ist, startet ein Kommentar mit einem < für einen Tag, gefolgt von einem Ausrufezeichen und exakt zwei Bindestrichen, und endet erneut mit exakt zwei Bindestrichen und einem schließenden >.

    Hinweis: Du kannst jedes Zeichen innerhalb eines Kommentars verwenden, das du willst. Es gibt nur eine Ausnahme: Es ist nicht erlaubt, -- innerhalb eines Kommentars zu schreiben, weil dieses das Ende des Kommentars kennzeichnet und enstprechend das abschließende > folgen muss. Was auch immer du als Kommentar schreibst, schreibe niemals -- Wink2

    Der letzte spezielle Tag ist der XML-Header, welcher immer der allererste Tag in einer XML-Datei ist und die einzige Ausnahme, die außerhalb des Wurzelknotens steht.

    Spezielle Zeichen und deren Behandlung
    Wann immer Zeichen eine Syntax definieren, hat man stets das Problem, wenn man eben diese Zeichen selbst ausgeben will. Dies ist natürlich auch bei XML der Fall: Wenn eine spitze Klammer oder ein Anführungszeichen ausgegeben werden soll, könnte dies die Syntax des Dokuments stören, und die gesamte Datei ungültig machen. Logischerweise gibt es einen Weg, diese Zeichen unscharf zu machen, sodass sie die Syntax nicht mehr stören können, das sogenannte escapen von Zeichen. Insgesamt gibt es fünf Zeichen, die von diesem Problem betroffen sind:
    • < wird zu &lt; wie in "Lower Than" – Escape außerhalb von Tags.
    • > wird zu &gt; wie in "Greater Than" – Escape außerhalb von Tags.
    • " wird zu &quot; wie in "QUOTe" – Escape in Attributen mit doppelten Anführungszeichen.
    • ' wird zu &apos; wie in "APOStrophe" – Escape in Attributen mit einfachen Anführungszeichen.
    • & wird zu &amp; wie in "AMPersand" – Escape immer.
    Es ist zu erkennen, dass eine Escape-Sequenz ' immer mit einem Und-Zeichen & (was dieses Zeichen selbst zu einem sehr gefährlichen macht Biggrin ), gefolgt von einem Bezeichner und einem abschließenden Semikolon ;. Der Bezeichner leitet sich von den englischen Namen der Zeichen ab, so heißt das & beispielsweise im Englischen Ampersand Wink2 Diese fünf Zeichen können stets ersetzt werden, wenn sie nicht Teil der XML-Syntax sein sollen, sie müssen aber stets an den Orten ersetzt werden, wie oben genannt. Kommentare sind hiervon ausgenommen: In ihnen müssen keine Zeichen behandelt werden, da der gesamte Kommentar einfach ignoriert wird.

    Hinweis: Falls du PHP verwendest, um einen ManiaLink zu generieren, stelle sicher, dass Benutzereingaben stets behandelt werden, um die genannten Zeichen zu escapen! Ansonsten könnte ein " oder ' den ManiaLink ungültig und somit für andere nicht mehr verfügbar machen. Achtung: Wenn du einfache Anführungszeichen für die Attribute-Werte verwendest, achte auf die korrekte Verwendung von htmlspecialchars(), um auch wirklich die ' zu escapen, das heißt es muss die folgende Anweisung verwendet werden:
    PHP Code:
    $escapedText htmlspecialchars($textToBeEscapedENT_QUOTES'UTF-8'); 

    Kleiner Test: Finde die Fehler
    Was denkst du: Bist du bereits in der Lage, eine gültige XML-Datei zu schreiben? Wie wäre es mit einem kleinen Test: Der folgende Code zeigt eine ungültige XML-Datei. Kannst du alle Fehler finden, dei in dieser Datei gemacht wurden?

    Invalid XML file:
    Code:
    <root>
        <!-- Dies ist ein Negativ-Beispiel für XML -- Kein copy&paste! -->
        <kind1><kind2>Etwas Inhalt</kind1></kind2>
        <input type="checkbox" checked>
        <label link="http://www.example.org/?param1=value1&param2=value2" />
    </root>
    <standalone />
    Spoiler: Fehler in der XML-Datei » Show

    Hinweis: Wenn du die Korrektheit einer XML-Datei überprüfen willst, kannst du diese einfach in einem normalen Browser wie Firefox oder Chrome öffnen. (Nutzt nicht den Internet Explorer hierfür, da dieser partout nicht die Syntax überprüfen will ^^) Solange der Browser die Datei als XML-Datei erkennt, wird er versuchen, diese als solche einzulesen und den Dokument-Baum darzustellen. Wenn die Datei nun einen Fehler enthält, so wird der Browser logischerweise über diesen stolpern, und wird die Stelle der Datei ausgeben, wo die Syntax nicht mehr gepasst hat.




    Grundlegende Positionierung von ManiaLink-Elementen

    Bevor wir endlich zu den einzelnen Elementen eines ManiaLinks kommen, brauchen wir noch eine Portion weiteres Grundwissen: Das Positionierungssystem. Alle sichtbaren Elemente können weitestgehend frei auf dem Bildschirm platziert werden, ohne sich über die anderen Elemente Gedanken machen zu müssen. Aber ohne dieses System zu kennen, wird es schwer, überhaupt irgendetwas anzuzeigen.

    Doppelt hält besser: Die zwei Positionierungssysteme
    Grundlegend haben wir ein vollständiges, dreidimensionales Koordinatensystem, mit der X-Achse zum Bewegen eines Elementes nach links oder rechts, der Y-Achse zum Bewegen nach oben und unten, und weil sich die Elemente überlappen können, eine Z-Achse, um ein Element in den Vordergund oder in den Hintergrund zu setzen. Um die Dinge etwas komplizierter zu machen, hast du nun die Wahl zwischen zwei verschiedenen Koordinatensystemen: Beide sind gleich mächtig, und du hast keinerlei Nachteile mit dem einen gegenüber dem anderem, die einzigen Unterschiede liegen in den exakten Werten der einzelnen Achsen, und in welche Richtung diese orientiert sind. Schau dir die folgenden Bilder an, um die Unterschiede zu sehen:
    [Image: classic.de.png][Image: menu.de.png]

    Wie du vielleicht schon erkannt hast, ist das Konvertieren zwischen den Systemen relativ einfach: Es müssen lediglich die Werte durch 100 dividiert oder mit 100 multipliziert werden, unter Beachtung der umgekehrten Ausrichtung der X- und Z-Achse. Dennoch wird empfohlen, sich für ein Koordinatensystem zu entscheiden und dieses für den gesamten ManiaLink zu nutzen.

    Mit Ausnahme der Werte ist der sonstige Unterschied zwischen den beiden Systemen sehr gering: Wenn du die Klassische Positionierung nutzen willst, verwende die Attribute pos und size, im Falle der Menü-Positionierung muss ein zusätzliches n angehangen werden, um die Attribute posn und sizen zu bekommen. Wann immer ein Element nicht dort platziert ist, wo du es erwartest, überprüfe, ob du die richtigen Attribute und die korrekte Orientierung der Achsen genutzt hast. Stelle zusätzlich sicher, dass version="1" im öffnenden <manialink>-Tag angegeben ist, da dies ebenfalls Einfluss auf die Werte der Achsen hat.

    Wie bereits gesagt, wird mit dem Z-Wert festgelegt, welches Element von welchen anderen überdeckt werden soll. Je größer (Menü-System) bzw. kleiner (klassisches System) der Z-Wert ist, desto weiter vorn wird das Element erscheinen. Sei vorsichtig mit diesen Z-Werten: Wenn zwei Elemente den gleichen Z-Wert besitzen,oder wenn ein Element einen ungültigen (zu großen oder zu kleinen) Wert besitzt, ist die Reihenfolge der Elemente meist zufällig, und kann sich sogar verändern, wenn du beispielsweise die Maus in die Menüleiste am oberen Rand von ManiaPlanet bewegst. Stelle also sicher, immer verschiedene Z-Werte bei sich überlappenden Elementen zu haben.

    Aber wieso gibt es überhaupt zwei Koordinatensysteme, wo doch eins bereits genug wäre? Der Grund ist vorwiegend historisch: Während das klassische System bereits in der allerersten Version der ManiaLinks, den United ManiaLinks, genutzt wurde, fand die Menü-Positionierung erst Einzug mit den Forever ManiaLinks als separates System, da das alte System nicht gut geeignet für die Menüs von TrackMania Forever geeignet war. Dennoch wurde das alte System beibehalten, um die Positionen der United ManiaLinks weiterhin korrekt berechnen zu können, und so existieren auch beide Systeme noch in den ManiaPlanet ManiaLinks aus Gründen der Abwärtskompatibilität. Um zumindest die Dinge ein wenig zu vereinfachen, wurden die konkreten Werte von beiden Systemen mit der Einführung der 16:9-Breitbild-Koordinaten aneinander angeglichen, sodass das Konvertieren zwischen den Systemen kein großes Problem mehr ist.

    Kurze Verschnaufspause: Erste Beispiele für die Positionierung
    Wir haben die notwendigen Grundlagen fast überstanden, doch bevor wir zum fehlenden Teil, der Ausrichtung von Elementen, kommen, sollen ein paar Beispiele die bisherige Positionierung etwas klarer machen. In diesen Beispielen werde ich Quads verwenden, um die Positionen darzustellen, da einem Quad einfach eine Hintergrundfarbe zugewiesen werden kann, um es sichtbar zu machen. Wir werden die verschiedenen Elemente der ManiaLinks später kennenlernen. Starten wir mit einem sehr einfachen Beispiel:

    Code:
    <quad bgcolor="F00A" />
    Wir haben weder eine Position, noch eine Größe für das Quad angegeben. (Nur die Hintergrundfarbe wurde definiert, um das Quad sichtbar zu machen.) Dennoch wird uns ManiaPlanet das Quad anzeigen, da für fehlende Attribute Standardwerte für diese verwendet werden. Die folgenden zwei Zeilen erzeugen das exakt gleiche Quad wie das vorherige, mit dem einzigen Unterschied, dass wir diesmal explizit die Position und Größe angegeben haben:

    Code:
    <quad posn="0 0 0" sizen="100 100" bgcolor="F00A" />
    <quad pos="0 0 0" size="1 1" bgcolor="F00A" />
    Es können zwei Dinge an diesem Beispielcode beobachtet werden: Zum einen, wie bereits eräwhnt, sind die beiden Positionierungssysteme gleich mächtig. Was auch immer wir im Menü-System (erstes Quad) angeben, können wir auch in das klassische System (zweites Quad) konvertieren. Aus diesem Grund werden die folgenden Beispiele und im restlichen Tutorial stets die Menü-Positionierung verwendet, aber natürlich kannst du jederzeit die klassische verwenden. Zum anderen sehen wir am Beispiel die eigentlichen Standardwerte für Position und Größe: Wird die Position weggelassen, so werden alle Koordinaten auf 0 gesetzt.Fehlt die Größe, wird diese auf 100 bzw. 1 für Breite und Höhe gesetzt.

    Code:
    <quad posn="40 -40" sizen="20 20" bgcolor="00FA" />
    Wenn wir den Z-Wert nicht auf einen Wert verschieden von 0 setzen müssen, können wir diesen auch weglassen, sodass nur X und Y angegeben sind. In diesem Beispiel haben wir eine Position verschieden von Null festgelegt, sodass dieses Quad nicht mehr in der Mitte des Bildschirms angezeigt werden wird. Was denkst du: In welche Richtung hat sich das Quad durch Angabe der Position "40 -40" (in Menü-Koordinaten) verschoben? Kopiere die Zeile in eine Manialink-Datei und überprüfe deine Antwort ^^

    Code:
    <quad posn="-160 90 -75" sizen="320 180" bgcolor="0008" />
    Dieses letzte Quad ist ein Beispiel für ein Hintergrundbild für den ManiaLink: Es bedeckt den gesamten Bildschirm, und wurde mit dem kleinstmöglichen Wert für die Z-koordinate in den Hintergrund gesetzt Wink2

    Die perfekte Verwirrung: Der Einfluss von halign und valign
    Eine weitere Besonderheit im Kontext der grundlegenden Positionierung von Elementen ist deren Ausrichtung, genauer gesagt deren halign (horizontal alignment, horizontale Ausrichtung) und valign (vertical alignment, vertikale Ausrichtung). Wirf einen Blick auf den folgenden Screenshot, welcher drei Elemente mit identischer Position zeigt, die sich nur in ihrer Ausrichtung wie angegeben
    [Image: alignment.png]

    Ohne das Geheimnis zu kennen, scheint die Ausrichtung ein wenig verwirrend. Das mit left links ausgerichtete Element ist rechts von dem mit right also rechter Ausrichtung? Und das nach unten (bottom) ausgerichtete ist über dem nach oben (top) ausgerichtetem? Das eintige, was man sich zur Ausrichtung merken muss, ist, dass wir nicht festlegen, wo sich das Element befinden soll, sondern wo die (mit pos oder posn festgelegte) Position sich befinden soll. Schaue also nochmal aufdas Bild, und achte diesmal darauf, wo sich jeweils der Positionierungspunkt bezüglich des Elementes befindet. Und nun sehen wir, dass die Ausrichtung Sinn ergibt: Wenn wir halign="bottom" und valign="right" festlegen, so befindet sich der Positionierungspunkt unten rechts vom Element, also befindet sich das Element selbst oben links vom Punkt. Also denke immer daran: halign und valign legen fest, wo der Positionierungspuntk sein soll, und nicht, wo das Element hin soll Wink2

    Als letztes sei noch erwähnt: Der Standardwert für halign ist left und der für valign ist top. Wenn du diese Attribute weglässt, wird sich das Element folglich rechts unterhalb der festgelegten Position befinden.




    Einen Code für den ManiaLink Registrieren

    [[[TODO: Informationen zum neuen Domain/Subdomain-System fehlen...]]]


    © 2011 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 30.09.2011 15:28 by Marcel.)
    21.09.2011 11:32
    Visit this user's website Find all posts by this user Quote this message in a reply
    Marcel Offline
    ここにはコードがありません。
    ********
    ClanLeader

    Posts: 695
    Joined: Aug 2007
    Reputation: 22
    Post: #3
    Teil 2: Unterschiede zu den Forever ManiaLinks
    Jedes Detail, was sich mit dem ManiaPlanet Upgrade geändert hat

    Dieses Kapitel des Tutorials ist für all jene unter euch, die bereits die ManiaLinks aus Forever und deren Details kennen, und nun ihr WIssen auf die ManiaPlanet ManiaLinks "upgraden" wollen. Falls du dich gerade durch das Grundwissen zu ManiaLinks gearbeitet hast, spring zum nächsten Teil des Tutorials, da dieser Teil keine neuen Informationen beinhaltet, die benötigt werden.

    Grundlegend hat sich nur wenig von Forever zu ManiaPlanet geändert: Wenn du einen Forever ManiaLink besitzt, so wird dieser relativ problemlos auch in ManiaPlanet funktionieren. Dennoch gibt es ein paar Details, die du zu den ManiaPlanet ManiaLinks wissen solltest. Lasst uns das Upgrade beginnen... Biggrin

    Mach dich bereit für das nächste Level: ManiaLink Version 1

    Der Hauptunterschied zu den Forever ManiaLinks ist die neue Version von ManiaLinks, die mit ManiaPlanet eingeführt wurde. Diese hat Einfluss auf einige Features der ManiaLinks, um diesebesser für die Zukunft zu rüsten. Während den Forever ManiaLinks (und den alten United ManiaLinks) die Version 0 zugeordnet wurde, tragen die ManiaPlanet ManiaLinks die Version 1. Diese Version wird einfach im öffnenden <manialink>-Tag am Anfang des ManiaLinks angegeben, wie unter <manialink> näher beschrieben wurde. Aktuell gibt es zwei grundlegende Features, die in ManiaLinks der VErsion 1 aktiviert werden:

    ManiaLinks werden Breitbild
    ManiaLinks mit Version 0 besitzen ein Koordinatensystem, welches auf einen 4:3 Bildschirm basiert. Allerdings bewegte sich die Entwicklung in den letzten Jahren hin zu Breitbild-Monitore, sodass alle ManiaLinks von 4:3 verzerrt wurden, um den Bildschirm zu füllen.

    Wird die Version nun auf 1 gesetzt, so wird ein neues Koordinatensystem aktiviert, welches auf 16:9 Anzeigen optimiert ist. Die neuen Werte für die Achsen der Positionierungs-Systeme sind wie folgt:
    [Image: classic.de.png][Image: menu.de.png]

    Besonders herauszuheben ist, neben den geänderten Verhältnissen und den daran angepassten Werte, die vereinfachte Konvertierung zwischen der Menü- und der klassischen Positionierung. Während in Version 0 die Werte mit 64 mulitpliziert werden mussten, um von den klassichen in die Menü-Koordinaten umzurechnen, brauchen die Werte in der neuen Version nur mit 100 multipliziert, also das Komma lediglich zwei Stellen nach rechts gerückt werden Wink2

    Hinweis: Obwohl ManiaScript in beiden Versionen funktioniert, verwendet es stets das neue 16:9-Koordinatensystem um irgendwelche Positionen zu berechnen. Sobald also ManiaScript im ManiaLink verwendet wird, stelle sicher, dass du die Version 1 verwendest, um unnötige Kopfschmerzen zu vermeiden Wink2

    Kein Support der line/cell-Syntax mehr
    Das Anheben eines ManiaLinks auf Version 1 deaktiviert vollständig die Unterstützung der alten line/cell-Syntax der United ManiaLinks. Diese Änderung ist nicht wirklich dramatisch, da die United ManiaLinks seit dem Forever Upgrade veraltet sind, und somit seit einigen Jahren nicht mehr aktiv für ManiaLinks verwendet wird. (Falls du nicht weißt, was die line/cell-Syntax ist: Keine Angst, du wirst ihr wohl niemals in Forever und ManiaPlanet ManiaLinks begegnen ^^)

    Wenn ein neuer ManiaLink für ManiaPlanet entwickelt wird, ist es empfohlen, die Version immer auf 1 zu setzen, um den ManiaLink zukunftssicher zu halten. Nur mit der neuen Version bekommst du die verbesserten Koordinatensysteme, die besser auf die weit verbreiteten Breitbild-Monitore passen als die alten.




    Neue und Veränderte Attribute

    Unabhängig von der verwendeten Version wurden nahezu allen Elementen neue Attribute zugeteilt, die in ManiaPlanet ManiaLinks Verwendung finden werden. An dieser Stelle soll lediglich eine kurze Liste dieser Attribute folgen, weitere Informationen sind der Referenz im nächsten Teil zu entnehmen Wink2

    Liste der neuen und veränderten Attribute
    • Neues Attribut version für <manialink>: Legt die Version des ManiaLinks fest.
    • Neues Attribut background für <manialink>: Aktiviert einen transparenten Hintergrund für den ManiaLink.
    • Neuer Wert center2 für valign von allen textbasierten Elementen: Richtet den Text leicht anders aus als von center bekannt.
    • Veränderte Werte für style und substyle von allen Style-basierten Elementen: Die Liste der verfügbaren Styles wurde an ManiaPlanet angepasst, auf dem ManiaLink Exemple sind die neuen Werte einzusehen.
    • Neues Attribut id für alle positionierbaren Elemente: Stellt den Zugriff auf das Element in ManiaScript zur Verfügung.
    • Neues Attribut ScriptEvents für alle sichtbaren Elemente: Aktiviert zusätzliche ManiaScript Events für das Element.


    ManiaScript Integration

    Eins der großen neuen Features von ManiaPlanet, und die wohl größte Änderung für ManiaLinks, sind die sogenannten ManiaScripts. Während Forever ManiaLinks immer statisch waren und nicht mehr geändert werden konnten, nachdem sie einmal ausgegeben wurden, gibt uns ManiaScript die Möglichkeit, mehr dynamik in diese zu bringen. So ist der ManiaLink nun in der Lage, auf das Verhalten des Benutzers zu reagieren, ohne den kompletten ManiaLink neu laden zu müssen: Die Maus generiert einige Events genauso wie die Tasten es tun. Wenn der Benutzer den Mauszeiger auf ein Icon bewegt, zeige einen kleinen Hinweis an, was dieses Icon macht. Platziere ein kleines "X" in dein Popup-Fenster, um den Benutzer dieses schließen zu lassen... Ohne den ManiaLink neu zu laden. Und das sind ziemlich einfache Beispiele für die Möglichkeiten, die ManiaScript in die ManiaLinks bringt Biggrin

    Falls du mehr darüber wissen möchtest, lies dir das Kapitel ManiaScript in ManiaLinks durch.




    Ersetzung von AddPlayerID durch ManiaConnect

    In TMF gab es die Möglichkeit, das Attribut addplayerid in einigen Elementen zu verwenden, um zusätzliche Informationen zum Spieler anzufordern, der gerade den ManiaLink anschaut. Dieses Feature wurde aus ManiaPlanet gestrichen, hauptsächlichst weil die übertragenen Werte viel zu einfach zu manipulieren waren, sodass dies, laut Nadeo, nicht mit dem Konzept von ManiaPlanet kompatibel war.

    An die Stelle von addplayerid tritt das von Nadeo neu eingeführte System namens ManiaConnect um wieder Zugriff auf die Daten des Spielers zu bekommen. Mit ManiaConnect muss der Spieler explizit dem Zugriff eines ManiaLinks auf seine Daten zustimmen, und nur wenn er das getant hat, ist der ManiaLink erst in der Lage die Daten anzufordern. Dieser neue Mechanismus ist komplett sicher und kann nicht mehr manipuliert werden, was neue Möglichkeiten eröffnet: Beispielsweise kann ein AdminPanel einfach den Login des Spielers als Sicherheit nutzen, denn wenn beispielsweise der Login "m4rcel" ist, handelt es sich definitiv um meine Wenigkeit (oder jemand hat meinen Account gehackt Biggrin ). Auf der anderen Seite müssen wir die erhöhte Sicherheit mit einem etwas komplizierterem Zugriff auf die Daten, unter Verwendung der ManiaPlanet WebServices, bezahlen.

    Im letzten Teil des Tutorial ist ein komplettes Beispiel zur ManiaConnect Authentifizierung gegeben.




    Weitere Änderungen

    Zugriff auf lokale Dateien
    Ein weiteres neues Feature in ManiaPlanet ist der direkte Zugriff auf Dateien, die lokal auf dem Rechner gespeochert sind. Hierzu wird das Präfix file:// genutzt, und als Basis-Ordner der ManiaPlanet Ordner verwendet. Wenn du beispielsweise einen ManiaLink aufrufen willst, der als Dokumente\ManiaPlanet\Media\Manialinks\test.xml gespeichert wurde, kannst du einfach "file://Media/Manialinks/test.xml" verwenden. Der Basis-Ordner ist dabei virtuell: Er zeigt nicht nur auf den ManiaPlanet-Ordner in deinen Dokumenten, sondern er zeigt gleichzeitig auch auf das Spieleverzeichnis und den Cache des Spiels. Versuche einfach mal "file://Media/Manialinks/Solitaire/index.xml" aufzurufen: Dieser ManiaLink ist in Wirklichkeit in irgendeinem der Packs gespeichert, die mit dem Spiel ausgeliefert wurde Wink2

    Dieses Feature ist vor allem während der Entwicklung eines ManiaLinks von Bedeutung: Anstatt jedesmal die Datei neu auf dem Server hochladen zu müssen, kann man diese nun direkt von der Festplatte aufrufen, solange sie im Media\Manialinks-Ordner gespeichert wurde. Selbstverständlich müssen alle lokalen Referenzen entfernt werden, bevor der ManiaLink veröffentlicht wird, da die anderen Spieler nicht in der Lage sein werden, diese lokalen Dateien anzufordern Wink2

    Keine Animationen
    ManiaPlanet unterstützt nicht mehr das animierte Bink-Format (.bik), und entsprechend gibt es keine Möglichkeit mehr, Animationen auf den ManiaPlanet ManiaLinks anzuzeigen. Als direkte Konsequenz gilt der <video>-Tag als veraltet und hat keinerlei Beudeutung mehr in ManiaPlanet ManiaLinks.

    UserAgent und andere Änderungen am Header
    Anstelle des UserAgenten Gamebox von TMF nutzt ManiaPlanet einen detaillierteren UserAgenten: ManiaPlanet/3.0.0 (2011-09-14). Somit ist es möglich, neben der Information, dass allgemein ManiaPlanet für den Aufruf des ManiaLinks genutzt wurde, auch die Version des Spiels auszulesen. Die könnte in der Zukunft hilfreich werden, wenn neue Features zu den ManiaLinks hinzugefügt werden (oder Fehler behoben werden), sodass man an der Version ablesen kann, ob diese Features tatsächlich verfügbar sind oder nicht.

    Als zusätzliche Information enthält der Header unter dem Eintrag Accept-Language die Sprache, mit dem das Spiel aktuell ausgeführt wird. Im Abschnitt über <dico> ist eine Liste der möglichen Sprachecodes zu finden.




    © 2011 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 30.09.2011 15:28 by Marcel.)
    21.09.2011 11:32
    Visit this user's website Find all posts by this user Quote this message in a reply
    Marcel Offline
    ここにはコードがありません。
    ********
    ClanLeader

    Posts: 695
    Joined: Aug 2007
    Reputation: 22
    Post: #4
    Teil 3: ManiaLink Elemente
    Eine vollständige Referenz von allen Elementen

    Dieses Kapitel stellt nun eine vollständige Referenz über alle Elemente der ManiaPlanet ManiaLinks zur Verfügung, inklusive einer detaillierter Liste der unterstützten Attribute. Wenn du neu in die ManiaLinks eingestiegen ist, solltest du dich einmal komplett durch diesen Teil des Tutorials lesen, um einen groben Eindruck zu bekommen, was für Elemente existieren und für was jedes einzelne von ihnen eingesetzt wird. Der eigentliche Zweck dieses Kapitels ist allerdings, eine Referenz darzustellen: Du brauchst dir nicht alle Details zu merken, es gibt keinen Test am Ende, um dein Wissen zu prüfen Biggrin

    <manialink>

    Der <manialink>-Tag ist der Vater aller Tags, er umschließt in einem ManiaLink als Wurzelknoten stets alle anderen Elemente. Fängt ein ManiaLink nicht mit dem <manialink>-Tag an, so ist es kein ManiaLink Biggrin

    Attribute:
    • version="1"Die Version des ManiaLinks
      Mit version kann die Version des ManiaLinks angegeben werden. Abhängig von der Version kann der ManiaLink anders dargestellt werden, und es können verschiedene Features verfügbar sein. ManiaLinks aus TrackMania Forever besitzen die Version 0, welche gleichzeitig der Standardwert ist. ManiaLinks aus ManiaPlanet besitzen die Version 1. Es wird empfohlen, bei allen neu entwickelten ManiaLinks, die nicht kompatibel zu TrackMania Forever sein sollen, die Version 1 zu nutzen, um alle Features der ManiaPlanet ManiaLinks nutzen zu können. Für mehr Informationen, siehe ManiaLink Version 1.
    • background="0"Die Sichtbarkeit des Hintergrundes
      Wird background auf 0 gesetzt, so besitzt der ManiaLinks selbst keinen Hintergrund, sondern nutzt was auch immer gerade vom Spiel hinter dem ManiaLink angezeigt wird. Somit kann dieses Feature als eine Art "transparenter Hintergrund" gesehen werden.

    Beispiel:
    Ein minimaler ManiaLink:
    Code:
    <?xml version="1.0" encoding="utf-8" ?>
    <manialink version="1">
        <!-- Inhalt des ManiaLinks -->
    </manialink>


    <timeout>

    Um Traffic zu sparen, werden alle angeforderten ManiaLinks von ManiaPlanet bis zum Beenden zwischengespeichert. Wird nun einer dieser gespeicherten ManiaLinks erneut abgerufen, so nutzt ManiaPlanet die lokale Version, und fordert die Datei nicht neu vom Server an. Was für statische ManiaLinks ein nettes Feature darstellt, ist für dynamische ManiaLinks, deren Inhalt sich jederzeit ändern könnte, der Untergang: Änderungen werden partout nicht angezeigt werden, einfach weil ManiaPlanet die Datei nicht neu anfordert.

    Mit dem <timeout>-Tag kann nun genau dieses Zwischenspeichern gesteuert werden: Der zwischen den Tags angegebene Wert stellen die Sekunden dar, die eine lokale Kopie maximal existieren soll. Üblicherweise wird mit einer 0 das Cachen vollständig deaktiviert, sodass ManiaPlanet die Datei bei jedem Aufruf tatsächlich neu vom Server anfordern wird.

    Beispiel:
    Rohbau eines ManiaLinks inklusive Timeout-Tag:
    Code:
    <?xml version="1.0" encoding="utf-8" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <!-- Inhalt des ManiaLinks -->
    </manialink>


    <frame>

    Ein Frame, zu deutsch "Rahmen", dient zum Gruppieren von zusammengehörigen Elementen, welche zwischen die <frame>-Tags geschrieben werden. Der Frame selbst ist dabei nicht sichtbar, mit seiner Position und seinem Skalierungsfaktor beeinflusst er aber alle enthaltenen Elemente in deren Darstellung. Das heißt konkret: Wird die Position des Frames verändert, so ändert sich gleichzeitig die Position alle in ihm befindlichen Elemente.

    Frames sollten immer dann zum Einsatz kommen, wenn verschiedene Elemente des ManiaLinks logisch zusammen gehören. So können alle Elemente des Menüs in ein Frame platziert werden: Entscheidet man sich, das Menü doch ein wenig nach unten zu versetzen, so brauch nur die Position des Frames verändert werden, die Positionen der einzelnen Menü-Schaltflächen bleiben davon unberührt. Dabei ist es möglich, Frames beliebig ineinander zu verschachteln, um so eine gewisse Hierarchie innerhalb des ManiaLinks zu erzeugen.

    Attribute:
    • pos(n)="X Y Z"Die Position des Frames
    • scale="Faktor"Der Skalierungsfaktor des Frames
    • id="Bezeichner"Die ID des Frames für das ManiaScript

    Beispiel:
    Ein Frame zum logischen Zusammenfassen zweier Quads:
    Code:
    <frame posn="50 50 0">
        <quad                sizen="20 20" bgcolor="F00A" />
        <quad posn="-20 0 0" sizen="20 20" bgcolor="00FA" />
    </frame>
    Dieses Beispiel zeigt einen Frame, der zwei verschieden farbige Quads enthält. Die Quads sind dabei exakt nebeneinander platziert, und richten sich am Frame aus: Wird der Frame verschoben, so verschieben sich die Quads ebenfalls, wobei diese sich aber weiterhin direkt nebeneinander befinden werden.




    <format>

    Mit Hilfe des <format>-Tags können ausgewählte Attribute anderer Elemente als allgemeines Format vordefiniert werden. Diese Angaben zählen dabei, abhängig davon, wo das <format> in der XML-Datei platziert wird, für den aktuellen Frame und alle untergeordneten Frames. Entsprechend zählen die Formatierungen global, wenn es direkt innerhalb des <manialink> definiert wird. Der <format>-Tag ist dabei selbst nicht sichtbar, beeinflusst aber, ähnlich wie ein <frame>, die Darstellung anderer Elemente.

    Das Format hat Einfluss auf <quad>, <label>, <entry> und <fileentry>. Dabei können die Elemente selbst jederzeit die vordefinierten Formate überschreiben, indem sie selbst das entsprechende Attribut definieren.

    Attribute:
    • bgcolor="RGBA"Die Hintergrundfarbe der Elemente – Beeinflusst: Quad
    • textsize="Zahl"Die Textgröße der Elemente – Beeinflusst: Label, Entry, FileEntry
    • textcolor="RGBA"Die Textfarbe der Elemente – Beeinflusst: Label, Entry, FileEntry
    • focusareacolor1="RGBA"Die Hintergrundfarbe (ohne MouseOver) der Elemente – Beeinflusst: Label, Entry, FileEntry
    • focusareacolor2="RGBA"Die Hintergrundfarbe (mit MouseOver) der Elemente – Beeinflusst: Label, Entry, FileEntry
    • style="StyleName"Der Style der Elemente – Beeinflusst: Label, Entry, FileEntry
      Nähere Informationen zu den einzelnen Attributen finden sich bei den entsprechenden Tags.

    Beispiel:
    Beispielhafte Definition eines vordefinierten Formats:
    Code:
    <format textcolor="F00F" />
    <label text="Hallo Welt!" />
    <label posn="0 -4 0" textcolor="FF0F" text="Hallo Welt!" />
    In diesem Beispiel wurde als vordefinierten Format die Schriftfarbe via textcolor auf rot gesetzt. Da das erste Label selbst kein textcolor definiert, wird die rote Farbe des <format> übernommen. Das zweite Label hingegen definiert die Schrift als gelb, und überschreibt somit die vordefinierte Formatierung.




    <quad>

    Das Quad zählt zu einemd er wichtigsten Elemente des ManiaLinks: Mit ihm lassen sich Bilder und Hintergründe anzeigen, um so dem ManiaLink einen individuellen Style zu geben. Dabei ist es auch möglich, die spieleigenen Styles von ManiaPlanet zu verwenden, um so den eigenen ManiaLink besser in das Spiel integrieren zu können. Eine weitere Option ist das Verlinken von Quads zu anderen ManiaLinks oder externen Websites, inklusive visuellem Feedback auf die Maus, wenn der Benutzer diese in ein Quad hinein bewegt. Als Bildformate werden dabei .jpg, .png, .tga und .dds akzeptiert.

    Attribute:
    • pos(n)="X Y Z"Die Position des Quads
    • size(n)="Breite Höhe"Die Größe des Quads
    • scale="Faktor"Der Skalierungsfaktor des Quads
    • halign="left|center|right"Die horizontale Ausrichtung des Quads
    • valign="top|center|bottom"Die vertikale Ausrichtung des Quads
    • style="KategorieName"Die Kategorie des Styles des Quads
    • substyle="StyleName"Der genaue Style des Quads
      Für das Quad müssen immer beide Attribute, style und substyle, angegeben werden, um ein spielinternes Design festzulegen. Eine Liste der verfügbaren Styles ist auf dem ManiaLink Exemple zu sehen.
    • image="Bild.jpg"Das Bild des Quads
    • imagefocus="Bild.jpg"Das Bild für den MouseOver-Effekt des Quads
      Die Bilder für image und imagefocus können wahlweise als absolute Pfade (http://localhost/images/bild.jpg) oder zur XML-Datei relative Pfade (./images/bild.jpg) angegeben werden.
      Wird die Maus in das Quad hinein bewegt, so wird das bei image angegebene Bild durch das von imagefocus ersetzt. Wird die Maus wieder hinaus bewegt, kommt das alte Bild wieder zum Vorschein. Dieser Effekt tritt allerdings nur auf, wenn das Quad zusätzlich verlinkt wurde.
    • bgcolor="RGBA"Die Farbe des Quads
      Da die Attribute style/substyle, image/imagefocus und bgcolor die gleiche Eigenschaft, nämlich die Darstellung des Quads, beeinflussen, können nicht alle drei gleichzeitig angegeben werden. Um genau zu sein ist die Priorität in der Reihenfolge, wie sie gelistet sind: Der Style überschreibt die Bilder, und diese wiederum die Farbe.
    • manialink="ManiaLink"Verlinkung zu einem ManiaLink (Registrierter Code oder URL)
    • url="ExterneSeite.html"Verlinkung zu einer externen Website
      Zum Anzeigen der Website wird ManiaPlanet minimiert und der Standardbrowser des Systems geöffnet.
    • id="Bezeichner"Die ID des Quads für das ManiaScript – Klasse CGameManialinkQuad
    • ScriptEvents="1"Aktiviert das Auslösen von Maus-Ereignissen für das Quad

    Beispiel:
    Beispielhafte Definition zweier Quads:
    Code:
    <quad style="Bgs1InRace" substyle="BgWindow1" />
    <quad sizen="16 4"
        image="http://localhost/manialink/menu.png"
        imagefocus="http://localhost/manialink/menuHover.png"
        manialink="FunTrackers"
    />
    Dieses Beispiel zeigt zwei Quads, wobei das erste einen vordefinierten Style von ManiaPlanet und das zweite eigene Bilder verwendet.




    <label>

    Neben den Quads sind die Label die wichtigsten Elemente eines ManiaLinks, um irgendwelche Texte anzuzeigen. Diese sind dabei nicht auf eine einzelne Zeile beschränkt, wie der Name "label" vermuten lassen könnte, sondern es können auch längere Texte inklusive Zeilenumbrüche dargestellt werden. Der anzuzeigende Text kann dabei wahlweise entweder als Attribut text angegeben oder zwischen die <label>-Tags geschrieben werden.

    Ein spezielles Feature der Labels (oder ein Fluch, je nachdem, ob man das Feature haben will oder nicht Biggrin ) ist die automatische Übersetzung von einigen Wörtern und Wortgruppen, die in den Sprachdateien von ManiaPlanet existieren. Wenn beispielsweise statistics (als einziges Wort) in ein Label geschrieben wird, so wird dieses automatisch in Statistik übersetzt, wenn ein deutscher Spieler den ManiaLink besucht. Falls du ein Wort nicht übersetzt haben möchtest, füge einfach ein Leerzeichen an das Ende hinzu.

    Attribute:
    • pos(n)="X Y Z"Die Position des Labels
    • size(n)="Breite Höhe"Die Größe des Labels
    • scale="Faktor"Der Skalierungsfaktor des Labels
    • halign="left|center|right"Die horizontale Ausrichtung des Labels
    • valign="top|center|center2|bottom"Die vertikale Ausrichtung des Labels
    • text="LabelText"Der im Label anzuzeigende Text
      Es können beliebige $-Formatierungen von ManiaPlanet genutzt werden. Wie bereits erwähnt, kann der Text statts als text-Attribut auch zwischen die <label>-Tags geschrieben werden.
    • style="StyleName"Der vordefinierte Style des Labels
      In einem Label aktiviert das Attribut style bereits das Verwenden eines vordefinierten Styles des Spiels. Eine Liste der verfügbaren Styles ist auf dem ManiaLink Exemple zu sehen.
    • textsize="Zahl"Die Textgröße des Labels
    • textcolor="RGBA"Die Textfarbe des Labels
      Da die Attribute style und textsize/textcolor die gleiche Eigenschaft, nämlich die Darstellung des Textes des Labels, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die textspezifischen Angaben.
    • focusareacolor1="RGBA"Die Hintergrundfarbe des Labels (ohne MouseOver)
    • focusareacolor2="RGBA"Die Hintergrundfarbe des Labels (mit MouseOver)
      Die beiden Attribute focusareacolor1 und focusareacolor2 definieren die Hintergrundfarbe des Labels. Dabei gibt focusareacolor1 die Farbe an, wenn die Maus aktuell nicht über dem Label ist, und focusareacolor2 die Farbe, wenn die Maus sich über dem Label befindet.
      Da style und focusareacolor1/focusareacolor2 beide die gleiche Eigenschaft, nämlich die Darstellung des Hintergrundes des Labels, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die Hintergrund-spezifischen Attribute.
    • autonewline="1"Aktiviert den automatischen Zeilenumbruch des Labels
      Wird autonewline auf den Wert 1 gesetzt, werden lange Zeilen automatisch umgebrochen, um auf die Breite des Labels zu passen. Ansonsten werden nur die Zeilenumbrüche verwendet, die direkt in der XML-Fatei als solche angegeben wurden, was unter Umständen zu überlangen Zeilen führen kann.
    • maxline="Zahl"Begrenzt die Anzahl der maximal angezeigten Zeilen des Labels
      Mit maxline kann die Anzahl der angezeigten Zeilen des Labels begrenzt werden. Alle Zeilen, die diese Einschränkung überschreiten, werden ignoriert und nicht im Label dargestellt.
    • manialink="ManiaLink"Verlinkung zu einem anderen ManiaLink (Registrierter Code oder URL)
    • url="website.html"Verlinkung zu einer externen Website
      Zum Anzeigen der Website wird ManiaPlanet minimiert und der Standardbrowser des Systems geöffnet.
    • id="Bezeichner"Die ID des Labels für das ManiaScript – Klasse CGameManialinkLabel
    • ScriptEvents="1"Aktiviert das Auslösen von Maus-Ereignissen für das Label

    Beispiel:
    Beispiel eines Labels mit einem vordefinierten Style und einer $-Formatierung:
    Code:
    <label style="CardButtonMediumWide" text="Ein Button mit einem $F00roten$g Wort" />


    <audio>

    Wie der Name bereits sagt, können mit dem <audio>-Tag Musik-Dateien auf dem ManiaLink wiedergegeben werden. Diese Datei wird dabei als einfacher Start/Stopp-Button angezeigt, mit welchem der Benutzer die Wiedergabe jederzeit starten und stoppen kann. Als Dateiformate werden .ogg und .mux akzeptiert.

    Attribute:
    • pos(n)="X Y Z"Die Position des Audios
    • size(n)="Breite Höhe"Die Größe des Audios
    • scale="Faktor"Der Skalierungsfaktor des Audios
    • halign="left|center|right"Die horizontale Ausrichtung des Audios
    • valign="top|center|center2|bottom"Die vertikale Ausrichtung des Audios
    • data="audio.ogg"Die abzuspielende Aduio-Datei
    • play="1"Aktiviert den automatischen Start des Audios
      Wird play auf den Wert 1 gesetzt, wird die Audio-Datei nachdem sie vollständig geladen wurde, automatisch gestartet werden.
    • looping="0"Deaktiviert die Endlosschleife des Audios
      Wird looping auf den Wert 0 gesetzt, wird ManiaPlanet die Wiedergabe der Audio-Datei anhalten, wenn diese das erste Mal beendet ist. Ansonsten wird das Spiel die Audio-Datei in einer Endlosschleife wiederholen.
    • id="Bezeichner"Die ID des Audios für das ManiaScript – Klasse CGameManialinkControl
    • ScriptEvents="1"Aktiviert das Auslösen von Maus-Ereignissen für das Audio

    Beispiel:
    Beispielhafte Verwendung eines <audio>-Tags:
    Code:
    <audio data="http://localhost/audio.ogg" play="1" />


    <music>

    Der <music>-Tag wird ebenfalls für die Wiedergabe von Musikdateien verwendet. Anstatt aber die Kontrolle für die Wiedergabe dem Benutzer zu überlassen, wie es beim <audio> der Fall ist, spielt der <music>-Tag die Musikdatei im Hintergrund ab, ohne Möglichkeit für den Benutzer, die Endlosschleife abzuschalten. Erneut werden die Dateiformate .ogg und .mux in diesem Tag akzeptiert. Ein zusätzliches Feature ist, dass die Wiedergabe der Musik nicht unterbrochen wird, wenn der ManiaLink gewechselt wird, und dieser die identische Musik-Datei in seinem <music>-Tag verwendet.

    Hinweis: Der <music>-Tag funktioniert nur, wenn er als direktes Kind des <manialink>-Tags, also außerhalb aller Frames, platziert wird.

    Attribute:
    • data="music.ogg"Die abzuspielende Musik-Datei

    Beispiel:
    Beispielhafte Verwendung eines <music>-Tags mit seinem einzigen Attribut:
    Code:
    <music data="http://localhost/music.ogg" />


    <include>

    Der Name des <include>-Tags lässt bereits erahnen, dass man mit ihm weitere XML-Dateien in den aktuellen ManiaLink einbinden kann. Das eröffnet die Möglichkeit, häufig genutzte Elemente wie das Menü in eine separate Datei auszulagern, und diese dann in alle tatsächlichen ManiaLinks zu importieren: Wenn du etwas am Menü ändern willst, muss lediglich die separate Datei modifiziert werden, anstatt von alle Dateien, in denen das Menü eingebunden wurde Wink2

    Der Import von anderen Dateien ist auf eine Ebene limitiert. Das bedeutet, dass zwar eine Datei in die "Haupt"-Datei eingebunden werden kann, allerdings kann nicht in der eingebundenen Datei eine weitere importiert werden. Der Grund ist, dass dadurch Zyklen von Import-Vorgängen verhindert werden: Wenn Datei A in der Lage ist, Datei B einzubinden, und B wiederum auch A importieren kann, resultiert das in einer endlosen Rekursion von einzubindenden Dateien.

    Ein anderer Aspekt ist, dass die einzubindende Datei eine vollständige und gültige XML-Datei sein muss, und kein vollständiger ManiaLink. Das heißt, die einzubindende Datei muss einen XML-Header sowie einen einzelnen Wurzelknoten (meistens ein <frame>, der alle anderen Elemente enthält) besitzen, und darf selbst keinen eigenen <manialink>-Tag besitzen. Du kannst die den Import-Vorgang wie folgt vorstellen: ManiaPlanet zerschneidet den Haupt-ManiaLink in zwei Teile, und klebt an diese Stelle die unveränderte einzubindende Datei. Ein zusätzliches <manialink> würde an dieser Stelle keinen Sinn ergeben Wink2

    Hinweis: Beachte, dass das Einbinden von Dateien mittels des <include>-Tags zu einer längeren Ladezeit des ManiaLinks führt, da die einzubindende Datei separat vom Server angefordert werden muss. Wenn du einen dynamischen (beispielsweise auf PHP basierenden) ManiaLink hast, solltest du stets die PHP-eigenen include- und require-Befehle bevorzugen.

    Attribute:
    • url="include.xml"Die URL der einzubindenden Datei

    Beispiel:
    Haupt-ManiaLink-Datei:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1.0">
        <quad sizen="10 10" bgcolor="F00A" />
        <include url="file://Media/Manialinks/include.xml" />
    </manialink>
    Die einzubindende include.xml-Datei:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <frame>
        <quad posn="10 0" sizen="10 10" bgcolor="0F0A" />
        <quad posn="20 0" sizen="10 10" bgcolor="00FA" />
    </frame>
    Der zweite Code-Schnipsel zeigt die einzubindende Datei. Wie bereits erwähnt, besitzt diese selbst keinen <manialink>-Tag, benötigt aber einen <frame>, der die eigentlichen Elemente umgibt, da eine XML-Datei nur einen einzigen Wurzelknoten besitzen darf.




    <entry>

    Eine weitere Möglichkeit, mit dem Benutzer zu interagieren, ist das Anzeigen eines Eingabefeldes, in ManiaLinks Entry genannt, wo er einen beliebigen Wert eingeben kann. Entsprechend macht das Entry nur Sinn auf dynamischen ManiaLinks, wo im Hintergrund ein serverseitiges Script arbeitet (bspw. in PHP geschrieben), welches die eingegebenen Werte verarbeiten kann. Die Verwendung eines <entry> ist relativ einfach: Es wird ein eindeutiger name angegeben, und überall wo dieser Name in einem Link eines Labels oder Quads auftaucht, wird er durch den aktuellen Wert des Entrys ersetzt. Beachte, dass ein Entry immer String-Werte entgegennimmt, das heißt, eine eventuelle Einschränkung beispielsweise auf Zahlen muss serverseitig geprüft werden.

    Attribute:
    • pos(n)="X Y Z"Die Position des Entrys
    • size(n)="Breite Höhe"Die Größe des Entrys
    • scale="Faktor"Der Skalierungsfaktor des Entrys
    • halign="left|center|right"Die horizontale Ausrichtung des Entrys
    • valign="top|center|center2|bottom"Die vertikale Ausrichtung des Entrys
    • style="StyleName"Der vordefinierte Style des Entrys
    • textsize="Zahl"Die Textgröße des Entrys
    • textcolor="RGBA"Die Textfarbe des Entrys
      Da die Attribute style und textsize/textcolor die gleiche Eigenschaft, nämlich die Darstellung des Textes des Entrys, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die textspezifischen Angaben.
    • focusareacolor1="RGBA"Die Hintergrundfarbe des Entrys (ohne MouseOver)
    • focusareacolor2="RGBA"Die Hintergrundfarbe des Entrys (mit MouseOver)
      Die beiden Attribute focusareacolor1 und focusareacolor2 definieren die Hintergrundfarbe des Entrys. Dabei gibt focusareacolor1 die Farbe an, wenn die Maus aktuell nicht über dem Entry ist, und focusareacolor2 die Farbe, wenn die Maus sich über dem Entry befindet.
      Da style und focusareacolor1/focusareacolor2 beide die gleiche Eigenschaft, nämlich die Darstellung des Hintergrundes des Entry, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die Hintergrund-spezifischen Attribute.
    • name="EntryName"Der eindeutige Name des Entrys
      Wie bereits erwähnt, ist der name des Entrys sehr wichtig: Wo immer der Name in einem Link auftaucht, wird der durch den aktuell vom Benutzer eingegebenen Wert ersetzt.
    • default="Wert"Der Standard-Wert des Entrys
      Wenn der ManiaLink geladen wird, wird das Entry mit dem Wert von default initialisiert. Solange der Benutzer keinen anderen Wert eingibt, wird dieser Standard-Wert im Entry angezeigt werden.
    • autonewline="1"Aktiviert den automatischen Zeilenumbruch des Labels
      Wird autonewline auf den Wert 1 gesetzt, wird die Eingabe des Benutzers automatisch auf eine neue Zeile umgebrochen, wenn diese die Breite des Entrys überschreitet. Dies ist besonders hilfreich, wenn eine größere Eingabe vom Benutzer erwartet wird.
    • id="Bezeichner"Die ID des Entrys für das ManiaScript – Klasse CGameManialinkEntry
    • ScriptEvents="1"Aktiviert das Auslösen von Maus-Ereignissen für das Entry

    Beispiel:
    Einfaches Beispiel eines Entrys und einem Link mit dessen Wert:
    Code:
    <entry sizen="50 5" style="TextValueSmall" name="inputValue" default="Hallo Welt!" />
    <label posn="0 -10" style="CardButtonMedium" text="Wert senden" url="http://localhost/script.php?value=inputValue" />
    Dieses Beispiel zeigt ein Entry mit dem Namen inputValue, und ein Label was dessen Wert zu einem Script sendet: Das inputValue im Link wird durch den aktuellen Wert des Entrys ersetzt. Für weitere Informationen, siehe das Fortgeschrittene Beispiel zu Entry und FileEntry.




    <fileentry>

    Das <fileentry> funktioniert in der gleichen Weise wie das <entry>, außer dass der Benutzer keine Werte eingibt, sondern eine Datei auswählt, die dann zum Server gesendet wird. Wie das Entry macht also auch das FileEntry nur Sinn bei dynamischen ManiaLinks, wo der Server die Datei entgegennehmen und verarbeiten kann.

    Sobald der Benutzer in das Feld eines FileEntrys klickt, öffnet sich ein Dialog, wo der Benutzer eine Datei von seinem Rechner auswählen kann. Diese Datei wird dann mittels einer POST-Anfrage abgesendet, für weitere Informationen siehe das Fortgeschrittene Beispiel zu Entry und FileEntry.

    Hinweis: Überprüfe immer die Datei, die der Benutzer hochgeladen hat, bevor sie auf dem Server gespeichert wird. Speichere niemals unkontrolliert Dateien, da dies ein hohes Sicherheitsrisiko darstellt!

    Attribute:
    • pos(n)="X Y Z"Die Position des FielEntrys
    • size(n)="Breite Höhe"Die Größe des FileEntrys
    • scale="Faktor"Der Skalierungsfaktor des FileEntrys
    • halign="left|center|right"Die horizontale Ausrichtung des FileEntrys
    • valign="top|center|center2|bottom"Die vertikale Ausrichtung des FileEntrys
    • style="StyleName"Der vordefinierte Style des FileEntrys
    • textsize="Zahl"Die Textgröße des FileEntrys
    • textcolor="RGBA"Die Textfarbe des FileEntrys
      Da die Attribute style und textsize/textcolor die gleiche Eigenschaft, nämlich die Darstellung des Textes des FileEntrys, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die textspezifischen Angaben.
    • focusareacolor1="RGBA"Die Hintergrundfarbe des FileEntrys (ohne MouseOver)
    • focusareacolor2="RGBA"Die Hintergrundfarbe des FileEntrys (mit MouseOver)
      Die beiden Attribute focusareacolor1 und focusareacolor2 definieren die Hintergrundfarbe des FileEntrys. Dabei gibt focusareacolor1 die Farbe an, wenn die Maus aktuell nicht über dem FileEntry ist, und focusareacolor2 die Farbe, wenn die Maus sich über dem FileEntry befindet.
      Da style und focusareacolor1/focusareacolor2 beide die gleiche Eigenschaft, nämlich die Darstellung des Hintergrundes des FileEntry, beeinflussen, können diese nicht gleichzeitig verwendet werden. Um genau zu sein überschreibt der Style die Hintergrund-spezifischen Attribute.
    • name="FileEntryName"Der eindeutige Name des FileEntrys
      Der name des FileEntrys hat die gleiche Aufgabe wie in einem Entry: Wo immer der Name in einem Link auftaucht, wird er durch den Namen der aktuell ausgewählten Datei des FileEntrys ersetzt.
    • folder="path"Der Pfad des obersten Ordners
      Mit dem folder-Attribut kannst du dem Benutzer helfen, die gewünschte Datei zu finden, indem du den obersten Ordner festlegst, den der Benutzer durchsuchen kann. Dieser Ordner ist immer relativ zum ManiaPlanet-Ordner in den Dokumenten, und es ist nicht möglich, in einen höheren Ordner als den angegebenen zu wechseln. Falls du beispielsweise eine Strecke als Datei erwartest, kannst du den Maps-Ordner als Basis-Ordner festlegen, aber denk daran, dass der Benutzer trotzdem in der Lage ist, alle möglichen Dateien hochzuladen, indem er sie vorher im entsprechenden Ordner speichert: Immer auf dem Server gegenprüfen!
    • default="value"Der Standard-Wert des FileEntrys
      Der Wert des default-Attributs wird solange angezeigt werden, bis der Benutzer eine Datei von seinem Rechner ausgewählt hat.
    • autonewline="1"Aktiviert den automatischen Zeilenumbruch für das FileEntry
      autonewline hat den gleichen Effekt wir in einem <entry>, da aber Dateinamen im Allgemeinen nicht allzu lang werden, wirst du dieses Attribut wohl nicht sehr oft benötigen.
    • id="Bezeichner"Die ID des FileEntrys für das ManiaScript – Klasse CGameManialinkFileEntry
    • ScriptEvents="1"Aktiviert das Auslösen von Maus-Ereignissen für das FileEntry

    Beispiel:
    Einfaches Beispiel für ein FileEntry und einen Link, der die ausgewählte Datei an den Server sendet:
    Code:
    <fileentry sizen="50 5" style="TextValueSmall" name="inputFile" folder="Maps" default="Wähle eine Map..." />
    <label posn="0 -10" style="CardButtonMedium" text="Datei senden" url="POST(http://localhost/script.php?file=inputFile,inputFile)" />
    Dieses Beispiel ist ähnlich zu dem von <entry>, mit dem einzigen Unterschied, dass wir die POST()-Methode nutzen müssen, um zu einen anderen ManiaLink oder Website zu verlinken. Für weitere Informationen, siehe erneut das Fortgeschrittene Beispiel zu Entry und FileEntry.




    <dico>

    Mit dem <dico>-Tag und einigen <language>-Tags ist es möglich, den ManiaLink in andere Sprachen zu übersetzen, sodass ein englisch-sprechender Spieler eine englische Version des ManiaLinks sieht, während ein deutscher Spieler eine deutsche Version präsentiert bekommt. Die tatsächlich genutzte Sprache wird dabei vom Spiel ausgewählt: Wenn die Sprache des Spielers (welche er in der Konfiguration von ManiaPlanet ausgewählt hat) als Übersetzung verfügbar ist, wird diese verwendet, ansonsten fällt ManiaPlanet zurück auf Englisch. Wenn beide nicht existieren, wird gar nichts angezeigt, also sollte sichergestellt werden, dass zumindest die Englische Übersetzung komplett ist Wink2

    Einen ManiaLink mehrsprachig zu machen ist relativ einfach: Anstatt beispielsweose den exakten text in einem <label> festzulegen, wird einfach eine ID für diesen angegeben, und zu jeder Sprache, in der der ManiaLink verfügbar sein soll, wird die entsprechende Übersetzung zu dieser ID gegeben. Um dies besser zu verdeutlichen soll ein Beispiel gegeben werden:

    Beispiel:
    Ein einfacher aber mehrsprachiger ManiaLink:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <!-- Die ManiaLink-Elemente selbst -->
        <label posn="-20 0" textid="example" />
        <label posn="-20 -10" textid="thanks" />
        <quad sizen="10 5" imageid="img" />

        <-- Die Übersetzungen der IDs -->
        <dico>
            <language id="en">
                <example>Example</example>
                <thanks>Thanks Nadeo for the new ManiaPlanet ManiaLinks!</thanks>
                <img>http://localhost/manialink/en.png</img>
            </language>    
        
            <language id="de">
                <example>Beispiel</example>
                <thanks>Danke Nadeo für die neuen ManiaPlanet ManiaLinks!</thanks>      
                <img>http://localhost/manialink/de.png</img>
            </language>
        </dico>
    </manialink>
    Im ersten Teil des Beispiels sehen wir die ManiaLink-Elemente, die weiter oben beschrieben wurden. Der einzige Unterschied ist nun, dass anstatt beispielsweise text das Attribut textid verwendet wurde. Das sagt ManiaPlanet, dass es die angegebene ID im <dico>-Tag nachschauen muss, und die ID durch die dort angegebene Übersetzung ersetzen muss. In der Tat braucht man lediglich nur ein "id" an den Namen des Attributes anzuhängen, welches übersetzt werden soll. Die folgenden Attribute unterstützen die Mehrsprachigkeit:

    Liste der unterstützten Attribute:
    • <quad>image, imagefocus, url, manialink
    • <label>text, url, manialink
    • <audio>data
    • <video>data
    Der zweite Teil des Beispiel zeigt die eigentliche Übersetzung der IDs, umgeben von den <dico>-Tags. Für jede Sprache, die unterstützt werden soll, wird ein <language>-Tag hinzugefügt, welcher als einziges Attribut id die Sprach-ID besitzt. Welche ID für welche Sprache genutzt wird, zeigt die folgende Liste:

    Liste der Sprach-Codes
    • czTschechisch
    • daDänisch
    • deDeutsch
    • enEnglisch
    • esSpanisch
    • frFranzösisch
    • huSpanisch
    • itItalienisch
    • jpJapanisch
    • krKoreanisch
    • nbNorwegisch
    • nlNiederländisch
    • plPolnisch
    • ptPortugiesisch
    • pt_BRBrasilianisches Portugiesisch
    • roRumänisch
    • ruRussisch
    • skSlowakisch
    • trTürkisch
    • zhChinesisch
    Für jede Sprache müssen nun alle zu übersetzenden IDs als Kindknoten zum <language> hinzugefügt werden, wie im Beispiel gezeigt wurde. Da die IDs Tag-Namen sind, ist es am besten, wenn du nur solche IDs wählst, die mit einem Buchstaben beginnen, und nachfolgend nur aus weiteren Buchstaben, Zahlen und dem Unterstrich _ bestehen. Versuche Sonderzeichen jeder Art, also auch deutsche Umlaute, in den IDs zu vermeiden, da diese die XML-Syntax stören könnten, und somit die gesamte ManiaLink-Datei ungültig machen könnten. Die Übersetzung selbst, notiert zwischen den ID-Tags, kann jede beliebige Sonderzeichen enthalten, denk aber dran, dass die Zeichen "<", ">" und "&" durch "&lt;", "&gt;" bzw. "&amp;" ersetzt werden müssen, um die XML-Syntax zu erhalten. Beachte weiterhin, dass du die XML-Datei auch wirklich als UTF-8 speicherst, damit die Sonderzeichen im ManiaLink korrekt angezeigt werden.




    <script>

    Der <script>-Tag ist das wohl einfachsten zu erklärende, und gleichzeitig das mit Abstand mächtigste Element innerhalb eines ManiaLinks: Mit ihm wird ein ManiaScript in den ManiaLink eingebunden. Die Notation ist dabei relativ intuitiv: Das ManiaScript selbst wird einfach zwischen die beiden <script>-Tags geschrieben. Da allerdings bestimmte Elemente des ManiaScripts die XML-Syntax stören könnten, muss das ManiaScript selbst zusätzlich in Kommentare gefasst werden.

    Es ist problemlos möglich, mehrere <script>-Tags in einen ManiaLink einzubauen. Die einzelnen Teile werden beim Laden des ManiaLinks einfach vor dem Ausführen zusammen geklebt, und quasi als ein großes ManiaScript betrachtet. Entsprechend macht es keinen Unterschied, ob nun ein ManiaScript in 3 Teilen, oder zusammenhängend beispielsweise am Ende des ManiaLinks eingegliedert wird Wink2

    Für weitere Informatione, siehe den entsprechenden Teil des Tutorial ManiaScript in ManiaLinks

    Beispiel:
    Ein einfaches Beispiel für einen vollständigen ManiaLink inklusive ManiaScript:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <quad id="myQuad" posn="10 0" sizen="20 20" bgcolor="F00A" ScriptEvents="1" />
        <script><!--
    while(True) {
        foreach(Event in PendingEvents) {
            if (Event.Type == CGameManialinkScriptEvent::Type::MouseClick) {
                Page.MainFrame.Controls["myQuad"].PosnX *= -1;
            }
        }
        yield;
    }
        --></script>
    </manialink>
    An dieser Stelle soll nicht näher auf das ManiaScript selbst eingegangen werden. Speichert euch den Code als XML-Datei ab, öffnet diese im ManiaPlanet-Browser und klickt ein wenig auf das Quad Wink2 Das Beispiel soll vorwiegend demonstrieren, wie ein ManiaScript eingebunden wird. Es sei nochmals darauf hingeweisen, dass das ManiaScript in einen XML-Kommentar einzubetten ist, um das XML-Dokument gültig zu halten.




    © 2011 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 04.10.2011 17:53 by Marcel.)
    21.09.2011 11:33
    Visit this user's website Find all posts by this user Quote this message in a reply
    Marcel Offline
    ここにはコードがありません。
    ********
    ClanLeader

    Posts: 695
    Joined: Aug 2007
    Reputation: 22
    Post: #5
    Teil 4: ManiaScript in ManiaLinks
    Manipulation eines ManiaLinks mit ManiaScript

    ManiaScript ist eine von Nadeo entwickelte, unabhängige Sprache, um verschiedene Aspekte von ManiaPlanet dynamischer zu machen. Dies zählt auch für die ManiaLinks: ManiaPlanet bietet die Möglichkeit, den ManiaLink nach dessen Ausgabe noch zu verändern und zu manipulieren, um so auf das Verhalten des Benutzers zu reagieren. Somit kann ManiaScript gundlegend genauso für ManiaLinks gesehen werden, was JavaScript für HTML ist. Dieser Teil des Tutorials wird sich exakt mit diesen ManiaScripten in ManiaLinks beschäftigen.

    Hinweis: Das Tutorial wird nicht auf die zu Grunde liegende Syntax von ManiaScripten eingehen. Falls du noch nie mit ManiaScripten gearbeitet hast, solltest du vorher das ManiaScript-Tutorial von destroflyer aufsuchen, um eine Einführung in ManiaScript zu bekommen. Der folgende Teil setzt grundlegendes Wissen über ManiaScripte voraus.

    Zugriff auf ManiaLink Elemente

    EInes der wichtigsten Dinge eines ManiaScripts in ManiaLinks ist die Manipulation der Elemente des ManiaLinks. Doch bevor wir irgendwelche Attribute von einem Element ändern können, müssen wir uns Zugriff zu diesen Elementen verschaffen, das heißt wir brauchen die Objekt-Instanz, die das gewünschte Element des ManiaLinks repräsentiert. Grundlegend gibt es zwei verschiedene Wege, um an ein Element heranzukommen, beide nutzen die globale Variable Page:
    • Page.MainFrame.Controls[ElementID]Zugriff auf ein Element über sein Eltern-Frame
      Der erste Weg, um die Hände an ein Element des ManiaLinks zu bekommen, ist dieses über den übergeordneten Frame abzufragen. Das Feld MainFrame des Typs CGameManialinkFrame repräsentiert den <manialink>-Tag des ManiaLinks, und wie der Name des Typs bereits vermuten lässt wird dieser einfach als ein weiterer Frame gesehen. Ein Frame hat nun ein Feld Controls, einem assoziativen Array, welches ControlIDs (vom Typ Text) auf die tatsächlichen Elemente (vom Typ CGameManialinkControl, siehe weiter unten für mehr Informationen) abbildet. Diese ControlIDs sind exakt diejenigen IDs, die mittels des Attributs id für die Elemente festgelegt wurden. Wenn du also Zugriff auf ein Element haben willst, stelle sicher, dass es eine eindeutige ID trägt Wink2

      Da Controls ein Array ist, können die einzelnen Elemente natürlich auch über deren Index abgefragt werden. Beispielsweise liefert Page.MainFrame.Controls[3] das 4. Kind von <manialink> (Denk dran, dass die Indizes mit 0 beginnen Wink2 ), auch wenn es keine eigene ID besitzt. Nichtsdestrotrotz ist das Festlegen von IDs der bessere Weg, da das verändern der Reihenfolge oder das Hinzufügen eines neuen Elementes die Idizes verschieben kann. Sei also vorsichtig damit Wink2

      Hinweis: Im Controls-Array sind nur die direkten Kinder eines Frames eingetragen, also alle direkten Kinder von <manialink> im Falle von Page.MainFrame. Das heißt wenn der ManiaLink einen Frame besitzt, so wird nur dieser Frame selbst als Kind in Page.MainFrame.Controls auftauchen, nicht aber die in diesem Frame enthaltenen Elemente. Wenn du eins dieser inneren Elemente erreichen willst, musst du zuerst den Frame auslesen (und diesen zu CGameManialinkFrame casten), und dann wiederum das Controls-Array dieses Frames aufrufen, um am Ende das gewünschte Element zu bekommen. Im Beispiel weiter unten ist diese Situation nochmals für ein besseres Versändnis erläutert Wink2
    • Page.GetFirstChild(ElementID)Nach einem Element suchen
      Der zweite Weg für das Zugreifen auf ein Element vom ManiaLink ist der Aufruf der Methode Page.GetFirstChild(ControlID): Unter Angabe der ID des gewünschten Elements sucht die Methode den gesamten ManiaLink nach diesem Element ab. Das bedeutet, dass das gesuchte auch gefunden wird, wenn es in Frames platziert wurde.

      Anstatt den gesamten ManiaLink mit Page.GetFirstChild() zu durchsuchen, kann diese Methode auch über ein Frame aufgerufen werden: In diesem Fall werden nur die Kinder und Kindeskinder von diesem Frame für die Suche nach der angegebenen ID in Betracht gezogen. Im Speziellen ist Page.MainFrame.GetFirstChild() ist äquivalent zu Page.GetFirstChild().


    Nachdem die Wege zum Zugriff auf ManiaLink-Elemente erklärt wurde, soll ein kurzes Beispiel helfen, das ganze etwas deutlicher zu machen, speziell die Sache mit den verschachtelten Frames.

    Beispiel:
    Beispiel für den Zugriff auf Elemente eines ManiaLinks:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <quad id="exampleQuad" />
        <frame id="outerFrame">
            <label id="exampleLabel" />
            <frame id="innerFrame">
                <entry id="exampleEntry" />
            </frame>
        </frame>
        
        <script><!--
    declare CGameManialinkQuad quad;
    declare CGameManialinkLabel label;
    declare CGameManialinkEntry entry;
    declare CGameManialinkFrame frame;

    // Zugriff auf Elemente über das Controls-Array
    quad = (Page.MainFrame.Controls["exampleQuad"] as CGameManialinkQuad);

    // Wir können nicht direkt auf exampleLabel und exampleEtry über Controls zugreifen,
    // sondern müssen zuerst den Frame bekommen und dessen Controls aufrufen usw.
    frame = (Page.MainFrame.Controls["outerFrame"] as CGameManialinkFrame);
    label = (frame.Controls["exampleLabel"] as CGameManialinkLabel);

    // Jetzt setzen wir frame auf das innerFrame-Element, um auf exampleEntry zuzugreifen
    frame = (frame.Controls["innerFrame"] as CGameManialinkFrame);
    entry = (frame.Controls["exampleEntry"] as CGameManialinkEntry);


    // Die gleichen Elemente bereitgestellt mittels GetFIrstChild()
    quad = (Page.GetFirstChild("exampleQuad") as CGameManialinkQuad);
    label = (Page.GetFirstChild("exampleLabel") as CGameManialinkLabel);
    entry = (Page.GetFirstChild("exampleEntry") as CGameManialinkEntry);
        --></script>
    </manialink>
    Was ist nun der Vorteil des Controls-Array, wenn die Methode GetFirstChild() so viel einfacher scheint? Es ist die volle Verfügbarkeit des Element-Baums: Man sieht immernoch, dass der innerFrame sich innerhalb des outerFrame befindet, und genau das kann hilfreich sein. Stell dir vor, du hast eine Auswahlliste, wo alle Einträge als Labels in einen separaten Frame platziert wurden. Anstatt nun allen Elemente eine eindeutige ID zuzuweisen und diese über GetFirstChild() abzufragen, kannst du einfach mittels einer foreach-Schleife alle Elemente des Controls-Array des Frames durchgehen, um Zugriff auf diese zu erhalten (du kannst sogar die IDs für die Einträge weglassen). Dies ist mit GetFirstChild() nicht möglich, da der Elemente-Baum nicht beachtet wird, der sagt, dass alle Elemente eines bestimmten Frames die Listeneinträge darstellen.

    Eine andere Sache, die dich am Beispiel etwas verwirren könnte, ist das Typecasting der Elemente, also das "konvertieren" in einen anderen Typ: Wann immer ein Element ausgelesen wird, muss es in seinen tatsächlichen Typ gecastet werden, Der Grund dafür ist, dass sowohl das Controls-Array als auch die GetFirstChild()-Methode immer ein Objekt der Klasse CGameManialinkControl zurück liefern. Da wir aber unter Umständen die erweiterten Funktionen eines Elements benötigen, müssen wir dieses vorher zu seinem eigentlichen Typ verändern. Nur wenn wir den outerFrame zu CGameManialinkFrame casten, sind wir in der Lage, auf sein Controls-Array zuzugreifen, um an den innerFrame zu gelangen. Eine detaillierte Liste der verfügbaren Klassen ist nachfolgend zu finden.




    ManiaLink Spezifische Klassen

    Um die Elemente eines ManiaLinks zu manipulieren, stellt ManiaScript nun verschiedene Klassen zur VErfügung, um dir dabei zu helfen. Die Basisklasse, welche stets vom Controls-Array und von GetFirstChild() zurück geliefert ist, ist CGameManialinkControl. Diese Klasse bietet grundlegende Felder und Methoden, um die Position und die Sichtbarkeit des Elements zu verändern. Alle anderen Klassen sind von dieser Basisklasse abgeleitet und erweitern somit die Möglichkeiten. Beispielsweise besitzt CGameManialinkLabel eine Methode SetText(), womit der angezeigte Text verändert werden kann. Die folgende Liste zeigt die verfügbaren Klassen für die ManiaLink Elemente, welche Elemente sie letztendlich repräsentieren, und von welcher Klasse sie abgeleitet sind.

    CGameManialinkControl

    Felder:
    • Text IdDie ID des Elements
    • Real PosnXDie X-Position im Menü-Koordinatensystem des Elements
    • Real PosnYDie Y-Position im Menü-Koordinatensystem des Elements
    • Real PosnZDie Z-Position im Menü-Koordinatensystem des Elements
    Methoden:
    • Void Hide()Versteckt das Element vom ManiaLink.
    • Void Show()Blendet das Element wieder ein nachdem es versteckt wurde.
    • Void Unload()Entfernt das Element vollständig vom ManiaLink. Das Element ist nicht mehr verfügbar, und ein nachfolgender Zugriff auf die Variable resultiert in einem Fehler.

    CGameManialinkFrame
    Abgeleitet von: CGameManialinkControl
    Repräsentiert: <frame>

    Felder:
    • Array CGameManialinkControl[Text] ControlsDie im Frame enthaltenen Elemente
    Methoden:
    • CGameManialinkControl GetFirstChild(Text)Stellt Zugriff auf untergeordnete Elemente des Frames zur Verfügung
      Parameter:
      • Text – Die ControlID des Elements

    CGameManialinkQuad
    Abgeleitet von: CGameManialinkControl
    Repräsentiert: <quad>

    Methoden:
    • Void ChangeImageUrl(Text)Ändert das Bild des Quads unter Angabe einer neuen URL.
      Parameter:
      • Text – Die neue URL die im Quad gezeigt werden soll.
      Hinweis: Die URL muss eine absolute URL sein und für das Quad muss bereits ein Bild mittels des image-Attribut festgelegt sein, damit diese Methode funktioniert.


    CGameManialinkLabel
    Abgeleitet von: CGameManialinkControl
    Repräsentiert: <label>

    Methoden:
    • Void SetText(Text)Ändert den aktuell im Label angezeigten Text.
      Parameter:
      • Text – Der neue Text, der im Label angezeigt werden soll.

    CGameManialinkEntry
    Abgeleitet von: CGameManialinkControl
    Repräsentiert: <entry>

    Felder:
    • Text ValueDer aktuelle Wert des Entrys.

    CGameManialinkFileEntry
    Abgeleitet von: CGameManialinkEntry
    Repräsentiert: <fileentry>

    Felder:
    • Text FullFileName [Nur Lesezugriff] – Stellt den vollständigen Pfad der im FileEntry ausgewählten Datei zur Verfügung.

    Hinweis: Ein weiterer Tag, der keine eigene Klasse besitzt, ist das <audio>: Dieser Tag wird direkt vom CGameManialinkControl repräsentiert und hat somit nur die Basis-Manipulation der Position und der Sichtbarkeit. Der <manialink>-Tag ist ein CGameManialinkFrame und stets über Page.MainFrame verfügbar. Nicht positionierbare Tags wie <music> oder <format> sind nicht über eine ID abfragbar, da beispielsweise das Ändern der Position keinen Sinn ergeben würde.




    Behandeln von Ereignissen

    Nun da wir wissen, wir wir bestimmte Elemente des ManiaLinks manipulieren können, felt natürlich noch die Reaktion auf die EIngaben des Benutzers, wie das Bewegen der Maus, Klicks und Tastendrücke. Dafür bietet ManiaScript verschiedene Typen an Ereignissen, englisch Events, welche exakt diese Aktionen des Benutzers darstellen:
    • MouseClickDer Benutzer hat mit der linken Maustaste auf ein Element geklickt.
    • MouseOverDer Benutzer hat die Maus in ein Element hineinbewegt.
    • MouseOutDer Benutzer hat die Maus aus einem Element hinausbewegt.
    • KeyPressDer Benutzer hat eine Taste gedrückt.
    Es gibt einige Einschränkungen für die Ereignisse, welche es verhindern, dass diese in einem ManiaScript behandelt werden können:
    • Nur Ereignisse, die nicht vom Element selbst behandelt werden, können von einem ManiaScript behandelt werden. Das bedeutet, dass beispielsweise ein Entry niemals ein KeyPress-Ereigniss generieren wird, da die Tastendrücke bereits dazu verarbeitet werden, um das gedrückte Zeichen im Entry einzufügen. Ein verlinktes Quad oder Label wird entsprechend niemals irgendwelche Maus-Ereignisse erzeugen.
    • Damit Maus-Ereignisse (MouseClick, MouseOver und MouseOut) für ein Element erzeugt werden, muss dessen Attribut ScriptEvents auf 1 gesetzt werden. Wenn ein Element ScriptEvents nicht auf 1 gesetzt hat, wird für dieses niemals ein Maus-Event generiert werden.
    • Jedes Ereignis wird nur einmal ausgelöst, die Z-Reihenfolge der Elemente entscheidet, welches Element am Ende das Ereignis wirklich "bekommt". Beispielsweise wird ein Mausklick von demjenigen Element verarbeitet, welches über allen anderen Elementen platziert wurde, also von demjenigen, welches den größten Z-Wert im Falle von Menü-Koordinaten bzw. den kleinsten Z-Wert im Falle der klassichen Koordinaten besitzt. Alle anderen Elemente hinter diesem ersten werden den Mausklick nicht zu sehen bekommen.
    Nun soll ein Blick auf eine typische Ereignisbehandlungsschleife (Event Handler Loop) eines ManiaLink-ManiaScripts geworfen werden:

    Ereignis-Behandlung eines ManiaLink-ManiaScripts:
    Code:
    main() {
        // #1 Ausgeführt als Initialisierung
        while(True) {
            // #2 Immer ausgeführt
            foreach(Event in PendingEvents) {
                switch(Event.Type) {
                    case CGameManialinkScriptEvent::Type::MouseClick: {
                        // #3 Ausgeführt bei einem MosueClick-Ereignis
                    }
                    case CGameManialinkScriptEvent::Type::MouseOver: {
                        // #4 Ausgeführt bei einem MouseOver-Ereignis
                    }
                    case CGameManialinkScriptEvent::Type::MouseOut: {
                        // #5 Ausgeführt bei einem MouseOut-Ereignis
                    }
                    case CGameManialinkScriptEvent::Type::KeyPress: {
                        // #6 Ausgeführt bei einem KeyPress-Ereignis
                    }
                }
            }
            yield;
        }
    }
    Grundlegend gibt es sechs Positionen, zu denen Code hinzugefügt werden kann, um verschiedene Situationen zu behandeln. Wenn ein Code einmalig direkt nach dem Laden des ManiaLinks ausgeführt werden soll, um beispielsweise einige Elemente zu verstecken, die erst später gezeigt werden sollen, so muss dieser außerhalb der Endlosschleife an Position #1 eingefügt werden. Im Gegensatz dazu wird der Code an Position #2 innerhalb der Schleife immer ausgeführt, Das heißt direkt nachdem er abgearbeitet wurde, wird er wieder und wieder ausgeführt. Dies wird am ehesten von (zeitbasierten) Animationen benötigt, da sie umso flüssiger laufen, je häufiger sie berechnet und dargestellt werden. Die foreach-Schleife wird nun für jedes eigentliche Ereignis ausgeführt, welche von irgendeinem Element erzeugt wurde. Um die einzelnen Ereignis-Typen zu unterscheiden, bietet sich ein switch an, wie es im Beispiel mit den Positionen #3 bis #6 gezeigt ist. Aber das liegt an dir, letztendlich ist das einzige, was wirklich beötigt wird, die endlose while-Schleife, die foreach-Schleife zum Abarbeiten der eingetroffenen Ereignisse, und dem yield am Ende der Endlosschleife.




    Komplexes Beispiel

    Um das Ganze ein wenig klarer zu mache, möchte ich nun ein vollständiges Beispiel angeben, welches das Verwenden von ManiaScript in einem ManiaLink demonstrieren soll. Das Beispiel ist recht einfach, aber zeigt dennoch, wie man die einzelnen Ereignisse behandeln kann, ohne die Animationsschleife zu stören. Falls du Probleme beim Verstehen des Beispiels hast, kopiere den Code einfach in eine neue XML-Datei, und modifiziere ihn etwas, um die Auswirkungen von den Änderungen zu beobachten.

    Im Einzelnen soll unser Beispiel eine fortlaufende Animation zeigen, welche einfach ein sich im Kreis bewegendes Quad sein wird. Zusätzlich soll dieses Quad auf die Maus des Benutzers reagieren: Wan immer ein MouseClick, MouseOver oder MouseOut erzeugt wird, soll das Quad seine Farbe ändern, um diese Ereignisse anzuzeigen. Lasst uns aber erstmal einen Blick auf den XML-Code werfen:

    XML-Code des ManiaScript-Beispiels:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1" background="0">
        <timeout>0</timeout>
        <!-- Der container wird verwendet, um die Position aller Quads gleichzeitig zu ändern -->
        <frame id="container">
            <!-- Das target Quad wird die Maus-Ereignisse generieren, auf die wir reagieren wollen -->
            <quad id="target" posn="0 0 5" sizen="20 20" ScriptEvents="1" />
            
            <!-- Da wir die bgcolor eines Quads direkt ändern können, nutzen wir mehrere Quads, und zeigen nur jenes, dessen Farbe wir aktuell zeigen wollen -->
            <quad id="red" sizen="20 20" bgcolor="A00A" />
            <quad id="green" sizen="20 20" bgcolor="080A" />
            <quad id="blue" sizen="20 20" bgcolor="00AA" />
        </frame>
        <script><!--
    #Include "MathLib" as MathLib

    // Zeigt das Quad mit der angegebenen ID und versteckt alle anderen (ausgenommen dem target)
    Void ShowQuad(Text ControlID) {
        declare CGameManialinkFrame Container <=> (Page.MainFrame.Controls["container"] as CGameManialinkFrame);
        foreach(Quad in Container.Controls) {
            if (Quad.Id == "target" || Quad.Id == ControlID) {
                Quad.Show();
            } else {
                Quad.Hide();
            }
        }
    }

    // Initialisiert die Animation
    Void Initialize() {
        // Speichert den Zeitpunkt der Initialisierung, da wir diese später für die Animation benötigen werden
        declare Integer StartTime for Page = CurrentTime;
        // Zeige standardmäßig das rote Quad zum Start
        ShowQuad("red");
    }

    // Berechnet die aktuelle Position der Animation und wendet diese auf den container an
    Void Animate() {
        // Macht die zuvor gespeicherte StartTime in unserer Funktion verfügbar
        declare Integer StartTime for Page;
        // Berechnet die Zeitdifferenz in Sekunden
        declare Real TimeDiff = (CurrentTime - StartTime) / 1000.;
        
        // Aktualisiert die aktuelle Position des container, um ihn letztendlich zu animieren
        declare CGameManialinkControl Container <=> Page.MainFrame.Controls["container"];
        Container.PosnX = 30 * MathLib::Sin(TimeDiff);
        Container.PosnY = 30 * MathLib::Cos(TimeDiff);
    }

    main() {
        Initialize();
        while(True) {
            Animate();
            foreach(Event in PendingEvents) {
                switch(Event.Type) {
                    case CGameManialinkScriptEvent::Type::MouseClick: {
                        ShowQuad("blue");
                    }
                    case CGameManialinkScriptEvent::Type::MouseOver: {
                        ShowQuad("green");
                    }
                    case CGameManialinkScriptEvent::Type::MouseOut: {
                        ShowQuad("red");
                    }
                }
            }
            yield;
        }
    }
        --></script>
    </manialink>
    Das erste Problem, was wir lösen müssen, ist, dass wir die bgcolor eines Quads nicht mit ManiaScript ändern können. Aus diesem Grund werden mehrere Quads mit derselben Größe und derselben Position, aber unterschiedlichen Farben genutzt, wo wir immer dasjenige davon anzeigen werden, dessen Farbe wir aktuell haben wollen. Diese Quads tragen die IDs red, green und blue.

    Da wir aber nicht diese drei Quads einzeln für die Maus-Ereignisse beobachten wollen, wurde ein viertes Quad <target> hinzugefügt, ebenfalls mit der gleichen Größe und Position, allerdings vor den anderen Quads (damit dieses garantiert unsere Maus-Ereignisse abfangen wird), und ohne irgendeine Farbe um es letztendlich unsichtbar zu machen. Dieses Quad ist das einzige Element, welches ScriptEvents="1" besitzt, sodass wir direkt wissen, dass alle Maus-Ereignisse zu diesem Quad gehören werden – Wir brauchen nicht zusätzlich die ControlId in unserem Beispiel zu prüfen.

    Da all diese Quads stets dieselbe Position besitzten sollen, platzieren wir sie in einen Frame namens container: Wir werden stets diesen container bewegen, um die Quads zu animieren, somit ist sicher gestellt, dass die Quads immer übereinander liegen werden.

    Kommen wir nun zum ManiaScript selbst, welches den wichtigsten Teil des Beispiels darstellt. Das Script hat grundlegend drei Funktionen: ShowQuad(ControlID) wird eines unserer farbigen Quads akzeptieren, und wird exakt diese Farbe anzeigen und alle anderen verstecken, unter bEachtung dass das target immer sichtbar bleibt, damit es weiterhin die Maus-Ereignisse abfangen kann. So wird zum Beispiel ShowQuad("blue"); das blaue Quad zeigen, egal welches aktuell angezeigt wurde. Initialize() wird einmalig nach dem Laden des ManiaLinks aufgerufen, um alle Werte zu initialisieren, die wir später benötigen werden, also in unserem Fall den Zeitpunkt, zu dem die Animation gestartet ist, und dem Anzaigen des roten Quads. Animate() berechnet mit jedem Aufruf die aktuelle Position der Quads, sodass sie eine kreisende Bewegung realisieren, basierend auf der verstrichenen Zeit (TimeDiff, in Sekunden). Diese Funktion wird immer aufgerufen werden, wenn wir nichts anderes zu tun haben, um die Anitmation so flüssig wie möglich zu machen.

    Der main()-Teil des ManiaSpripts implementiert nun das konkrete Verhalten um unsere Funktionen. Als erste Zeile sehen wir den Aufruf von Initialize();, sodass wir wissen, dass das rote Quad angezeigt wird, sobal wir die Endlosschleife betreten. Diese Endlosschleife selbst ist nun in drei Teile untergliedert:
    1. Aktualisiere die Animation mit dem Aufruf von Animate().
    2. Behandel irgendwelche Maus-Ereignisse, die seit dem letzten Durchlauf ausgelöst wurden. Abhängig von dem Typ des Maus-Ereignisses zeigen wir eine anders farbiges Quad, sodass wir die Ereignisse beobachten können, die am Quad angekommen sind. Zum Beispiel wird sich das Quad blau färben, wenn wir auf dieses klicken, aber wird rot werden sobald wir die Maus aus dem Quad bewegen – Wird das Quad mit der Muas verfolgt, so wird es seine blaue Farbe behalten Wink2
    3. yield gibt die Kontrolle zurück an ManiaPlanet, sodass das Spiel in der Lage ist, das PendingEvents-Array neu zu befüllen (wenn neue Ereignisse ausgelöst wurden) und um andere Arbeiten zu erledigen... zum Beispiel endlich die geänderte Position des Quads darzustellen Wink2 Sobald ManiaPlanet fertig ist, wird es die Kontrolle zurück an das ManiaScript geben (was nur wenige Millisekunden dauern wird), und somit den nächsten Durchlauf der Endlosschleife starten.
    Wir können sehen, dass ein Ereignis-Typ nicht beachtet wird: KeyPress. Sieh es als kleine Übung: Erweitere das ManiaScript (und den ManiaLink selbst) so, dass zusätzlich zum aktuellen Verhalten das Quad die Farbe zu gelb wechselt, wenn der Benutzer irgendeine Taste gedrückt hat Wink2




    © 2011 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 30.09.2011 15:28 by Marcel.)
    21.09.2011 11:33
    Visit this user's website Find all posts by this user Quote this message in a reply
    Marcel Offline
    ここにはコードがありません。
    ********
    ClanLeader

    Posts: 695
    Joined: Aug 2007
    Reputation: 22
    Post: #6
    Teil 5: Tipps & Tricks
    Ausgewählte Wissenswerte Themen

    Das letzte Kapitel des Tutorials wird ausgewählte Themen behandeln, die entweder nicht in die anderen Kapitel gepasst haben, oder einfach zum umfangreich sind, um sie dort direkt einzubauen. Die folgenden Teile sind unabhängig voneinander, sodass du direkt zu den Teilen springen kannst, die dich interessieren.

    Fortgeschrittenes Beispiel zu Entry und FileEntry
    PHP-Kenntnisse erforderlich.

    Mit Entrys und FileEntrys hat der Benutzer die Möglichkeit, eingegebene Werte und Dateien zu einem ManiaLinks zu senden. Dieser Abschnitt wird anhand von Beispielen erklären, wie du diese Elemente einsetzt und wie du letztendlich an die übertragenen Daten herankommst.

    Fortgeschrittenes Beispiel für Entry
    Die Verwendung eines Entrys ist sehr einfach, da die Werte direkt als zusätzliche Parameter an die URL angehangen werden können.

    XML-Code:
    Code:
    <entry sizen="10 5" style="TextValueSmall" name="inputValue" default="Hallo Welt!" />
    <label posn="0 -20" style="CardButtonMedium" text="Link mit dem Wert" manialink="ManiaLink?value=inputValue" />
    Behandelndes Script:
    PHP Code:
    <?php
    // Lese den übertragenen Wert
    $value $_GET['value'];

    // Escape den Wert, um den ManiaLink sicher gegen Manipulation zu machen
    $value htmlspecialchars($value);

    // Ausgabe des ManiaLinks
    header('Content-Type: text/xml');
    echo <<<EOT
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <label text="
    {$value}" />
    </manialink>
    EOT;
    ?>
    In der XML-Datei haben wir ein <entry> mit dem Namen inoutValue. Woauchimmer dieser Name in einer URL eines Links auftaucht, wird dieser automatisch durch den aktuellen Wert des Entrys ersetzt. In unserem Fall wird also inputValue im Link des Labels durch den eingegebenen Wert des Entrys ersetzt. Oder in anderen Worten: Der Inhalt des Entrys wird als Parameter value an unser Script gesendet, wie mit ?value=inputValue festgelegt wurde.

    Im Script müssen wir nun einfach den übergebenen Parameter mittels $_GET auslesen, und anschließend einen vollständigen ManiaLink generieren, wo der übergebene Wert in einem Label ausgegeben wird.

    Fortgeschrittenes Beispiel für FileEntry
    Die Verwendung eines FileEntrys ist ein wenig komplizierter, da wir eine Datei nicht als URL Parameter übergeben können, sondern ein POST-Anfrage generieren müssen.

    XML code:
    Code:
    <fileentry sizen="50 5" style="TextValueSmall" name="inputMap" folder="Maps" default="Wähle eine Map..."/>
    <label posn="0 -20" style="CardButtonMedium" manialink="POST(ManiaLink?map=inputMap,inputMap)" text="Map senden"/>
    Behandelndes Script:
    PHP Code:
    <?php
    // Lese die übertragene Datei ein
    $name $_GET['map'];
    $file file_get_contents('php://input');

    // Speichere die Datei auf dem Server
    // ACHTUNG: Überprüfe immer die vom Benutzer hochgeladene Datei, ob sie das ist, was du erwartest.
    // Dies wird in diesem Beispiel nicht gemacht, und stellt ein hohes Sicherheitsrisiko dar!
    file_put_contents("maps/{$name}"$file);

    // Ermittle die Dateigröße für die Ausgabe
    $size filesize("maps/{$name}");
    // Escape den Dateinamen
    $name htmlspecialchars($name);

    // Ausgabe des ManiaLinks
    header('Content-Type: text/xml');
    echo <<<EOT
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <label text="Erhaltene Map: 
    {$name} (Größe: {$size})" />
    </manialink>
    EOT;
    ?>
    Der XML-Code ist sehr ähnlich zu dem des Entry-Beispiels, der einzige Unterschied ist der Wert des manialink-Attributs des Labels. Anstatt des aufzurufenden ManiaLinks sehen wir nun ein POST(ManiaLink?map=inputMap,inputMap). Damit senden wir die Datei, welche im FileEntry inputMap (hinter dem Komma) ausgewählt wurde, an den ManiaLink ManiaLink?map=inputMap (vor dem Komma). Aber wieso taucht das FileEntry doppelt im Link auf? Der Grund dafür ist, dass wir den Dateinamen verlieren, wenn wir einfach nur die Datei senden. Da wir aber den Namen brauchen, um die Datei auf den Server zu speichern, mpssen wir diesens eparat an das Script übergeben. (Das heißt auch: Wenn du den Dateinamen selbst nicht brauchst, kann der Parameter in der URL vor dem Komma entfallen, sodass es zu einem POST(ManiaLink,inputMap) wird.)

    Das Script selbst leist nun Dateinamen und Datei ein, speichert die Datei auf dem Server und gibt den Dateinamen sowie die Größe der Datei als neuen ManiaLink aus. Der Code ist nicht wirklich kompliziert, wenn man einmal das Senden der Datei als POST-Anfrage gemeistert hat Wink2

    Hinweis: Ein weiteres Mal möchte ich darauf hinweisen, dass du die empfangene Datei immer überprüfen solltest! In unserem Beispiel wäre ein einfacher Schutz, den Dateinamen zu überprüfen, ob er auf .Map.Gbx endet, ein besserer aber auch schwieriger zu implementierender Schutz wäre das Auslesen und Validieren des XML-Headers der Map.




    ManiaConnect Authentifizierung
    PHP-Kenntnisse erforderlich.

    ManiaConnect ist ein System, mit welchem zusätzliche Daten zum Spieler, der gerade den ManiaLink anschaut, abgerufen werden können – Unter der Voraussetzung, dass er den Zugriff auf seine Daten erlaubt hat. Diese Informationen sind sicher und können nicht manipuliert werden, wenn du also beispielsweise m4rcel als Login hat, kannst du dir sicher sein, dass meine Wenigkeit gerade euren ManiaLink besucht (oder jemand meinen Account gehackt hat Biggrin ).

    ManiaConnect ist Teil der ManiaPlanet Web Services (MPWS). Die folgenden Bedingungen müssen erfüllt auf deinem Webspace erfüllt sein, damit du diese Services und ManiaConnect im speziellen nutzen kannst:
    • PHP 5.3 oder neuer
    • CURL-Erweiterung
    • JSON-Erweiterung
    Wenn dein Webspace diese Voraussetzungen erfüllt, lade dir die neueste Version des MPWS SDK für PHP.

    Erstellen eines API-Benutzer für die MPWS
    Bevor wir irgendwelche Daten anfordern können, müssen wir einen neuen API-Benutzer anlegen, mit welchen wir die MPWS nutzen können. Einen neuen API-Benutzer zu erstellen ist relativ einfach:
    1. Besuche developers.maniaplanet.com und logge dich mit deinem ManiaPlanet-Account ein.
    2. Klicke auf Web Services am oberen Rand der Seite, und nutze den Button Create a new API user um einen neuen Benutzer anzulegen.
    3. Wähle einen Identifier aus: Dabei handelt es sich um eine Zeichenkette, die zusammen mit eurem ManiaPlanet-Login den Namen des API-Benutzers bildet. Klicke anschließend auf Validate. Im nächsten Schritt ist ein Passwort festzulegen und zu bestätigen, bevor man erneut mit Validate zur Seite Manage your API user gelangt.
    4. Klicke auf den Button Create a ManiaConnect application: Wähle einen Namen für eure App, die Adresse wo ManiaCOnnect nach der Authentifizierung hinleiten soll sowie eine Kontakt-Adresse, falls es mal zu Problemen kommen sollte. Bestätige die Daten mit Validate.
    5. Fertig.


    Daten mit ManiaConnect anfordern
    Nun da wir einen API-Benutzer und eine ManiaConnect Applikation erstellt haben, sind wir bereit, einen ManiaLink zu schreiben, der die MPWS nutzt um zusätzliche Informationen des Benutzers anzuzeigen. Das folgende Beispiel demonstriert die Verwendung, indem der Nickname des aktuellen Benutzers angezeigt wird.

    ManiaLink, der ManiaConnect zum Anzeigen des Nicknamens verwendet:
    PHP Code:
    <?php
    // Ändere diese Werte zu denen von deinem API-Benutzer
    define('MPWS_USER''mpws_user');
    define('MPWS_PASS''mpws_pass');
    define('MPWS_SCOPE''basic');

    // Binde die MPWS-Dateien ein
    require('autoload.php');

    try {
        
    // Versuche, die Daten des Benutzers anzufordern
        
    $mpwsPlayer = new \Maniaplanet\WebServices\ManiaConnect\Player(MPWS_USERMPWS_PASS);
        
    $player $mpwsPlayer->getPlayer();
        
        if (!
    $player) {
            
    // Wenn $player gleich false ist, muss der Benutzer seine Daten erst für unseren ManiaLink freigeben,
            // also müssen wir die Login-URL für ihn ausgeben
            
    $loginURL htmlspecialchars($mpwsPlayer->getLoginURL(MPWS_SCOPE));
            
    $label '<label style="CardButtonMedium" text="Authentifizierung" manialink="'.$loginURL.'" />';
        } else {
            
    // Wenn $player nicht false ist, hat der Benutzer seine Daten für uns freigegeben,
            // also können wir beispielsweise den Nicknamen ausgeben
            
    $nickname htmlspecialchars($player->nickname);
            
    $label '<label sizen="100 5" halign="center" text="Dein Nickname: '.$nickname.'" />';
        }
    } catch (\
    Maniaplanet\WebServices\Exception $e) {
        
    // Der Zugriff auf ManiaConnect beziehungsweise auf die WebServices im Allgemeinen ist fehlgeschlagen.
        // In diesem Fall geben wir einfach die Fehlermeldung aus.
        
    $message htmlspecialchars("[{$e->getHTTPStatusCode()} {$e->getHTTPStatusMessage()}{$e->getMessage()}"ENT_QUOTES'UTF-8'); 
        
    $label '<label sizen="100 5" halign="center" text="Exception: '.$message.'" />';
    }

    // Ausgabe des ManiaLinks
    header('Content-Type: text/xml; charset=utf-8');
    echo <<<EOT
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        
    {$label}
    </manialink>
    EOT;
    ?>
    Wichtig ist, dass die Klasse Player vor der ersten Ausgabe instantiiert wird, da diese eine Session (unter Verwendung des PHP-internen Session-Mechanismus) initialisiert. Anschließend wird einfach versucht, die Informationen mittels getPlayer() abzufragen: Wenn uns der Zugriff auf die Daten erlaubt wurde, so werden wir diese direkt zurück geliefert bekommen, ansonsten wird einfach false zurück gegeben. Entsprechend des Rückgabewertes können wir also entscheiden, ob wir bereits den Nicknamen ausgeben können, oder ob wir dem Benutzer erst um die Erlaubnis fragen müssen.

    Wenn wir die Erlaubnis für das Anfordern der Daten des Spielers nicht besitzen, müssen wir die Methode getLoginURL() aufrufen, um die URL zu einem ManiaLink zu bekommen, über welchen der Benutzer seine Erlaubnis erteilen kann. Wir brauchen uns nicht weiter um die Authentifizierung zu kümmern, einfach die URL ausgeben und "warten", dass der Benutzer zurück zu unseren ManiaLink geleitet wird: Wenn er den Datenzugriff erlaubt hat, haben wir diese im nächsten Script-Durchlauf und können entsprechend den Nickname ausgeben, ansonsten wird erneut die Login-URL ausgegeben.

    Die Gültigkeitsbereiche von ManiaConnect
    Eine Sache, die noch nicht erläutert wurden, sind die Gültigkeitsbereiche, oder englisch Scopes, von ManiaConnect. Der Gültigkeitsbereich sagt, welche Daten wir vom Benutzer anfordern wollen, und entsprechend welche Daten der Benutzer für unseren ManiaLink freigeben soll.

    Liste der verfügbaren Gültigkeitsbereiche
    • basic – Methode: getPlayer()Grundlegende Informationen wie Login, Nickname und Zone
    • buddies – Methode: getBuddies()Liste der Freunde
    • dedicated – Methode: getDedicated()Liste der Dedicated Server
    • email – Methode: getEmail()Email-Adresse
    • manialinks – Methode: getManiaLinks()Liste der registrierten ManiaLink-Codes
    • online_status – Methode: getOnlineStatus()Online-Status
    Wenn mehrere Bereiche genutzt werden, müssen diese einfach durch ein Leerzeichen getrennt werden.

    Hinweis: Fordere nur die Bereiche an, die du auch wirklich benötigst. Zum Beispiel sollte eine Shoutbox oder ein Gästebuch niemals nach den Freunden eines Spielers fragen.

    Zusätzliche Informationen
    Wenn du die Erlaubnis für einen bestimmten ManiaLink zurückziehen willst, besuche home.maniaplanet.com, logge dich mit deinem ManiaPlanet-Account ein, und verwalte die Applikationen, die aktuell Zugriff auf deine Daten besitzen.




    Alles hat ein Ende...

    Schlussendlich, nach sechs Beiträgen, einer länger als der andere, kommt auch das ManiaPlanet ManiaLinks Tutorial zum Ende. Nun liegt es an dir, das konzentrierte Wissen zu nehmen, und an deinen eigenen ManiaLinks in ManiaPlanet anzuwenden. Natürlich freue ich mit über jegliches Feedback zum Tutorial, sei es Lob und Dank für dieses, oder Vorschläge für Verbesserungen oder Hinweise auf Fehler und Probleme im Tutorial.

    Im allerletzten Absatz möchte ich all jenen danken, die mich während der Erstellung des Tutorials unterstützt haben, neben Nadeo auch all jenen, die mir in den Foren geholfen haben. Ein spezieller Dank geht dabei an FT»kastun, seeba und destroflyer, die kritisch das Tutorial begutachtet und auf alle Fehler hingewiesen haben, neben der Hilfe, das noch so kleinste Detail in dieses einzufügen. Ohne diesen Support wäre das Tutorial nicht so groß, wie es letztendlich geworden ist Smile


    Das war's, nun bist du dran.
    FT»Marcel



    © 2011-2012 ManiaPlanet ManiaLinks Tutorial von FT»Marcel (m4rcel)

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 13.02.2012 00:37 by Marcel.)
    21.09.2011 11:33
    Visit this user's website Find all posts by this user Quote this message in a reply
    Post Reply 



    Forum Jump:

    User(s) browsing this thread: 1 Guest(s)

    Contact Us | FunTrackers | Return to Top | Return to Content | Lite (Archive) Mode | RSS Syndication | Twitter