mozdev.org


Der Tandem Browser - Online Help

resources:


Der Tandem Browser Help Page

Introduction
Copying and License Information
Installation
Quick Start
Settings and Operation
Chatting, Synchronized Browsing, Preferences
DTBserver
Error Messages
Programmer's Notes
Organization,Technologies/Interfaces, Resources

Note: red text signifies a feature which has not yet been implemented.


Introduction

Der Tandem Browser is an add-on for the Mozilla browser which provides features that facilitate synchronized or interactive browsing among two or more people. When installed, it embeds a collapsible chat area/control panel into the bottom of the browser, and inserts a corresponding menu item to hide or display this panel in Mozilla's View > Show/Hide menu. Users connect to one another via the internet in the typical server-client configuration, with one person running Der Tandem Browser as a host and everyone else as a client. Once connected, users can chat with one another just as with any standard chat application.

der tandem browser panel

However, though DTB can be used merely as a simple chat client, it is developed specifically for one aspect of internet interaction: sharing links and viewing/discussing web pages in a group. Der Tandem Browser makes it easy to send and load links into a browser, minimizing the inconvenience of copying a URL from your chat client, pasting it into your browser, and vice versa. It has been laid out as a horizontal panel which sits at the bottom of the browser to maximize the web page display area and be compatible with the defacto convention of designing web pages to be vertically scrolled. In addition, it can be operated in a special 'tandem' mode in which one person acts as the lead and any URL (including local files) loaded into his browser will automatically be forwarded to and loaded in the browsers of all connected users. Some examples where this might be useful:
The lead browser can designate another connected partner as the new 'driver' whenever such a change is desired, and all users are free to switch off tandem mode at any time.

Feel free to offer ideas and suggestions - your feedback is welcome. Contact me directly at melodious@mindspring.com or visit the Der Tandem Browser homepage listed below. You may report bugs via the MozDev Bugzilla page or by emailing me.

Der Tandem Browser homepage:
http://dertandembrowser.mozdev.org



Copying and License Information

DerTandemBrowser - Synchronized browsing add-on for Mozilla
Copyright (c) 2003  Charles Melhorn

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Or see the GNU web site at: http://www.gnu.org



Installation

Manual Installation

Step 1:

Locate this directory: 'Browser'\bin\chrome where 'Browser' is the installation directory for the version of Mozilla you're using. On Windows systems, this will typically be "Program Files\MozillaXX", with XX representing the release number.

Create a subdirectory called "dertandembrowser" and unzip the Der Tandem Browser archive file into it (...\bin\chrome\dertandembrowser).  Be sure to use the option to preserve the directory structure when decompressing the zip file (check "use folder names" if using WinZip). Verify that  two subdirectories are created: 'content' and 'dtbserver' .

Step 2:

If installing DTB for the first time...

In the 'chrome' directory (Program Files\'Browser'\bin\chrome),  find the file named "installed-chrome.txt" and open it using a text editor, like Notepad. At the bottom of the file, append a  new line with the following text:

content,install,url,resource:/chrome/dertandembrowser/content/

The next time you open Mozilla, Der Tandem Browser  should be installed. A chat area/control panel will appear at  the bottom of the browser, and there will be a menu item for displaying/hiding the DTB bar under the View > Show/Hide submenu.

To Uninstall

If you need to uninstall it, delete the 'dertandembrowser' directory and its contents. Then edit these three files and remove the lines containing "dertandembrowser" if present:


Quick Start

Setting your nickname
To use Der Tandem Browser to chat and browse interactively with others, you'll need to set your nickname before you connect. Bring up the preference panel by clicking the settings button button (settings) on the toolbar to the left of the chat area. Fill out the nickname (and info, if desired) textbox, then press 'okay' to save your settings. You may use any combination of letters, numbers, and the underscore for your nickname, but you cannot change it while connected.

