FunTrackers Easter Special 2016 - Finished! » View News


Post Reply 
 
Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
[EN] ManiaPlanet ManiaLinks
» The great Tutorial for all Newcomers and Changers from Forever
Author Message
Marcel Offline
ここにはコードがありません。
********
ClanLeader

Posts: 695
Joined: Aug 2007
Reputation: 22
Post: #1
[EN] ManiaPlanet ManiaLinks
The great Tutorial for all Newcomers and Changers from Forever

ManiaLinks – Little websites, which can be viewed directly in the game. If you always wanted to make your own ManiaLink, you are on the exact right place: This Tutorial will introduce the ManiaLinks and their creation to you. You already know how to make a ManiaLink for TrackMania Forever, and now want to upgrade your knowledge to ManiaPlanet? Then this Tutorial will help you, too.

This tutorial is built up of five parts, mostly independent from each other, and dealing with a certain topic. The first part is for all newcomers, who never heard from ManiaLinks and their creation, and will introduce them from the very beginning of XML over the basic knowledge needed to successfully build a ManiaLink in ManiaPlanet. If you already learned how to make a ManiaLink for TrackMania Forever, start with the second part of the tutorial, which will describe the differences between TrackMania Forever and ManiaPlanet. The third part contains a complete reference of all elements to be used in a ManiaLink, including all the attributes of each element, and detailled description of those. The fourth part is for experts, who already built some ManiaLinks and now want to manipulate the elements of the ManiaLinks using the ManiaScript language. The fifth and last part of the tutorial describes different aspects of ManiaLinks, which may be important to some of you, but mostly requires advanced knowledge. This last part can be seen as a collection of topics, which did not match into the other parts.

Although the ManiaLinks in ManiaPlanet are mostly the same as in TrackMania Forever, I sometimes want to differ between the versions of ManiaLinks. I will name the versions by the game with which they have been introduced, so in detail ManiaPlanet ManiaLinks are the ManiaLinks of ManiaPlanet, where Forever ManiaLinks are those known from TrackMania Forever. Additionally, United ManiaLinks are meant to be the very first ManiaLinks introduced with TrackMania United, having a completely different structure as known and described in this tutorial – You don't need to know these, they are only mentioned for completeness Wink2

