Message System

Introduction

The DutchPIPE message system is responsible for all communications to objects. These are not limited to users, you can communicate to all objects, such as NPCs or pages. Also, it is not limited to text communication, it takes care of all communications such as requesting complete pages or sending the XHTML to add an avatar to a page when someone else enters the page a user is on.

If the object is a user object, it will send messages and HTML to represent objects, windows and the like to the user's browser. NPCs and other objects will not react to messages by default, but can be made to do so.

The tell method

The message system is centered around the following method which can be called in all objects in your universe:

1. function tell($data)

When called with a string with data, it will communicate the string as a "message" to the object it was called in:

1. $user->tell('You drink the beer.');

When called in pages, it will communicate the message to all objects in that page. In this case, one or more extra parameters can be given to skip:

1. function tell($data, &$from, ...)

This is used to skip the source of the message, so:

1. $page->tell($user->getTitle() . ' drinks the beer', $user);

will communicate that someone is drinking a beer to all objects on the same page, except the user itself, who gets a custom message.

The $data to communicate

So far, we have only seen text messages being communicated. For users, these messages will appear in the text message area in their browsers.

However, the $data string uses the following XML format to communicate (other) types of messages:

• <message>data</message>

• The default when the string isn't surrounded by tags. Transmits data to the text message area.

• <window>data</window>

• Creates a yellow window with data as content. The window tag can have these attributes:

  • autoclose="miliseconds"

  • When not given, the window has a 'close' link. With this argument given, it will automatically close in the given number of miliseconds.

  • styleclass="cssclass"

  • Used to create a different window than the default yellow one.

  An example which is used for drinking beer:

  1. $env->tell('<window autoclose="2500" styleclass="dpwindow_drink">'
  2.     . '<h1>' . dp_text('BUUUUUUUUUUUUUURRRP!') . '</h1></window>',
  3.     $user);

The following types are used by the DutchPIPE system and you probably don't need to use them directly:

• <div id="DOMelementid">content</div>

• Adds a div element to the DOM of the user, removes any existing ones with the same id.

• <location>url</location>

• Moves an object to another location. This can be used to move users to another page.

• <addDpElement>, <moveDpElement>, <changeDpElement>, <removeDpElement>

• Used by DpObject::moveDpObject() to handle graphical object elements.

CDATA/innerHTML

Note that currently all message data is automatically wrapped in a <![CDATA[ ]]> construct. So:

<message>hello world</message>

will automatically be turned into and communicated as:

<message><![CDATA[hello world]]></message>

This is done because otherwise the data must always be valid XHTML to be parsed by the XML parser. For instance, for messages by users this is absolutely necessary. At the client side, innerHTML is used to add content.

Although this is "handy", this was the quick and lazy and not the clean or advanced solution. The option to not do that for certain things (such as the XHTML of pages) and operate in a cleaner way with the DOM will be added in the future, allowing more trustworthy DOMs in the browser.

In other words, it's rather lame for DutchPIPE to only do DHTML/innerHTML and not proper DOM manipulations. We'll try to do better.

For more info, do for example a Google search on "innerhtml vs dom".

Behind the scenes

For the browser, there are two ways to obtain data:

• Through a page request
• Using AJAX

Also, there are two ways data is communicated to the browser:

• Directly because of a user action (page request or performing an action)
• Indirectly (for example, someone else says something)

A user is not permanently connected to a DutchPIPE site. The user requests a page, and the HTTP connection is broken. Then every two seconds, the user will request updates, and get disconnected every time.

If an external event causes a message to be generated for a user, it can't be directly communicated to the user's browser because of that. Messages will be put in a queue, and are communicated during the next page or AJAX request.

When a user requests a full page (he clicks a link for example), not only the page content but also all waiting messages (text messages, windows, moved or changed objects) are included in the XHTML. There is no need to obtain those separately with AJAX.

When an AJAX check is performed and waiting messages are obtained, the Javascript in the browser will insert, update or delete text and elements on the fly.