Connecting as client
Assuming you are online, you can connect as a client to someone running Der Tandem Browser in host mode by clicking the connect button button (connect), and selecting "Connect as client". Provide the host's ip address, either as a numerical address or as a host name, and choose "Okay". You should see a series of status messages in the chat display confirming your connection attempt. Once a connection is established, the message "handshake received: your position is x" will be displayed in the chat area and a list of partners will appear in the browsing partners box on the right side of the Der Tandem Browser window. Your nickname should appear in the position indicated by the handshake message, and it will be displayed in a bold font. Note that when you connect as a client, you'll be in tandem mode, as indicated by the depressed tandem mode button button on the connection toolbar and the green status icon READY status icon after your name in the browsing partners listbox. This means that your browser is linked to the partner whose nickname appears at the top of the partners list, and, if he is in tandem mode too, it will display whatever URL is loaded into his browser. You can turn off tandem mode by toggling the tandem mode button - the tandem status icon will be cleared, but your nickname remains in the list of connected partners. It is not necessary to be in tandem mode in order to chat.

Connecting as host
Because Mozilla does not currently provide the ability to create server sockets, Der Tandem Browser uses a companion program, DTBServer, to allow it to act as a host. DTBServer is written in C using Unix network APIs. To run Der Tandem Browser in host mode, you'll need to start DTBServer, which resides in the dertandembrowser\dtbserver subdirectory, then connect to it by selecting "Connect as host" from the Der Tandem Browser connection dialog window. Normally you can start the server program without any command line arguments. However, if you find that command messages are being dropped (if the partner status icons don't seem to update properly, for instance), you may wish to increase the WriteDelay, which is the minimum time the server waits between forwarding successive command messages. For more details about configuring the server, see the DTBServer section. The server program uses port 4444 by default.

You should see a series of status messages in the chat display confirming your connection attempt. Once a connection is established with the server, the message "Waiting for partners to connect..." will be displayed in the chat area and your nickname will appear in the browsing partners listbox on the right side of the Der Tandem Browser window. Note that when you connect as a host, you'll initially be in solo (i. e. not tandem) mode.

When a client connects to you, via the server, the message "Received connection request from partner_name" will be displayed in the chat area and the partners listbox will be updated with the new partner's name and status. Because the server program assumes that the first person connected to it will be the host, you should be sure to be up and running before inviting others to connect to you as clients.

Tandem browsing and switching 'drivers'
The person at the top of the partners list is designated the lead browser, also known as the browser captain or der browser meister. When the lead browser is in tandem mode, as indicated by the green status icon READY status icon after his name, any URL loaded into his browser is forwarded to all connected partners, and will be loaded and displayed in the browser of any partner who is also in tandem mode. The loading icon loading status icon will appear after the name of a tandem partner while his browser is loading a URL relayed by the browser captain, then return to green when the document load has been successfully completed. If the specified URL is a local file, the file itself will be automatically transmitted to all linked partners so that it can be loaded and displayed (not yet implemented).

Only the browser captain may lead the linked browsers in this fashion; any other connected partner, even those in tandem mode, can load a URL without affecting the other linked partners. To switch 'drivers', the browser captain may promote another partner to the lead position by selecting his name in the partners listbox, then right-clicking and choosing "Promote" from the context menu. The promoted partner and the old captain will swap places in the partner list, and the new captain will then have the ability to lead the browser procession.

At this time (version 0.6), Der Tandem Browser is not fully compatible with Mozilla's tabbed browsing feature. Therefore, it's best to avoid creating multiple browser tabs while using DTB.

Disconnecting
To disconnect, click the disconnect toolbar button disconnect button on the left side of the Der Tandem Browser window. If you are running DTB in host mode, you'll need to shut down the server program by using CTRL-C in the program's command/shell window.



Settings and Operation

Hiding and Showing the Der Tandem Browser panel

To completely hide the DTB panel, use the menu item under the browser's View > Show/Hide submenu. You can also collapse the panel by clicking the grippy widget on the splitter that separates the DTB panel from the browser content area. The panel's height and hidden/collapsed status are saved on exit.

Tool Bar Buttons:

connect button Connect button. Brings up a connection dialog window. See Connecting as client or Connecting as host in the Quick Start section for more information. Will appear depressed while you are connected to other DTB users.
disconnect button Disconnect button. Will appear depressed while you are disconnected.
tandem mode button Tandem mode button. Toggle to enter/exit tandem mode (see Synchronized Browsing below). This button is disabled until you are connected.
chat view icon
Displays the chat area.
settings button Settings button. Displays the preference panel.
info view icon
Displays the "about" panel which includes program version and copyright information.