Overview about the Tutorial
    Part 1: Introduction into the ManiaPlanet ManiaLinks
    From the very Basics to the Last Detail of Internal Mechanisms Part 2: Differences to the Forever ManiaLinks
    Every Detail which changed with the ManiaPlanet Upgrade of the ManiaLinks Part 3: ManiaLink Elements
    A Full Reference of all Elements Part 4: ManiaScript in ManiaLinks
    Manipulate the ManiaLink with a ManiaScript Part 5: Tips & Tricks
    Selected Topics which are Worth Knowing

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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 30.09.2011 15:37 by Marcel.)
    17.08.2011 15:46
    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
    Part 1: Introduction into the ManiaPlanet ManiaLinks
    From the very Basics to the Last Detail of Internal Mechanisms

    The first chapter of the Tutorial will deal with the basics of the ManiaLinks. If you never wrote your own ManiaLink before, this is the right place to start. This chapter will start with a short crash course into XML, on which the ManiaLinks are based and therefore is needed to create your own ManiaLink. After that, the real basics of ManiaLinks are described, in detail the positioning system which is needed to show any elements on it.

    If you want to make your ManiaLink public to all, the last part of this chapter will explain in how to register a code for it, so that others do not have to remember the full URL to your ManiaLink file. The only thing this chapter requires you to know is how to upload files to a webspace to make them available to everyone.

    Crash course into XML files and their syntax

    ManiaLinks make use of the XML standard to specify the elements to be displayed when viewing them. If you are already familiar with HTML, you know the basic syntax used for XML and so for ManiaLinks, but there are small differences between HTML and the stricter XML.

    So what exactly is XML? The three letters stand for eXtensible Markup Language, and is a general syntax for describing various documents. Although XML is standardized it sets no restrictions to the actual elements to be used: The application itself decides which elements are needed, and what they should represent in the end. In this part of the Tutorial I will only describe these features of XML which you really have to know to create a valid ManiaLink file.

    Hello World: Creating your first ManiaLink file
    An XML file is simply a text file, which commonly ends with .xml to indicate it to be XML. This means, you may use whatever text editor you want, nevertheless, especially for newcomers an editor with Syntax Highlighting is recommended, as this feature directly reveals most errors as of wrong colorization of the following code. I myself recommend the editor Notepad++, a lightweight editor supporting syntax highlighting for many different languages. In the following I assume you use Notepad++, but all steps may be adapted to other editors as well.

    After installing and opening Notepad++, select in the Language menu XML, to enable the correct highlighting, then type the following into it:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <label text="Hello World!" />
    </manialink>
    Before we finally save this file, we have to ensure it has the right encoding. This is important, if you use special characters like German umlauts, because if you save the file in the wrong encoding, these characters will be messed up and not displayed correctly on the ManiaLink. In Notepad++ open the Encoding menu, and check what encoding the file currently has (i.e. which element is marked). If it is not Encode in UTF-8 without BOM, click the option Convert to UTF-8 without BOM a little more down in the menu. Double check the correct encoding to be on safe site Wink2

    When saving the file, you have to pay attention to really save it as XML file (i.e. with ending .xml), because Notepad++ then will automatically detect it as XML and select the correct highlighting for you. You may either input the file extension directly in the file name field, or you may select eXtensible Markup Language in the file type dropdown field. For now, simply name your file helloworld.xml and save it into ManiaPlanet\Media\Manialinks\ within your Documents directory.

    Now go into ManiaPlanet, and enter file://Media/Manialinks/helloworld.xml into the address bar which shows up when you move your mouse to the top of the screen – If you now see a white Hello World! printed on a gray background, you successfully created your first ManiaLink Biggrin (If you want to close the ManiaPlanet browser, click on the left most button in the top bar or press the Esc key Wink2 )

    Hint: The file:// method of accessing ManiaLinks only works locally on your machine; nobody else will be able to see your ManiaLink this far. If you upload this file on a webspace, you can call it with its URL as known from normal websites. Before learning how to register a code for a ManiaLink file, we first need to learn how XML in detail works Wink2

    A closer look onto the syntax: The XML header
    If you look on the example from above, you see as first line the so called XML header. This header always introduces an XML file, and tells the application that it actually is XML. The values specified in the header are like a little configuration of the XML file.

    This line will mostly never change at all, so either remember the concrete values, or copy&paste this line in each new XML file you create Wink2 The reason simply is: There is currently no other version than 1.0, using UTF-8 as encoding is the best choice to make your ManiaLink compatible to all languages, and what in detail standalone tags are will be described later.

    Hint: It is very important that the very first character of a file is the < of the XML Header. You are neither allowed to add any spaces or line breaks, nor any other characters in front of it.

    The opening and closing of Tags
    So what about the other three lines of the example? These are the actual XML file, describing our ManiaLink we want to show in ManiaPlanet. Now we see the so called Tags: They always start with an opening angle bracket < and end with a closing one >, everything between these brackets belongs to the tag. At least, the name of the tag is specified. In our example we have two manialink tags and one label tag.

    As you may see, there are in total three different kinds of tags: An opening tag has no slash / in it, and never comes alone. Whenever you have an opening tag like the first manialink one, you will always find its corresponding closing tag: This tag has the same name as the opening one, but has a leading / before the actual name, as seen in the second manialink tag.

    In addition, an opening tag may have so called attributes, specified either as name="value" or name='value'. If you use single quotes or double quotes does not really matter; there is no difference between them at all. Back to our example, we can see, that the opening manialink tag has an attribute named version, which value is set to 1. The label tag, too, has an attribute, here it is called text and its value is Hello World!, which we already saw printed in ManiaPlanet. Opening tags may have several attributes, but they may also have none. Closing tags never have attributes at all.

    The third type of a tag is more a shortcut than really a new type. Look at the label tag in the above example: This one has the slash / at the end of the tag, and therefore is called a standalone tag. It is simply a short form of <label text="Hello World!"></label>, and can always be used if there is nothing else between the opening and closing tag.

    An opening tag with its corresponding closing tag together with everything between them is called a node of the XML document. A node always starts with the opening tag, and ends with a closing tag with the same name, and everything between these tags is called the content of the node. (In case of a standalone tag, this tag alone forms the node, of course.) The content now can be either of simple text, or, what we will mostly see in ManiaLinks, other nodes, i.e. other opening and closing tags. Important is, that a node always is completely contained in another node, where the outer node is called the parent and the inner one the child node. Back to the example, we have the label node as a child of the manialink node. The label node itself has no content, that's why we were able to use the shorter syntax as standalone tag.

    Special tags: Root node, comments and again the XML header
    The manialink node now is a special node: It has no parent, and therefore is called the root node. A valid XML document must always have exactly one root node, and as this node then holds all data of the document as child nodes, it is also called the document node. In ManiaLinks, the root node always is a <manialink>.

    Another special kind of nodes are comment nodes. You can place a comment wherever you can place other nodes, so keep attention to placing it neither outside the root node, nor inside a certain tag e.g. between the attributes. As the name says, you are able to add additional comment to your XML file, e.g. to say which role this certain part of file has in the final ManiaLink, and the XML parser will per definition ignore any comments within the file. The syntax of a comment is slightly different than of the other tags:
    Code:
    <!-- This is a comment -->
    As you can see, a comment starts with < for a tag followed by an exclamation mark and exactly two hyphens, and it ends with again exactly two hyphens and the closing >.

    Hint: You may use any characters within comments you want. There is only one exception: You are not allowed to use -- inside a comment, as this would end the comment and requires the closing > to directly follow. So whatever you print as comment, never print -- in it Wink2

    The last special tag is the XML Header, which always is the very first tag in an XML file and the only exception which is written outside the root node.

    Special characters and their escaping
    Wherever you have characters defining a syntax, you always have the problem in printing these characters themselves. This is the same case in XML: The angle brackets or quotes may disturb the XML syntax, making your complete file invalid. Of course there is a way of making these characters safe, the so called escaping of the characters. In total, only five characters are affected by this problem:
    • < becomes &lt; as in "Lower Than" – Escape outside of tags.
    • > becomes &gt; as in "Greater Than" – Escape outside of tags.
    • " becomes &quot; as in "QUOTe" – Escape in double quoted attribute values.
    • ' becomes &apos; as in "APOStrophe" – Escape in single quoted attribute values.
    • & becomes &amp; as in "AMPersand" – Escape always.
    As you can see, the escaping sequence always starts with an ampersand & (which makes this character a very harmful one Biggrin), followed by an entity and finalized with a semicolon ;. You may always escape these five characters when they are not part of the syntax, but you only must escape them if they occur at the places as specified above. Comments are an exception of this escaping: You don't have to escape anything within a comment, as it gets ignored by default.

    Hint: If you use a PHP generated ManiaLink and want to output the value of a user input, make sure to escape these characters! Otherwise, a simple " or ' may make your ManiaLink invalid and thus not available to anyone anymore. Warning: If you use single quotes for attribute values, make sure to use htmlspecialchars() properly to escape the single quotes, i.e. you have to use the following line:
    PHP Code:
    $escapedText htmlspecialchars($textToBeEscapedENT_QUOTES'UTF-8'); 

    Little Test: Find the errors
    What do you think: Are you already able to write a valid XML file? Let's have a little test: The following code shows an invalid XML file. Can you find all of the errors, which were made in this file?

    Invalid XML file:
    Code:
    <root>
        <!-- This is a negative example of XML -- Do not copy&paste it! -->
        <child1><child2>Some content</child1></child2>
        <input type="checkbox" checked>
        <label link="http://www.example.org/?param1=value1&param2=value2" />
    </root>
    <standalone />
    Spoiler: Errors in the XML file » Show

    Hint: If you want to check the correctness of an XML file, you can simply open it in a normal browser like Firefox or Chrome. (Do not use the Internet Explorer, it cannot help you at all ^^) As long as the browser recognizes that the file is an XML file, it will try to parse the XML and print the document tree. If there is any syntax error in the file, the browser of course will fail to parse it, and will print the first error where the file got invalid.




    Basic positioning of the ManiaLink elements

    Before we finally get known the different elements of a ManiaLink, we still need some more basics: The positioning system. All visible elements can mostly be randomly placed on the screen, without having to worry about other elements. But without knowing the system, it is hard to place anything anywhere.

    Better safe than sorry: The two positioning systems
    Basically you have a full three dimensional coordinate system, with an X-axis for moving elements to the left and right, a Y-axis for moving them up and down, and because elements may overlap with some others, a Z-axis for moving elements in front and behind others. To make things a bit more complicated, you now have the choice between two different coordinate systems: They both are as powerful as the other and you don't have any back draws using either of them, the only differences are the exact values of the axes and in which direction they are directed. Look at the following figures to exactly see these differences:
    [Image: classic.en.png][Image: menu.en.png]

    As you can see, converting between these two systems is very easy; you simply have to divide the values through or multiply with 100, paying special attention to the inverted X- and Z-axes. Nevertheless it is recommended to decide for one of these systems, and to use this system throughout the whole ManiaLink.

    In fact, the difference in the ManiaLinks (except the values) is very small: If you want to use the Classic Positioning, you have to use the attributes pos and size, to use Menu Positioning add an additional n to get posn and sizen. Whenever an element is not placed where you expect it, always make sure you use the correct attributes and the correct orientation. Additionally, check to have version="1" specified in the opening <manialink> tag, as this, too, influences the values of the axes.

    As already said, the Z value specifies which element is covered by which others. The bigger (menu system) or lower (classic system) the value is, the more in front it will appear. Be careful with these Z values: If two elements have the same values, or if an element has an invalid (too big or too low) value, the order of the elements will be mostly random, and it may even change if you for example move your mouse into the top bar of ManiaPlanet. So always make sure to have different Z values if elements overlap each other.

    But why do we have two different coordinate systems, where one would clearly be enough? The reason is mostly historical: Where the Classic Positioning system was used back in the very first version of ManiaLinks, the United ManiaLinks, the newer Menu Positioning was introduced with the Forever ManiaLinks as a separate system, because the old system was not very good suited to be used in the game menus of TrackMania Forever. Nevertheless, the old system was kept to correctly calculate positions of United ManiaLinks, and so they still both exists in ManiaPlanet ManiaLinks as of backwards compatibility. At least, to make things easier, the concrete values of both systems have been made more similar when 16:9 widescreen has been introduced into the ManiaLinks, so that converting between the systems now is no problem any longer.

    Have a break: First examples of positioning
    We are nearly finished with the basics, but before we continue with the last missing piece, the alignment of elements, I want to give you same examples to make the positioning of elements clear. In these examples, I will use Quads for displaying the positions, as a Quad we can simply assign a background color to make it visible. We will learn the different elements available for a ManiaLink later. Let's start with a very basic example:

    Code:
    <quad bgcolor="F00A" />
    We neither have specified a position, nor a size of the Quad. (Only the background color have been specified to make this Quad visible.) Nevertheless, we will get a Quad displayed with this code, because ManiaPlanet applies default values to all missing attributes. The following two lines will produce the exactly same Quad as the above one, with the only difference that we explicitly gave the position and the size:

    Code:
    <quad posn="0 0 0" sizen="100 100" bgcolor="F00A" />
    <quad pos="0 0 0" size="1 1" bgcolor="F00A" />
    We see two things on this example code: First, as already mentioned above, the two positioning systems are equally powerful. Whatever we specify in the menu system (first Quad), we can convert to the classic system (second Quad). Because of this fact, the following examples and the rest of the Tutorial will always use the menu system, but of course you are free to use the classic one instead. The second thing we see are the default values for these attributes: If the position is omitted, all coordinates are set to 0. If the size is omitted, it is set to 100 or 1 respectively for both width and height.

    Code:
    <quad posn="40 -40" sizen="20 20" bgcolor="00FA" />
    If we do not need to set the Z value to something different from 0, we can omit it and only specify to values for X and Y. We specified a position different from zero, so this Quad will not be in the middle of the screen anymore. What do you think: In which direction has the Quad been moved by setting the position (in menu coordinates) to "40 -40"? Copy the line in a ManiaLink file and check your anwser ^^

    Code:
    <quad posn="-160 90 -75" sizen="320 180" bgcolor="0008" />
    This last Quad is an example for inserting a background image into your ManiaLink: It covers the whole screen, and has been set to the very back using the lowest allowed value for Z (using the menu system) Wink2

    The perfect confusion: The influences of halign and valign
    Another thing which is important in context of the basic positioning of elements is their alignment, exactly their halign (horizontal alignment) and valign (vertical alignment). Let's have a look on the following screenshot showing three elements with identical positions, which only differ in the alignment as shown:
    [Image: alignment.png]

    Without knowing the secret, the alignment seems to be confusing. The left aligned element is right of the right aligned one? And the bottom aligned one is above that one with top? The only thing you have to know is that you do not specify where the element should be, but where the position (specified with pos or posn) is. So take another look on the screenshot, and look at where exactly the position is related to the elements. And now, the alignment starts to make sense: When we specify halign="bottom" and valign="right", the positioning point is at the bottom right corner, thus the element is above and right from it. So always remember: halign and valign specify where the positioning point is, not where the element should go Wink2

    By the way, the default value of halign is left and the default value of valign is top. If you omit these attributes, the element will be right and below the specified positioning point.




    How to register a code for a ManiaLink

    [[[TODO: Information about new domain/subdomain system missing...]]]


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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 30.09.2011 15:37 by Marcel.)
    17.08.2011 15:46
    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
    Part 2: Differences to the Forever ManiaLinks
    Every Detail which changed with the ManiaPlanet Upgrade of the ManiaLinks

    This chapter of the tutorial is for all of you, who already know the ManiaLinks from Forever with their details, and know want to "upgrade" their knowledge to the ManiaPlanet ManiaLinks. If you just finished in working through the basics of ManiaLinks, go ahead to the next chapter, as this one will not contain any new information you need so far.

    Basically, no major things changed from Forever to ManiaPlanet: If you have a Forever ManiaLink, it will work quite well in ManiaPlanet without any changes. Nevertheless, there are some details, which you should know about the ManiaPlanet ManiaLinks. So let's start the Upgrade process... Biggrin

    Get ready for the Next Level: ManiaLink Version 1

    The main difference to Forever ManiaLinks is the new version, which have been introduced with ManiaPlanet, and which will enable or change the behavior of some features to make them ready for the future. Whereas Forever ManiaLinks (and the oldschool United ManiaLinks) are now called to have version 0, ManiaPlanet ManiaLinks become the version 1. This version is simply specified in the opening <manialink> tag at the beginning of each ManiaLink, as described at <manialink>. Currently, there are two major features, which will be enabled with having the version 1:

    ManiaLinks get Widescreen
    ManiaLinks with version 0 have a coordinate system, which is based on a 4:3 screen. The development in the last years, nevertheless, moved on to widescreen monitors, having all ManiaLinks stretched from 4:3 to the widescreen to fill the monitore.

    With setting the version to 1, you enable a new coordinate system optimized for 16:9 widescreens. So the new values of the axes of the known positioning systems are as follows:
    [Image: classic.en.png][Image: menu.en.png]

    The main difference next to the changed ratio and therefor the adjusted values, is the more easy conversion between menu positioning and the classic one. Where in version 0 you had to multiply with 64 to get from classic to menu, now you only need to multiply with 100 to do so, thus only shifting the comma two digits to the right Wink2

    Hint: Although ManiaScript works with both Version 1 and Version 0, it always uses the 16:9 coordinate system to calculate any positions. Therefore ensure to always use Version 1 when using a ManiaScript to avoid confusion Wink2

    No Support of line/cell syntax anymore
    Raising a ManiaLink to version 1 will disable any support of United ManiaLinks, also known as the line/cell-syntax. This change is not very dramatical, as United ManiaLinks are outdated since the Forever Upgrade, and not used for several years when developing new ManiaLinks. (If you don't know, what the line/cell syntax is, don't worry about this, you won't need it at all for your ManiaLinks in Forever or ManiaPlanet ^^)

    If you develop a new ManiaLink for ManiaPlanet, it is recommended to use version 1 to make your ManiaLink ready for the future. Only with the new version, you get the simplified coordinates, which match better to the more used widescreen than the old ones.




    New and Changed Attributes

    Regardless of whether you use version 0 or 1, nearly all elements got new attributes to be used in your ManiaPlanet ManiaLinks. At this point of the tutorial, a short list of all new attributes should be given, for more details, please take a look into the reference in the next part Wink2

    List of New and Changed Attributes
    • New attribute version for <manialink>: Specifies the version of the ManiaLink.
    • New attribute background for <manialink>: Enables a transparent background for the ManiaLink.
    • New value center2 for valign of all text based elements: Aligns the text slightly different to the known center.
    • Changed values for style and substyle of all style based elements: List of available styles has been adopted to ManiaPlanet, refer to the ManiaLink Exemple to see the new values.
    • New Attribute id for all positionable elements: Provides access to the element in a ManiaScript.
    • New Attribute ScriptEvents for all visible elements: Enables additional ManiaScript events to be generated for this element.


    ManiaScript Integration

    One of the big new features of ManiaPlanet, and the biggest change by far of the ManiaLinks, are the so called ManiaScripts. Where Forever ManiaLinks always have been static and unchangeable after they have been printed in the game, ManiaScript now enables to bring more dynamic into them. You are now able to react on the users behavior without reloading the ManiaLink at all: Mouse events are generated as much as most keys will do. If the user moves the mouse cursor over an icon, display a little hint what it does. Place a little "X" on your popup window, to let the user close it... Without realoding the ManiaLink. And these are only very basic examples of what is possible with ManiaScripts in ManiaLinks Biggrin

    If you want to know more, read the part ManiaScript in ManiaLinks.




    Replacing AddPlayerID with ManiaConnect

    In TMF you had the possibility to use the attribute addplayerid in some elements to retrieve some information of the player currently viewing the ManiaLink. This feature is no longer available in ManiaPlanet, mostly because it was too easy to manipulate the submitted values, and that’s why, so Nadeo, it is not compatible with the ManiaPlanet concept.

    Instead of addplayerid Nadeo introduced a new mechanism called ManiaConnect to again get access to the player's data. With ManiaConnect, the player explicitly must confirm that he or she wants to publish the data to a certain ManiaLink, and only when done so, the ManiaLink will be able to retrieve this player's data. This new mechanism is completely secure and cannot be manipulated, which opens new possibilities: For example an AdminPanel now needs simply to check the retrieved login, as if this login is "m4rcel", it is definitely me visiting this ManiaLink (or somebody who hacked my account Biggrin ). On the other side, we have to pay with a more complex way to get our hands on these data, making use of the ManiaPlanet WebServices.

    In the last part of this Tutorial, a complete example of a ManiaConnect Authentification is given.




    Other Changes

    Access of local files
    Another new feature is the possibility, to directly access files stored on the local computer using the file:// prefix. The base directory is the ManiaPlanet folder, if you want to call e.g. a ManiaLink stored in Documents\ManiaPlanet\Media\ManiaLinks\test.xml, use "file://Media/ManiaLinks/test.xml". The base path is virtual: It does not only point to the ManiaPlanet directory in your Documents, it also points to the game directory and the game cache. Simply try to call "file://Media/ManiaLinks/Solitaire/index.xml", which actually is located in one of the packs delivered with the game Wink2

    This feature is escpecially useful during the development of a ManiaLink: Instead of having it to upload each time to the server, you may call it directly from your hard drive, as long as the file is placed in the Media\ManiaLinks folder. Of course, when publishing a ManiaLink, all local references have to be removed and replaced by online references, as other players will not be able to request any local files Wink2

    No Animations
    ManiaPlanet does not support the animated Bink format (.bik) anymore, therefore there is no possibility to view any animations on the ManiaPlanet ManiaLinks. As direct consequence, the <video> tag becomes deprecated and has no meaning any longer in ManiaPlanet ManiaLinks.

    UserAgent and other Header changes
    ManiaPlanet does not use the UserAgent Gamebox any longer, instead a more detailled one is used: ManiaPlanet/3.0.0 (2011-09-14). So next to simply know that ManiaPlanet is calling you, it tells you the exact version of the game. This may be helpful if new features of ManiaLinks get added (or bugs get fixed) in the future, so you now from the version if a certain feature is available or not.

    As an additional information, the Header now contains an additional line Accept-Language, where the code of the language is specified, with which the game is running. Refer to the <dico> tag to see a list of available language codes.




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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 23.09.2011 10:16 by Marcel.)
    17.08.2011 15:46
    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
    Part 3: ManiaLink Elements
    A Full Reference of all Elements

    This chapter now will give you a complete reference about all elements of the ManiaPlanet ManiaLinks, including a detailled list of the supported attributes. If you are new to the ManiaLinks at all, you may want to read once through this part of the tutorial, to get a little overview of which elements exist and for what each of them is used for. The intended purpose, nevertheless, is a reference: You do not have to remember all details, there is no test in the end to proove your skills Biggrin

    <manialink>

    The <manialink> tag is the godfather of all tags, it surrounds as root node always all other elements of the ManiaLink. If a ManiaLink does not start with the <manialink> tag, it simply is no ManiaLink Biggrin

    Attributes:
    • version="1"The version of the ManiaLink
      With version you are able to specify the version of the ManiaLink. Depending on this version, the ManiaLink may be displayed slightly different and other features may be available for it. ManiaLinks from TrackMania Forever uses the version 0, which is at the same time the default value of this attribute, whereas ManiaLinks from ManiaPlanet uses the version 1. It is recommended to use version 1 on all new developped ManiaLinks, which should not be compatible to TrackMania Forever, to enable all features of the ManiaPlanet ManiaLinks. See ManiaLink Version 1 for more information.
    • background="0"The visibility of the background
      If background is set to 0, the ManiaLink won't have any background itself, but will use whatever the game shows up behind the ManiaLink. So this feature can be seen as a kind of "transparent background".

    Example:
    A minimal ManiaLink:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <!-- Content of the ManiaLink -->
    </manialink>


    <timeout>

    To save some traffic, all requested ManiaLinks get locally cached by ManiaPlanet, until the game is quit. If now one of these cached ManiaLinks is called another time, ManiaPlanet will used the local copy of the file instead of re-requesting it again from the server. Which may be a nice features for static ManiaLinks is a huge problems for dynamic ones: Last changes will never display, as ManiaPlanet does not reload the file from the server.

    With the <timeout> tag you can disable these caching of the ManiaLink files: The value specified between the tags says the number of seconds, after which the game should re-request the file from the server. Typically this value is set to 0 to force ManiaPlanet to always reload the file from the server.

    Example:
    Skeleton of a ManiaLink including the <timeout> tag:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <!-- Content of the ManiaLink -->
    </manialink>


    <frame>

    A Frame is for grouping several elements together, which got written between the <frame> tags. The Frame itself is not visible, but with its position and scaling factor it influences all containing elements in their display. This means: If the position of the Frame is changed, all elements in this Frame will move along to this change.

    Frames should always be used when several elements of the ManiaLink belongs logically together. For example: If you group all elements of the menu together in a Frame, moving the whole menu a bit down means only to change the position in the Frame; the actual Quads and Labels have not to be changed at all. In addition, you may interlace a Frame into another one. This gives you the possibility to build a kind of hirarchical structure within your ManiaLink.

    Attributes:
    • pos(n)="X Y Z"The position of the Frame
    • scale="factor"The scaling factor of the Frame
    • id="identifier"The ID of the Frame for the ManiaScript – Class CGameManialinkFrame

    Example:
    A Frame to logically combine several Quads:
    Code:
    <frame posn="50 50 0">
        <quad                sizen="20 20" bgcolor="F00A" />
        <quad posn="-20 0 0" sizen="20 20" bgcolor="00FA" />
    </frame>
    This example shows a Frame containing two Quads. These Quads have been positioned directly next to each other, and aligns with the Frame: If we move the Frame, the Quads will do so, too, but they will never get disconnected in this way.




    <format>

    With the <format> tag you are able to define some attributes to be used on other elements as a default format. These predefined formats are applied to all elements of the current Frame in which the <format> is placed and all its subframes. This means, if you place the <format> tag as a direct child into the <manialink> tag, these formats are applied to all elements of the ManiaLink.

    The <format> definitions affects the elements <quad>, <label>, <entry> and <fileentry>, whereas the predefined format always can be overwritten by specifying the same attribute directly in the element’s tag.

    Attributes:
    • bgcolor="RGBA"The background color of the Element – Affects: Quad
      The colors are specified as a four digit hexadecimal number, having the values 0 to 9 and A to F for each digit. The first three digits represent the actual color in their red, green and blue components, and the last digit the transparency of the color, ranging from 0 for transparent to F for opaque.
    • textsize="Number"The text size of the Element – Affects: Label, Entry, FileEntry
    • textcolor="RGBA"The text color of the Element – Affects: Label, Entry, FileEntry
    • focusareacolor1="RGBA"The background color of the Element (without MouseOver) – Affects: Label, Entry, FileEntry
    • focusareacolor2="RGBA"The background color of the Element (with MouseOver) – Affects: Label, Entry, FileEntry
      Both attributes focusareacolor1 and focusareacolor2 define the background color of the element. Thereby focusareacolor1 defines the color to be used when the mouse is not over the element, and focusareacolor2 defines the color when the mouse is currently over it.
    • style="StyleName"The predefined style of the Element – Affects: Label, Entry, FileEntry
      With the style attribute you are able to use the same styles as ManiaPlanet uses in its own menus. For example, with style="CardButtonSmall" you can create the black button which gets white when moving the mosue over it. A list of available styles can be viewed on the ManiaLink Exemple.

    Example:
    Example of using a <format> tag:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1.0">
        <frame>
            <format bgcolor="F00A" />
            <quad sizen="10 10" />
            <quad posn="10 0" sizen="10 10" bgcolor="0F0A" />
        </frame>
        <quad posn="20 0" sizen="10 10" />
    </manialink>
    The <format> sets the default background color to red, and this color gets applied to the first Quad. The second Quad defines a background color for its own, and therefore overwrites the predefined value of the <format>. The third and last Quad is not visible at all, because it is outside the <frame> and so the predefined value of the <format>is not applied to it.




    <quad>

    One of the most important elements of the ManiaLinks is the Quad for displaying images and shapes. It is possible to use the designs of ManiaPlanet itself, so called styles, to better integrate your ManiaLink into the game. Furthermore it is possible to link a <quad> to another ManiaLink or to an external website, whereas this linking can be highlighted when the mouse is moved over the Quad to indicate, that it is linked somewhere. As images a <quad> accepts the formats .jpg, .png, .tga and .dds.

    Attributes:
    • pos(n)="X Y Z"The Position of the Quad
    • size(n)="width height"The size of the Quad
    • scale="factor"The scaling factor of the Quad
    • halign="left|center|right"The horizontal alignment of the Quad
    • valign="top|center|bottom"The vertical alignment of the Quad
    • style="StyleName"The category of the predefined style of the Quad
    • substyle="SubstyleName"The concrete predefined style of the Quad
      To use a predefined style from the game, both attributes style and substyle have to be specified, where style can be seen as the category of the concrete style to be used. A list of all available styles can be viewed on the ManiaLink Exemple.
    • image="image.png"The image of the Quad
    • imagefocus="image.png"The image of the MouseOver effect of the Quad
      You may specify the images to be used for image and imagefocus either with their full URL like http://localhost/image.jpg or as URL relative to the XML file like ./image.jpg. If the mouse is moved into the Quad, the image specified with image is replaced with that from imagefocus if the latter has been specified and the Quad has been linked.
    • bgcolor="RGBA"The background color of the Quad
      As style/substyle, image/imagefocus and bgcolor all affect the Quad in how it is displayed, you cannot use all these attributes at the same time. In detail the style overwrites the images and both overwrites the background color.
    • manialink="ManiaLink"Link to another ManiaLink via its registered code or URL
    • url="website.html"Link to an external website
      To display an external website, ManiaPlanet minimizes itself and opens the default browser of the system.
    • id="identifier"The ID of the Quad for the ManiaScript – Class CGameManialinkQuad
    • ScriptEvents="1"Enables mouse events to be triggered for the Quad

    Example:
    Example of Quad definitions:
    Code:
    <quad sizen="50 10" style="Bgs1InRace" substyle="BgWindow1" />
    <quad posn="0 -60" sizen="50 10"
        image="http://localhost/menu.png"
        imagefocus="http://localhost/menuHover.png"
        manialink="FunTrackers"
    />
    This example shows two Quads, where the first one uses a predefined style of ManiaPlanet and the second one custom images.




    <label>

    Next to the Quads, Labels are the most important element of ManiaLinks to display any kind of texts. This is not limited to a single line of text what the name "label" may imply, but also for complex texts with line breaks. The text to be displayed may either be specified as attribute text or to be written between the <label> tags.

    A special feature of the label (or a curse, whether you want to have it or not Biggrin ) is the automatic translation of certain words and word groups, which exists in the language files of ManiaPlanet. For example, if you write statistics into a label (as the only word), this will be translated to Statistik if a German user views the ManiaLink. If you don't want to have these words translated, simply add another space at the end of the text.

    Attributes:
    • pos(n)="X Y Z"The Position of the Label
    • size(n)="width height"The size of the Label
    • scale="factor"The scaling factor of the Label
    • halign="left|center|right"The horizontal alignment of the Label
    • valign="top|center|center2|bottom"The vertical alignment of the Label
    • text="LabelText"The Text to be displayed in the Label
      You may use any $-formats of ManiaPlanet in the text. As already mentioned, you may also specify the text between the <label> tags instead of using the text attribute.
    • style="StyleName"The predefined style of the Label
      In Labels specifying the attribute style already enables the use of a predefined style of the game. A list of available styles can be viewed on the ManiaLink Exemple.
    • textsize="Number"The text size of the Label
    • textcolor="RGBA"The text color of the Label
      As style and textsize/textcolor both affect the Label, exactly the text of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the text specific attributes.
    • focusareacolor1="RGBA"The background color of the Label (without MouseOver)
    • focusareacolor2="RGBA"The background color of the Label (with MouseOver)
      Both attributes focusareacolor1 and focusareacolor2 define the background color of the Label. Thereby focusareacolor1 defines the color to be used when the mouse is not over the Label, and focusareacolor2 defines the color when the mouse is currently over it.
      As style and focusareacolor1/focusareacolor2 both affect the Label, exactly the background of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the background specific attributes.
    • autonewline="1"Enables the automatic line breaking of the Label
      If autonewline is set to 1 long lines will be automatically breaked to fit the width of the label. Otherwise only line breaks entered into the XML file itself will be used as line break in the ManiaLink, having maybe lines to long for the Label.
    • maxline="Number"Limits the maximum number of lines displayed in the Label
      With maxline you may set a limit of lines to be displayed in the Label. All lines exceeding this limit will bi ignored and not displayed in the Label at all.
    • manialink="ManiaLink"Link to another ManiaLink via its registered code or URL
    • url="website.html"Link to an external website
      To display an external website, ManiaPlanet minimizes itself and opens the default browser of the system.
    • id="identifier"The ID of the Label for the ManiaScript – Class CGameManialinkLabel
    • ScriptEvents="1"Enables mouse events to be triggered for the Label

    Example:
    Example Label using a predefined style and $-formats:
    Code:
    <label style="CardButtonMediumWide" text="A button with a $F00red$g word" />


    <audio>

    As the name already says, you are able to add an Audio file to be played on your ManiaLink using the <audio> tag. This file is displayed as simple start and stop button, with which the user may stop or start the play of the file. As file formats .ogg and .mux are accepted.

    Attributes:
    • pos(n)="X Y Z"The Position of the Audio
    • size(n)="width height"The size of the Audio
    • scale="factor"The scaling factor of the Audio
    • halign="left|center|right"The horizontal alignment of the Audio
    • valign="top|center|bottom"The vertical alignment of the Audio
    • data="audio.ogg"The audio file to be played
    • play="1"Enables the automatic start of the Audio
      If play is set to 1 the audio file will start to play when the ManiaLink has finished loading.
    • looping="0"Disables the looping of the Audio
      If looping is set to 0 ManiaPlanet will stop playing the audio file after it finished once. Otherwise, ManiaPlanet will repeat it in an endless loop.
    • id="identifier"The ID of the Audio for the ManiaScript – Class CGameManialinkControl
    • ScriptEvents="1"Enables mouse events to be triggered for the Audio

    Example:
    Example use of an <audio> tag:
    Code:
    <audio data="http://localhost/audio.ogg" play="1" />


    <music>

    The <music> tag is, too, used to play audio files. Instead of having the user control the play of the file as with the <audio>, <music> plays the file in the background without any possibility for the user to stop it in an endless loop. Again only .ogg and .mux files are accepted in this tag. As an additional feature the music does not stop playing if you change the ManiaLink, if the new one uses the very same audio file in its <music> tag.

    Hint: The <music> tag only works if it is placed as a direct child of the <manialink> tag, i.e. outside of all Frames.

    Attributes:
    • data="music.ogg"The music file to be played

    Example:
    Example of a <music> tag with its only attribute:
    Code:
    <music data="http://localhost/music.ogg" />


    <include>

    The name of the tag <include> already says, that it will include another XML file into the current ManiaLink. This enables the possibility to extract often used elements like the menu into a separate file, and to include it in all actual ManiaLinks: If you want to change the menu, you only have to change the separate file rather than change all files which uses this menu Wink2

    The inclusion of other files is limited to one level. Thus, you can only include a file from within the "main" file, but you are not able to include another file in the included file. The reason is to avoid a cycle of inclusions: If file A includes file B, and file B now is able to include file A, you get an endles recursion of included files.

    Another point is, that the included file has to be a complete and valid XML file, and not a complete ManiaLink. This means, the included file must have an XML header and a single root node (mostly a <frame> which contains the actual elements to be included), and must not have a <manialink> tag itself. You can imagine the including process like cutting the main ManiaLink into two pieces, and pasting in the file to be included. Having an additional <manialink> at this point would make no sense at all Wink2

    Hint: Please keep in mind, that including a file using an <include> tag increases the time until the ManiaLink has been completed loading, as the included file has to be requested separatly from the server, so do not overuse this tag. If you have a dynamic (i.e. PHP based) ManiaLink, you should always consider to prefer the include or require commands of PHP instead.

    Attributes:
    • url="include.xml"The URL of the file to be included

    Example:
    Main ManiaLink file:
    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>
    File include.xml to be included:
    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>
    The second code snippet shows the file to be included. As already mentioned, it does not have a <manialink> itself, but needs to have a <frame> surrounding the actual elements to be included, as a valid XML file only is allowed to have a single root node.




    <entry>

    Another possibility to interact with the user is to show an input field, called Entry in ManiaLinks, where he or she can input any value. Of course, an Entry only makes sense on dynamic ManiaLinks, where a script on the server (e.g. written in PHP) is able to handle the inputted value. The use of an <entry> is pretty simple: You specify an unique name, and wherever this name appears in a link of a Label or a Quad it is replaced with the current value of the Entry. You should remember, that an Entry always accepts string values, thus you have to check on server side, if for example you only want to have numbers as values.

    Attributes:
    • pos(n)="X Y Z"The Position of the Entry
    • size(n)="width height"The size of the Entry
    • scale="factor"The scaling factor of the Entry
    • halign="left|center|right"The horizontal alignment of the Entry
    • valign="top|center|center2|bottom"The vertical alignment of the Entry
    • style="StyleName"The predefined style of the Entry
      A list of available styles can be viewed on the ManiaLink Exemple.
    • textsize="Number"The text size of the Entry
    • textcolor="RGBA"The text color of the Entry
      As style and textsize/textcolor both affect the Entry, exactly the text of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the text specific attributes.
    • focusareacolor1="RGBA"The background color of the Entry (without MouseOver)
    • focusareacolor2="RGBA"The background color of the Entry (with MouseOver)
      Both attributes focusareacolor1 and focusareacolor2 define the background color of the Entry. Thereby focusareacolor1 defines the color to be used when the mouse is not over the Entry, and focusareacolor2 defines the color when the mouse is currently over it.
      As style and focusareacolor1/focusareacolor2 both affect the Entry, exactly the background of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the background specific attributes.
    • name="EntryName"The unique name of the Entry
      As already mentioned, the name of the Entry is very important: Wherever this name occurs in a link, it is replaced with the current value entered by the user.
    • default="value"The default value of the Entry
      When loading the ManiaLink, the Entry is initialized with the value specified with default. As long as the user does not enter any other value, this default value will be displayed in the Entry.
    • autonewline="1"Enables the automatic line breaking of the Entry
      If autonewline is set to 1, the entered value is automatically broken into a new line if it exceeds the set width of the Entry. This is helpful if you expect larger inputs from the user.
    • id="identifier"The ID of the Entry for the ManiaScript – Class CGameManialinkEntry
    • ScriptEvents="1"Enables mouse events to be triggered for the Entry

    Example:
    Simple example of an Entry and a link with its value:
    Code:
    <entry sizen="50 5" style="TextValueSmall" name="inputValue" default="Hello World!" />
    <label posn="0 -10" style="CardButtonMedium" text="Send Value" url="http://localhost/script.php?value=inputValue" />
    This example shows an Entry with the name inputValue, and a Label which sends its value to a script: The inputValue of the link will be replaced with the current value of the Entry. Please refer to the Advanced Example of Entry and FileEntry for additional information.




    <fileentry>

    The <fileentry> works the same way as <entry> does, with the only difference that the user does not enter a value, but select a file to tbe uploaded to the server. Like the Entry, the FileEntry uses its unique name to Again, this tag only makes sense on dynamic ManiaLinks where a server script in the background can handle the uploaded file.

    As soon as the user clicks into the field of FileEntry, a file selecting dialog will pop up, having the user to choose a file from his computer. This file then is transmitted using a POST request, see the Advanced Example of Entry and FileEntry for additional information.

    Hint: Always check what file the user tries to upload, before finally saving it on the server. Never ever save any files without checking them, as this is a huge security risk!

    Attributes:
    • pos(n)="X Y Z"The Position of the FileEntry
    • size(n)="width height"The size of the FileEntry
    • scale="factor"The scaling factor of the FileEntry
    • halign="left|center|right"The horizontal alignment of the FileEntry
    • valign="top|center|center2|bottom"The vertical alignment of the FileEntry
    • style="StyleName"The predefined style of the FileEntry
    • textsize="Number"The text size of the FileEntry
    • textcolor="RGBA"The text color of the FileEntry
      As style and textsize/textcolor both affect the FileEntry, exactly the text of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the text specific attributes.
    • focusareacolor1="RGBA"The background color of the FileEntry (without MouseOver)
    • focusareacolor2="RGBA"The background color of the FileEntry (with MouseOver)
      Both attributes focusareacolor1 and focusareacolor2 define the background color of the FileEntry. Thereby focusareacolor1 defines the color to be used when the mouse is not over the FileEntry, and focusareacolor2 defines the color when the mouse is currently over it.
      As style and focusareacolor1/focusareacolor2 both affect the FileEntry, exactly the background of it, in how it is displayed, you cannot use both of them at the same time. In detail the style will overwrite the background specific attributes.
    • name="FileEntryName"The unique name of the FileEntry
      The name of a FileEntry has the same task as in an Entry: Wherever this name appears in a link, it is replaced with the name of the selected file of the FileEntry.
    • folder="path"The path of the base folder
      With the folder attribute you may help the user to find the wanted file to be uploaded to the ManiaLink, as you set the base directory the user is able to browse. This folder is always relative to the ManiaPlanet folder in the Documents directory, and the user is not allowed to browse any upper folders as the specified one. If for example you only want to have Maps uploaded to the ManiaLink, specify Maps as base folder, but keep in mind, that the user still is able to upload any file he or she wants: Double check on the server!
    • default="value"The default value of the FileEntry
      The value of the default attribute is displayed as long as the user did not choose a file from his computer.
    • autonewline="1"Enables the automatic line breaking of the FileEntry
      autonewline has the same effect as in an <entry>, but as filenames won't get very long in most cases, you won't need this attribute very often.
    • id="identifier"The ID of the FileEntry for the ManiaScript – Class CGameManialinkFileEntry
    • ScriptEvents="1"Enables mouse events to be triggered for the FileEntry

    Example:
    Basic example of an FileEntry and how the file is send to a server script:
    Code:
    <fileentry sizen="50 5" style="TextValueSmall" name="inputFile" folder="Maps" default="Choose Map..." />
    <label posn="0 -10" style="CardButtonMedium" text="Send File" url="POST(http://localhost/script.php?file=inputFile,inputFile)" />
    This example is pretty much the same as that one for <entry>, with the only different that we need to use the POST() method to link to another ManiaLink or website. Again, please refer to the Advanced Example of Entry and FileEntry to have a more detailed description for this.




    <dico>

    With the <dico> tag and some <language> tags, you are able to translate your ManiaLink into other languages, making it possible that an English speaking player sees an English version, whereas a German player has a German version. The actually used language is selected by the game: If the player's language (which he or she selected in the configuration of ManiaPlanet) is available, that one will be used, otherwise ManiaPlanet will try to use the English version. If both do not exist, nothing is displayed as translation, so ensure that at least the English language is complete Wink2

    Making a ManiaLink multilingual is very easy: Instead for example specifying the exact text in a <label>, you only use a ID for it and give for each language in which your ManiaLink should be available the translation. To illustrate it better, an example should be given:

    Example:
    A simple but multilingual ManiaLink:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
        <timeout>0</timeout>
        <!-- The ManiaLink elements itself -->
        <label posn="-20 0" textid="example" />
        <label posn="-20 -10" textid="thanks" />
        <quad sizen="10 5" imageid="img" />

        <-- The translations of the 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>
    So what we can see in the first part of the ManiaLink are the elements, which have been explained above. The only different is, that instead e.g. text the attribute textid is used. This tells ManiaPlanet, that it has to look up the specified ID in the <dico> tag and replace the ID with the actual translation. In fact, you simply have to add "id" to the name of the attribute, to enable the translation feature for it. The following attributes support to be multilingual:

    List of supported attributes:
    • <quad>image, imagefocus, url, manialink
    • <label>text, url, manialink
    • <audio>data
    • <video>data
    The second part of the example shows the actual translation of the IDs, enclosed by the <dico> tag. For each language to be supported, add a <language> tag to the <dico>, holding as only attribute id the ID of the language, you want to translate. Which ID you have to use for which language shows the following list:

    List of language codes:
    • czCzech
    • daDanish
    • deGerman
    • enEnglish
    • esSpanish
    • frFrench
    • huHungary
    • itItalian
    • jpJapanese
    • krKorean
    • nbNorwegian
    • nlDutch
    • plPolish
    • ptPortuguese
    • pt_BRBrazilian Portugese
    • roRomanian
    • ruRussian
    • skSlovak
    • trTurkish
    • zhChinese
    For each language, you now have to add all IDs to be translated as child tags to the <language>, as shown in the example. As the IDs to be translated become tag-names, it is best if you only choose IDs, which begin with a letter, and may be followed bay other letters, numbers or the underscore _. Try to avoid any special characters within these IDs, as they may invalidate the XML syntax, and thus making the whole ManiaLink file invalid. The translation itself, denoted between the ID-tags, may contain whatever character you want, but keep in mind that the characters "<", ">" and "&" have to be replaced by "&lt;", "&gt;" and "&amp;" respectively, to keep the XML syntax valid. Also remember saving the XML file in UTF-8 as soon as you use special characters like German umlauts "Ä", "Ö", "Ü" etc. Wink2




    <script>

    The <script> tag is maybe the most simple tag, and at the same point the most powerful element of a ManiaLink: With this tag, you may include a ManiaScript into your ManiaLink. The use of it is very intuitive: The ManiaScript itself gets written between the <script> tags. But as some elements of the ManiaScript may invalidate the XML syntax, you have to put the ManiaScript additionally into an XML-comment.

    It is possible, to use several <script> tags in your ManiaLink. These parts will get clued together on loading the ManiaLink, and executed as one big ManiaScript. So there is no different in using a ManiaScript in three parts, or to include it as one big part e.g. at the end of the ManiaLink.

    For additional information, please look at the corresponding part of the Tutorial ManiaScript in ManiaLinks.

    Example:
    A simple example of a complete ManiaLink using a 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>
    At this point, I do not want to explain the ManiaScript in detail. Save this code as a new XML file, open it in the ManiaPlanet Browser, and click on the Quad Wink2 This example should only demonstrate, how to integrate a ManiaScript into a ManiaLink: The ManiaScript itself has to be surrounded with an XML-comment, to keep the XML file itself valid.




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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 04.10.2011 17:53 by Marcel.)
    17.08.2011 15:46
    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
    Part 4: ManiaScript in ManiaLinks
    Manipulate the ManiaLink with a ManiaScript

    ManiaScript is an independent language developed by Nadeo, to make different parts of the ManiaPlanet game more dynamic. This also applies to ManiaLinks: With ManiaPlanet, you have the possibility to manipulate and change the ManiaLink after it has been printed, and to react on the users behavior like mouse movement or keyboard inputs. Thus basically you can see ManiaScript the same way for ManiaLinks, as JavaScript is for HTML. This part of the Tutorial will exactly explain these ManiaScripts in ManiaLinks.

    Hint: The Tutorial will not explain any syntax basics about ManiaScripts, so if you are not knowing anything about ManiaScripts yet, please refer to a ManiaScript Tutorial to get introduced into them. The following parts will require basic knowledge about ManiaScript.

    Access of ManiaLink Elements

    One of the most important things of ManiaScript in ManiaLinks is the manipulation of the elements of the ManiaLink. Before we can change any of the attributes of an element, we need to get our hands on this, i.e. we need to get the object instance, which represents the ManiaLink element. Basically, there are two different ways to get acces to an element of the ManiaLink, both together use the global variable Page:
    • Page.MainFrame.Controls[ElementID]Access element over its parent frame
      The first way of getting your hands on the instance of a ManiaLink element is to access it over its parent frame. The field MainFrame of type CGameManialinkFrame represents the <manialink> tag of the ManiaLink, and as the typename already says, it is simply seen as another Frame. A Frame now have a field Controls, which is an associative array mapping ControlIDs (of type Text) to the actual elements (of type CGameManialinkControl, see below for more information). The IDs are exactly those, which have been specified with the id attribute within the elements, so if you want to access an element, make sure it has an unique ID Wink2

      As Controls is an array, you also have the possibility to access its elements with their index. For example, Page.MainFrame.Controls[3] would give you the 4th child of the <manialink> (Remember that the first element has index 0 Wink2 ), also if it has no named ID itself. Nevertheless, specifying IDs for your elements is the better way, as changing the order of the elements or adding another one may break any indizes you use to access these elements. So be careful with this Wink2

      Hint: In the Controls array, you only find the direct childs of the Frame, i.e. all direct childs of <manialink> in case of Page.MainFrame. This means if you have a Frame, you only will see this Frame itself in the Page.MainFrame.Controls array, but none of the elements contained in the Frame. If you want to access an inner element, you have to read the Frame (and cast it to CGameManialinkFrame), and then call this Frame's Controls array to finally get the wanted element. In the example below, this situation have been shown for better understanding Wink2
    • Page.GetFirstChild(ElementID)Searching for the element
      The second way on accessing an element of the ManiaLink is the Page.GetFirstChild(ElementID) method call: You specify the ID of the Element you want, and the method will search for this element in the whole ManiaLinks. This means, if the wanted element have placed into Frames, this method will still find it.

      Instead of searching all elements of the ManiaLink using Page.GetFirstChild(), you may, too, use this method on a Frame to only search the Frames direct and indirect childs for the specified ControlID. Especially Page.MainFrame.GetFirstChild() is aquivalent to Page.GetFirstChild().


    After explaining the ways of accessing the elements, a short example should help to make everything clear, especially the issue with nested frames of the first way.

    Example:
    Example of accessing some elements of the ManiaLink:
    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;

    // Access elements over Controls Array
    quad = (Page.MainFrame.Controls["exampleQuad"] as CGameManialinkQuad);

    // We cannot access exampleLabel and exampleEntry directly over Controls,
    // we have first to get the Frame, and call its Controls and so on.
    frame = (Page.MainFrame.Controls["outerFrame"] as CGameManialinkFrame);
    label = (frame.Controls["exampleLabel"] as CGameManialinkLabel);

    // Now we set frame to the innerFrame element, to access the exampleEntry
    frame = (frame.Controls["innerFrame"] as CGameManialinkFrame);
    entry = (frame.Controls["exampleEntry"] as CGameManialinkEntry);


    // The same elements accessed via GetFirstChild()
    quad = (Page.GetFirstChild("exampleQuad") as CGameManialinkQuad);
    label = (Page.GetFirstChild("exampleLabel") as CGameManialinkLabel);
    entry = (Page.GetFirstChild("exampleEntry") as CGameManialinkEntry);
        --></script>
    </manialink>
    So what is the advantage of the Controls array, if the method GetFirstChild() seems to be much simpler? It is the full availability of the element tree: You still see, that the innerFrame is inside the outerFrame, and exactly this can be helpful. Imagine, you have a Dropdown list, where you place all items of the list inside a separate frame. Instead of accessing all elements via an unique ID using GetFirstChild, you may simply loop with a foreach over all elements of the Controls array of the Frame to get all items of the list (and you may even omit IDs for these list items). This is not possible with GetFirstChild, as you don't have the element tree which says, that all elements in a particular frame are list items.

    Another point of the example, which may confuse you, is the typecasting of the elements: Whenever an element is read, it is casted to its actual type. The reason for this is, that the Controls array and the GetFirstChild method always return an object of the class CGameManialinkControl. But as we may want the extended features of the elements, we have to cast them to their actual type. Only with casting the outerFrame to CGameManialinkFrame, we are able to use its Controls array to access the innerFrame. A detailled description of the available classes can be found below.




    ManiaLink Specific Classes

    For manipulating the elements of a ManiaLink, ManiaScript now provides different classes helping you. The base class, which is always returned by the Controls array and GetFirstChild(), is CGameManialinkControl. This class provides basic fields and methods to change the position and visibility of the element. All other classes are derived from this base class, and extend the possibilities. For example, CGameManialinkLabel has a method SetText() to update the displayed text. The following listing shows each of the available classes for the ManiaLink elements, which element they represent, and which class they are derived from.

    CGameManialinkControl

    Fields:
    • Text IdThe ID of the Control
    • Real PosnXThe X position in the Menu coordinate system of the Control
    • Real PosnYThe Y position in the Menu coordinate system of the Control
    • Real PosnZThe Z position in the Menu coordinate system of the Control
    Methods:
    • Void Hide()Hides the Control from the ManiaLink.
    • Void Show()Shows the Control on the ManiaLink if it has been hidden.
    • Void Unload()Completely removes the Control from the ManiaLink. The Control is not available any longer, and accessing the variable afterwards will result in an error.

    CGameManialinkFrame
    Extends: CGameManialinkControl
    Represents: <frame>

    Fields:
    • Array CGameManialinkControl[Text] ControlsThe Controls this Frame contains
    Methods:
    • CGameManialinkControl GetFirstChild(Text)Provides access to child elements of the Frame
      Parameters:
      • Text – The ControlID of the element

    CGameManialinkQuad
    Extends: CGameManialinkControl
    Represents: <quad>

    Methods:
    • Void ChangeImageUrl(Text)Changes the Image of the Quad by specifying a new URL.
      Parameters:
      • Text – The new URL to be shown in the Quad.
      Hint: The URL must be an absolute URL and the Quad must already have an image set with the image attribute to make this method work.


    CGameManialinkLabel
    Extends: CGameManialinkControl
    Represents: <label>

    Methods:
    • Void SetText(Text)Updates the Text currently shown in the Label.
      Parameters:
      • Text – The new Text to be displayed in the Label.

    CGameManialinkEntry
    Extends: CGameManialinkControl
    Represents: <entry>

    Fields:
    • Text ValueThe current Value of the Entry

    CGameManialinkFileEntry
    Extends: CGameManialinkEntry
    Represents: <fileentry>

    Fields:
    • Text FullFileName [Read-only] – Provides the full path of the currently selected file of the FileEntry

    Hint: Another tag, which does not have its own class, is <audio>: This tag is represented directly by CGameManialinkControl and therefore only has the basic manipulation of the position and visibility. The <manialink> tag is a CGameManialinkFrame and always accessable over Page.MainFrame. Not positionable tags like <music> or <format> are not accessable via ID at all, as changing e.g. their position would make no sense.




    Event Handling

    Now that we know how to manipulate certain elements of the ManiaLink, of course we still need to know how to react on the user's input like mouse movement and clicks and key presses. For this, ManiaScript provides different kinds of events, which exactly represents these actions of the user:
    • MouseClickThe user clicked with the left mouse button on an element.
    • MouseOverThe user moved the mouse cursor into an element.
    • MouseOutThe user moved the mouse out of an element.
    • KeyPressThe user pressed a key.
    There are some limitations on the events, which may hinder Events to be handled in a ManiaScript:
    • Only events which are not handled by the element itself may be handled in a ManiaScript. This means, that e.g. an Entry will never create any KeyPress events, as it handles them itself by inserting the pressed character into the field. A linked Quad or Label will never create any mouse events.
    • The mouse events (MouseClick, MouseOver and MouseOut) requires to have ScriptEvents set to 1 to be created for this element. If an element does not have ScriptEvents set to 1, it will not create any mouse events.
    • Each event is triggered only once, the z-order decides about which element finally "gets" the event. For example a MouseClick will only be handled from the element which is above all others, i.e. from that one with the highest z-value in case of menu positioning or lowest z-value in case of classic positioning. All other elements behind this first one will not see the MouseClick at all.
    Let's have a look on a typical event handling loop of a ManiaLink-ManiaScript:

    Event handling of ManiaLink-ManiaScript:
    Code:
    main() {
        // #1 Execute on initialization
        while(True) {
            // #2 Execute always
            foreach(Event in PendingEvents) {
                switch(Event.Type) {
                    case CGameManialinkScriptEvent::Type::MouseClick: {
                        // #3 Execute on MouseClick event
                    }
                    case CGameManialinkScriptEvent::Type::MouseOver: {
                        // #4 Execute on MouseOver event
                    }
                    case CGameManialinkScriptEvent::Type::MouseOut: {
                        // #5 Execute on MouseOut event
                    }
                    case CGameManialinkScriptEvent::Type::KeyPress: {
                        // #6 Execute on KeyPress event
                    }
                }
            }
            yield;
        }
    }
    Basically we have six positions, where we can add some code to handle the different situations. If you want to execute some code once right after the ManiaLink finished loading, for example to hide some elements which should be showed later, do it outside the endless loop at position #1. In contrast to that, the code at position #2 will always be executed, this means right after it is done with this code, it will restart it again and again. This is most suited for (time based) animations, as the more often they get executed the better and smoother they become. The foreach loop now is executed for each actual event triggered by any of the elements. You may use a switch to distinguish between their concrete types, as shown in the example with the positions #3 to #6. But this is up to you, finally, the only things you need is the infinite while loop, the foreach to handle all new events, and the yield at the end of the infinite loop.




    Complex Example

    To make all this stuff a little bit clearer for you, I want to give you a full example, which demonstrates the use of a ManiaScript in a ManiaLink. The example is very basic, but still shows how to handle the Events without interfere an animation loop. If you have problems with understanding the example, you may simply copy&paste the XML code into a file, modify it a little bit and see in what these changes will result.

    In detail, our example should display a continuous animation, which will be a simple Quad moving in a circle. Additionally, this Quad should react on the user's mouse: When receiving a MouseClick, MouseOver or MouseOut, the Quad should change its color to visualize these events. Let's have a look on the XML code itself:

    XML code of the ManiaScript example:
    Code:
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1" background="0">
        <timeout>0</timeout>
        <!-- The container is used to change the positions of all Quads simultanously -->
        <frame id="container">
            <!-- The target Quad triggers the Mouse events we want to react on -->
            <quad id="target" posn="0 0 5" sizen="20 20" ScriptEvents="1" />
            
            <!-- As we cannot change the bgcolor of a Quad, we use multiple Quads and only display that one with the wanted color -->
            <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

    // Shows the Quad with the specified ID and hides all others (except the 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();
            }
        }
    }

    // Initializes the animation
    Void Initialize() {
        // Save the time of initialization as we need it for the animation
        declare Integer StartTime for Page = CurrentTime;
        // Show the red Quad as default on initialization
        ShowQuad("red");
    }

    // Calculates the current animation state and applys it to the container
    Void Animate() {
        // Make the previously saved StartTime available in our function
        declare Integer StartTime for Page;
        // Calculate the time difference in seconds
        declare Real TimeDiff = (CurrentTime - StartTime) / 1000.;
        
        // Update the current Position of the Container to finally animate it
        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>
    The first problem we need to solve is that we cannot change the bgcolor of a Quad out of a ManiaScript. That's why we use several Quads with the same size and same position but different colors, and we will only show that one which has the currently wanted color. Those Quads have the IDs red, green and blue.

    Because we do not want to observe these three Quads for the mouse events, a fourth Quad target has been added, having the same size and same position, but have been placed in front of all other Quads (so it will definitely catch all the mouse events) and without any color to make it invisible. This Quad is the only element with ScriptEvents="1", so whenever a mouse event has been triggered, we can be sure it is from this Quad – We don't have to check the ControlId at all in this example.

    As all these Quads always should have the same position, we put all of them in a Frame called container: We will always move this container to animate the Quads, so we can be sure that they will always stay on top of each other.

    So let's have a look on the ManiaScript itself, which is the important part of our example. The script has mainly three functions: ShowQuad(ControlID) will expect either of our visible Quads and will exactly show this one Quad and hide all others, making sure our target will always be shown to be able to catch our mouse events. So for example ShowQuad("blue"); will show our blue Quad instead whatever Quad have been shown before. Initialize() is called once when the ManiaLink has been finished loading to initialize any values we need, in our case saving the CurrentTime we’ll need later and showing the red Quad. Animate() will calculate and update the current position of the Quads to fit our circle animation, based on the time which have been passed (TimeDiff, in seconds). This function will be called whenever we have nothing else to do to make the animation as smooth as possible.

    The main() part of the ManiaScript now implements the concrete behavior "around" our functions. As first line, we see the call of Initialize();, so we know that we will have the red Quad shown as soon as we enter the infinite loop. The infinite loop now is divided in three parts:
    1. Update the animation with the call of Animate().
    2. Handle any mouse events which arrived since the last time. Depending of the actual type of the event to be handled, we show a different colored Quad, so that we can observe what events have reached the Quad. For example the Quad will become blue when you click on it, but will become red once you move the mouse outside of it – Following the Quad with your mouse will keep it blue Wink2
    3. yield gives back the control to ManiaPlanet, so the game will be able to re-fill the PendingEvents array (if some events have been triggered) and do other stuff... like finally displaying the changed position of our Quad Wink2 As soon as ManiaPlanet is done, the control is taken back to the ManiaScript (which will take only milliseconds so far) starting the next run of the infinite loop.
    We can see that one event type is not handled at all: KeyPress. Take it as a little exercise: Expand the ManiaScript (and the ManiaLink itself) to additionally change the color of the Quad, let’s say to yellow, if the user presses any key Wink2




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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 23.09.2011 10:17 by Marcel.)
    17.08.2011 15:46
    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
    Part 5: Tips & Tricks
    Selected Topics which are Worth Knowing

    The last chapter of this Tutorial will explain some selected topics, which either do not match into the other chapters, or simply are too much to write them there. The following parts are not related to each other, so you may read those parts which you are interested in, and skip the others.

    Advanced Example of Entry and FileEntry
    PHP knowledge required.

    With Entrys and FileEntrys the user has the possibility to send entered values and files to the ManiaLink. This section will now explain with a more advanced example, how you have to use these elements and how you finally get your hands on the transmitted data.

    Advanced example for Entry
    The use of an Entry is very easy, as the values can directly be appended to the URL as additional parameters.

    XML code:
    Code:
    <entry sizen="10 5" style="TextValueSmall" name="inputValue" default="Hello World!" />
    <label posn="0 -20" style="CardButtonMedium" text="Link with value" manialink="ManiaLink?value=inputValue" />
    Handling script:
    PHP Code:
    <?php
    // Read the passed value
    $value $_GET['value'];

    // Escape the value to make our ManiaLink safe against manipulation
    $value htmlspecialchars($value);

    // Output the ManiaLink
    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 the XML file, we have an <entry> with the name inputValue. Whereever this name appears in a URL of a link, it is replaced with the current value of the Entry. So in our case, the inputValue of the link in the Label is replaced by whatever the user entered into the Entry. Or in other words: The content of the Entry is passed as parameter with the name value to our script, as specified with ?value=inputValue.

    In the script we now simply have to read the passed parameter using the $_GET array, and afterwards generate a full ManiaLink as output, where the passed value is printed as label.

    Advanced example for FileEntry
    The use of a FileEntry is a little bit more complex, as we cannot pass the file as URL parameter, but have to POST it.

    XML code:
    Code:
    <fileentry sizen="50 5" style="TextValueSmall" name="inputMap" folder="Maps" default="Select Map..."/>
    <label posn="0 -20" style="CardButtonMedium" manialink="POST(ManiaLink?map=inputMap,inputMap)" text="Send Map"/>
    Handling script:
    PHP Code:
    <?php
    // Read the passed file
    $name $_GET['map'];
    $file file_get_contents('php://input');

    // Save the passed file on the server
    // WARNING: Always check the file uploaded by the user to be what you expected.
    // This is not done in this example, what is a huge security risk!
    file_put_contents("maps/{$name}"$file);

    // Get the filesize for outputting it
    $size filesize("maps/{$name}");
    // Escape the filename
    $name htmlspecialchars($name);

    // Output the ManiaLink
    header('Content-Type: text/xml');
    echo <<<EOT
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
    <manialink version="1">
    <timeout>0</timeout>
    <label text="Received Map: 
    {$name} (Size: {$size})" />
    </manialink>
    EOT;
    ?>
    The XML code is very similar to that one for the Entry example, the only important different is the value of the manialink attribute of the label. Instead of having the ManiaLink to be called, we now see a POST(ManiaLink?map=inputMap,inputMap). With this we now send the file of the FileEntry inputMap (behind the comma) to the ManiaLink ManiaLink?map=inputMap (infront the comma). But why dies the FileEntry occurs twice in this link? The reason is, that we will loose the filename if we only send the file itself. But as we need the filename to save the file on the server, we have to pass it separatly to the script. (This also means, if you do not need the filename itself, you may omit the parameter in the URL, making it to a POST(ManiaLink,inputMap).)

    The script itself now reads the filename and the file contents, saves the file on the server and prints the name and the size of the received file as new ManiaLink. The code is not very difficult once we managed to send out file using a POST request Wink2

    Hint: Another time I want to state, that you always should check what file is uploaded to the server! For our example, a simply check would be to validate the filename to end with .Map.Gbx, a better but more difficult to implement security check would be to read and validate the XML header of the Map.




    ManiaConnect Authentification
    PHP knowledge required.

    ManiaConnect is a system, with which you are able to retrieve detailed information of the player currently visiting the ManiaLink – assuming that he granted access to his or her data. These information are secure and cannot be manipulated at all, so if you have the login m4rcel, you can be sure that I am visiting your ManiaLink (or somebody hacked my account Biggrin ).

    ManiaConnect is part of the ManiaPlanet Web Services (MPWS). The following preconditions must be fulfilled by your webspace to be able to use these services and ManiaConnect in particular:
    • PHP 5.3 or newer
    • CURL extension
    • JSON extension
    If your webspace supports these requirements, go ahead and download the latest version of the MPWS SDK for PHP.

    Creating an API user for the MPWS
    Before we can request any data, we have to create a new API user with which we will be able to use the MPWS. Creating a new API user is very simple:
    1. Visit developers.maniaplanet.com and login with your ManiaPlanet account.
    2. Click on Web Services at the top of the page, and use the button Create a new API user.
    3. Do what the page prompts you to do, until you have created the API user, landing on the Manage your API user page.
    4. Click on the button Create a ManiaConnect application: Again, the dialog is self-explanatory in what values are to be entered. Important is the Redirection URI: This is the URL, which should be redirected to after the user permitted access to his or her data.
    5. Done.


    Request Data with ManiaConnect
    Now that we have created our API user and a ManiaConnect Application for it, we are ready to write a ManiaLink which uses the MPWS to display the user's information. The example below demonstrates this by printing the Nickname of the current user.

    ManiaLink using ManiaConnect to show the Nickname:
    PHP Code:
    <?php
    // Change these values to match your MPWS user
    define('MPWS_USER''mpws_user');
    define('MPWS_PASS''mpws_pass');
    define('MPWS_SCOPE''basic');

    // Include the MPWS files
    require('autoload.php');

    try {
        
    // Try to retrieve the data of the player
        
    $mpwsPlayer = new \Maniaplanet\WebServices\ManiaConnect\Player(MPWS_USERMPWS_PASS);
        
    $player $mpwsPlayer->getPlayer();

        if (!
    $player) {
            
    // If $player equals false, we need the player to grant access to his or her data,
            // so we need to print the LoginURL
            
    $loginURL htmlspecialchars($mpwsPlayer->getLoginURL(MPWS_SCOPE));
            
    $label '<label style="CardButtonMedium" text="Authentificate" manialink="'.$loginURL.'" />';
        } else {
            
    // If $player is not false, the player allowed accessing his or her data,
            // so we are able to e.g. print the Nickname
            
    $nickname htmlspecialchars($player->nickname);
            
    $label '<label sizen="100 5" halign="center" text="Your Nickname: '.$nickname.'" />';
        }
    } catch (\
    Maniaplanet\WebServices\Exception $e) {
        
    // Accessing ManiaConnect or the WebServices in general has failed.
        // In this case, we simply print the error message.
        
    $message htmlspecialchars("[{$e->getHTTPStatusCode()} {$e->getHTTPStatusMessage()}{$e->getMessage()}"ENT_QUOTES'UTF-8'); 
        
    $label '<label sizen="100 5" halign="center" text="Exception: '.$message.'" />';
    }
    // Output the ManiaLink
    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;
    ?>
    Most important is that the Player class is instantiated before the first output, because it will initialize a session (using the PHP's internal session mechanisms). You then simply try to access the player's information using the getPlayer() method: If you are allowed to do so, you will get the data of the player, if not, false is returned instead. According to the returned value, we therefore are able to decide if we already can print the Nickname, or if we have to get the permission first.

    If we don't have the permission to get the player's data, we need to call getLoginURL() to get the URL to the ManiaLink on which the player can grant access to his or her data. We do not take care of this, simply print this URL e.g. as button, and "wait" that the user is redirected back to our ManiaLink: If he allowed accessing the data, we will get them and thus printing the Nickname, otherwise the button is displayed another time.

    The Scopes of ManiaConnect
    One thing, which has not been explained so far, is left: The scopes of ManiaConnect. The scope simply says which data you want to get access to, and therefore which data the player must permit to be accessed.

    List of available scopes
    • basic – Method: getPlayer()Basic information like login, nickname and zone
    • buddies – Method: getBuddies()List of the buddies
    • dedicated – Method: getDedicated()List of the dedicated server
    • email – Method: getEmail()Email address
    • manialinks – Method: getManiaLinks()List of the registered ManiaLink codes
    • online_status – Method: getOnlineStatus()Online status
    If using several scopes, simply separate them with spaces.

    Hint: Do only request those scopes you really need access to. For example, a Shoutbox or a Guestbook should never ask to get the buddies of a player.

    Additional information
    If you want to revoke any permission of a certain ManiaLink, you can visit home.maniaplanet.com, login with your ManiaPlanet account, and manage all applications which currently have access to your data.




    All good things must come to an end...

    Finally, after six posts, one longer than the others, we reached the end of the ManiaPlanet ManiaLinks Tutorial. Now it is up to you, to take this concentrated knowledge, and to apply it to your own ManiaLinks in ManiaPlanet. Of course I would like to see any feedback to the tutorial, regardless if you only want to thank for it or have some suggestions or found some errors in the tutorial.

    In the very last paragraph, I want to thanks all of those, who supported me with the tutorial, next to Nadeo of course all who helped me in the forums, too. Special thanks go to FT»kastun, seeba and destroflyer, which critically read the tutorial and pointed out all the errors, next to helping me getting the very last detail to be inserted into it. Without the support, the tutorial would never have been as big as it is now Smile


    That's it, now is your turn.
    FT»Marcel



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

    [Image: 54e39adf682a7e.png][Image: 54e81d421182e1.png]
    [Image: message.png]
    (This post was last modified: 13.02.2012 00:38 by Marcel.)
    17.08.2011 17:04
    Visit this user's website Find all posts by this user Quote this message in a reply
    Virus Offline
    Homely Mapper
    *

    Posts: 10
    Joined: Aug 2011
    Reputation: 0
    Post: #7
    RE: ManiaPlanet ManiaLinks
    Cool ! I've never known how to make a ManiaLink, and will surely make one once you'll have finished Tongue
    28.08.2011 13:02
    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