Marauroa Chat Tutorial/HTML5 Client

From Arianne
Jump to navigation Jump to search


Marauroa Tutorial

HTML5 support in Marauroa is in development. We are looking for feedback to stabilize the API and improve the documentation on it.

The HTML 5 client works in a modern browser without requiring any plugins or other software to be installed locally. It is therefore not written in Java but JavaScript. While JavaScript has a similar name, it has some basic concepts that are very different from Java.

HTML Code

We start our HTML 5 client by creating a HTML page consisting of an output area for the chat log and a small input field to enter text. We use CSS rules to make the page look nicely. We are using a development version of Marauroa, which consists of several JS files. The final version will consists of one file to reduce startup time. 

<!doctype html>
<html><head>
    <title>Marautoa Chat Tutoral Client in HTML 5</title>
    <style type="text/css">
        body {font-family: "Arial"}
        #chat {border: 1px solid #000; padding:0.5em; overflow-y: scroll}
        #chat p {margin: 0}
        p.logclient {color: #888}
        p.logerror {color: #F00}
    </style>

    <!-- low level communication -->
    <script src="json.js"></script>
    <script src="/socket.io/socket.io.js"></script>
    <!-- Marauroa -->
    <script type="text/javascript" src="marauroa.js"></script>
    <script type="text/javascript" src="client-framework.js"></script>
    <script type="text/javascript" src="message-factory.js"></script>
    <script type="text/javascript" src="perception.js"></script>
    <script type="text/javascript" src="rpfactory.js"></script>
    <!-- Out code -->
    <script type="text/javascript" src="chatclient.js"></script>
</head>

<body>
    <h1>Marautoa Chat Tutoral Client in HTML 5</h1>
    <!-- input field for text -->
    <form id="form" onsubmit="ui.chatBar.send(); return false">
        <input type="text" name="chatbar" id="chatbar" style="width:90%">
        <input type="submit" value="Send">
    </form>
    <!-- Chat history -->
    <div id="chat" style="height:200px">
        <noscript>JavaScript is required by the Web Client.</noscript>
    </div>
</body></html>


Implementing the client Framework

As the first step, we want to connect to the server using the marauroa.clientFramework. Note that we use "null" for host and post which means that we connect to the same server from which the client has been downloaded from. Connecting to the server may take a second or two, therefore we give some feedback to the user. 

function startClient() {
	ui.chatLog.addLine("client", "Client loaded. Connecting...");
	var body = document.getElementById("body")
	body.style.cursor = "wait";
	marauroa.clientFramework.connect(null, null);
}

Now as we are able to connect to the server, we want to receive and handle events. In the Java word, we implemented a subclass of ClientFramework. In JavaScript, however, we can just redefine the methods, we are interested in: 

	/** display a message to the chat window on disconnect. */
	marauroa.clientFramework.onDisconnect = function(reason, error){
		ui.chatLog.addLine("error", "Disconnected: " + error);
	}

	/** on failed login, open a message box and disable the user interface */
	marauroa.clientFramework.onLoginFailed = function(reason, text) {
		alert("Login failed. Please check your password and try again.");
		marauroa.clientFramework.close();
		document.getElementById("chatbar").disabled = true;
		document.getElementById("chat").style.backgroundColor = "#AAA";
	}

        /** Automatically pick the first character associated with this account and enable the chat controls */
	marauroa.clientFramework.onAvailableCharacterDetails = function(characters) {
		marauroa.clientFramework.chooseCharacter(marauroa.util.first(characters).a.name);

		var body = document.getElementById("body")
		body.style.cursor = "auto";
		ui.chatLog.addLine("client", "Ready...");
	}

Handling actions

So far, our client is able to connect to a Marauroa based server and display some basic feedback. There is an input field for chat message. Now we want to send those message to the server.

In order to keep our code well structures, we create an object called "ui" and a subobject called "chatbar". For Java developers: While Java is a class based programming languages, JavaScript is prototype based. 


/** user interface package */
ui = {
        /** methods for the chat input box */
	chatBar: {
                /** clear the chat window */
		clear: function() {
			document.getElementById('chatbar').value = '';
		},

                /** send a message to the server */
		send: function() {
			var val = document.getElementById('chatbar').value;

			// create an RPAction object of type "chat" with the message.
			var action = {
				"type": "chat",
				"text": val;
			};

			// send the message to the server and clear the input field
			marauroa.clientFramework.sendAction(action);
			this.clear();
		}
	}
}

Handling perceptions

Before we can put it all together, there is one remaining piece: We need to listen to perceptions sent by the server and display the chat in our log window.

In this tutorial the chat message are not just events, but objects. This allows us to store them to the database and allow late client to read the history. Normally we'd use an marauroa.rpobjectFactory to create those objects with the correct prototype ("Player", "Item", "Creature", ...) as they are transferred from the server. You can have a look at this file of the experimental Stendhal HTML5 client, to learn how the rpobjectFactory is used.

For this really simple chat client, we are only interested in chat objects. Therefore we skip this step for now and work directly on the perception event for new objects: 

marauroa.perceptionListener.onAdded = function(object) {
	if (object.has("text")) {
		ui.chatLog.addLine("text", object.get("from") + "* : " + object.get("text"));
	}
}

ui: {
	chatLog: {
		addLine: function(type, msg) {
			var e = document.createElement('p');
			e.className = "log" + ui.escapeHTML(type);
			e.innerHTML = ui.escapeHTML(msg);
			document.getElementById('chat').appendChild(e);
			document.getElementById('chat').scrollTop = 1000000;
		},

		clear: function() {
			document.getElementById("chat").innerHTML = "";
		}

		/** HTML code escaping */
		escapeHTML: function(msg){
			return msg.replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace("\n", "<br>");
		}
	}
}

Note: When putting all together, you need to merge the "ui" package from the previous section with the one defined here.

Deployment

Sorry, this part is still a bit messy. We promise to make it as easy as the traditional Marauroa version in the future.

Instead of the official download version of marauroa, you need to download the current development version directly from git.

Check out Marauroa, Branch perception_json into a new project:

Follow the instructions from the previous pages to setup your Marauroa server, with these little changes:

  • Add all the additional libraries to the classpath.
  • Create a Run Configuration, that launches marauroa.server.net.web.WebSocketServer

Create or reuse your server.ini

  • Edit server.ini to add these lines, replacing "accountname" with the name of your account for testing:
http_port=8080
debug_fake_web_username=accountname
  • Launch the WebSocketServer run configuration
  • Visit http://localhost:8080/chat.html
  • Best to do this using firefox, with firebug extension installed (if you will be developing or studying the client)

Next Steps

Congratulations, you completed this tutorial. The final sections will list some ideas for further steps to improve. {{#breadcrumbs: Marauroa | Using | Tutorial | Swing Client}}

Retrieved from "https://stendhalgame.org/w/index.php?title=Marauroa_Chat_Tutorial/HTML5_Client&oldid=15115"