Viewing Local Files

You can use the "View File" button on the right of the chat entry textbox to select a file for viewing, similar to the Mozilla browser "Open File..." menu item. If you open and load a local file while you are the lead browser in tandem mode, the file will be automatically transmitted to all linked partners so that it can be loaded and displayed (not yet implemented).

Getting Help

Click the "?" button located to the right of the chat entry textbox to display this help page.


Chatting

Der Tandem Browser's chat display supports the following chat commands and widgets:

Command or Widget
Character sequence
emoticons: smile icon wink icon frown icon jacko icon
:)  ;)  :(  ;(  respectively.
sonicons (audio icons): ear icon doh, ear icon splash $* , $~ respectively.
links: ex. http://www.mozdev.org
Enter "http://www.mozdev.org" .
actions: ex. adeleH bats her eyelashes Enter "/me " at the beginning of a line, followed by desired text
bold: ex. you cannot be serious!
Enter "*word*" . Example: "you *cannot* be serious!"

To change the font size, right click on the chat display area and choose the desired size from the context menu. Emoticons and sonicons can be turned off in the settings panel, in which case the underlying character sequences will simply be displayed as text.


Synchronized Browsing

Der Tandem Browser makes it possible for two or more browsers to be linked, so that a URL loaded in the lead browser will be transparently forwarded to, and loaded in, the browsers of all participating users. In addition, it provides feedback on the progress of  the other browsing partners, allowing the person leading the browser procession to determine when the page load has finished and whether the URL has been loaded successfully. Ideally, it should never be necessary to ask a browsing partner whether she's "there" or if he "can see it" - you'll know by monitoring their status in the browsing partner's listbox.

dtb partners listbox

The person at the top of the partners list is designated the lead browser, also known as the browser captain or der browser meister. When the lead browser is in tandem mode, as indicated by the green status icon READY status icon after his name, any URL loaded into his browser is forwarded to all connected partners, and will be loaded and displayed in the browser of any partner who is also in tandem mode. To enter or exit tandem mode, toggle the tandem button tandem mode button on the connection toolbar to the left of the chat area. It is not necessary to be in tandem mode to chat.

When a linked browser begins to load a URL, its status is updated and the 'loading' icon loading status icon will appear after the appropriate name in the partners list. Typically, you'll see the browser captain's status change to loading first, followed shortly by the other partners as they follow his lead. Once the document has finished loading, the browser's status is updated and the green READY icon READY status icon is displayed once more.

Summary of status icons:

READY status icon Indicates partner is in tandem mode and ready to proceed. Also indicates that the previous load, if any, was successful.
loading status icon Indicates that partner is in tandem mode and is loading a shared URL.
out of sync status icon
Indicates partner is in tandem mode and ready to proceed, but that the previous document load was not completed or was unsuccessful.

(no icon) Indicates that partner is in SOLO mode, i.e. not linked.

Only the browser captain may lead the linked browsers as described above; any other connected partner, even those in tandem mode, can load a URL without affecting the other linked partners. To switch 'drivers', the browser captain may promote another partner to the lead position by selecting his name in the partners listbox, then right-clicking and choosing "Promote" from the context menu. The promoted partner and the old captain will swap places in the partner list, and the new captain will then have the ability to lead the browser procession.

Limitations:

Preferences

You can bring up the preference panel by clicking the settings button button (settings) on the toolbar to the left of the chat area. Press the 'okay' button to save any changes to your settings. If you don't wish to save your changes, switch to one of the other views, either the chat area or the 'about' panel, without clicking the 'okay' button.

The following preference options are available:

Preference
Default Value
Description
verbose messages
false
When this is true, diagnostic and expanded informational messages (e.g. raw command data) are displayed in the chat area. Used primarily for debugging.
play connect tone
false
Setting this true will cause a tone to be played when a new guest connects to the host. Applies only to the DTB in host mode.
emoticons
true
Enables/disables the display of emoticons in the chat area. If disabled, the emoticon drop down menu will be hidden and emoticon strings are simply displayed as text.
sonicons
true
Enables/disables audio icons. If disabled, sonicon strings are simply displayed as text and the associated .wav files are not loaded.
nickname
"dtb_partner"
User's chat name. Must consist of only alphanumeric characters and/or the underscore, and is limited to 25 characters. Cannot be changed while connected.
info
""
User information displayed as a tooltip when the mouse cursor is positioned over user's name in the partners list box. Might typically be used for a quote or an email address. Limited to 35 characters.
host max.
4
The maximum number of connections allowed by the host. Requests to connect after this quota has been reached will be rejected.

Der Tandem Browser preferences use the preference node "extensions.dtb." and are stored in the "prefs.js" file (along with the other Mozilla preferences) in the user's profile directory. On Windows systems, this directory is usually Documents and Settings\<user_name>\Application Data\Mozilla\Profiles\<profile name>\<random string> or something similar. On Linux, it would be ~/.mozilla.


DTB Server

Because Mozilla does not currently provide the ability to create server sockets, Der Tandem Browser uses a companion program, DTBServer, to allow it to act as a host. DTBServer is written in C using Unix network APIs; it runs on Linux platforms as a native binary and on 32-bit Windows systems with the Cygwin DLL.

DTBServer acts as an intermediary between the DTB client acting as host and the other other DTB clients acting as guests. It could be described as a "dumb proxy" because most of the hosting duties such as maintaining the list and status of connected partners or echoing messages are performed by the DTB host. The server is pretty much limited to listening for connections from new clients and relaying messages between the DTB host and the DTB guests. It assumes that the first client connected to it is the host; any message received over its first connection is transmitted to all other connected clients. Likewise, any message received from connection 2 or greater is transmitted only to the client on connection 1. Thus, the DTB host, not the server, is responsible for resending any message from a client that needs to be seen by all guests.
dtb network configuration diagram
DTBServer has one other function and that is to maintain an array of working connections. If a client becomes disconnected, either because a guest intentionally disconnects or because an error occurs, the server will close the socket and remove it from the array. Since most of the host logic resides in the DTB client, it should be relatively easy to replace the server program with native Mozilla server sockets or a similarly functioning XPCOM component in future versions of Der Tandem Browser, if appropriate.

To run DTBServer, simply start it from a command console/shell or double click the file, as appropriate for your operating system. By default, the program runs in PROXY mode and listens for connections on port 4444 (and 4445 for file transfer connections). It's possible, however, to override these values using command line arguments and flags: enter dtbserver -h to display the usage description and a list of flags. If you are considering using a different port, bear in mind that the DTB client also expects to connect to port 4444 and would have to be modified as well. To stop the server, use CTRL-C.

One parameter you may wish to experiment with is the minimum interval between successive messages. The server limits the rate of messages over every connection to avoid overrunning its clients, particularly the DTB host which is normally local to it. If you find that command messages are being dropped (if the partner status icons don't seem to update properly, if linked browsing is erratic, chat messages are lost, etc.), you may wish to increase the WriteDelay, especially on slower or heavily taxed machines. The default WriteDelay value is 5, which translates to .5 milliseconds between commands. To change the WriteDelay, use the -wN flag, where N is the delay in .1 milliseconds. For example, to change the WriteDelay to 10 msecs between commands, start the server by entering dtbserver -w100 on the command line. As an illustration, I've found that I had to boost the delay to 50 milliseconds on a 800 MHz PIII while listening to large .wav files, although the default of .5 ms normally works fine on that same machine.



Error Messages

Error Message Text
Description
Error 01: Please reenter nickname using only
characters [A-Za-z0-9_].
Displayed when attempting to save user settings after entering an invalid nickname. 
Error 02: Cannot alter nickname while connected
- change ignored.
Displayed when attempting to save user settings while connected, after changing nickname. All preferences other than the nickname are updated.




Programmer's Notes

Organization


Technologies/Interfaces


Resources




Revised: 06/04/03

This document created and maintained with Mozilla Composercomposer taskbar gif