Scout: Adding room information to your page

Scout is in beta testing, mostly due to the status of its documentation. This tutorial is incomplete and should be scrapped and rewritten. Please help us make it better by sending your comments.

Scout allows webmasters to insert live information about their chat rooms into web pages. Adding Scout to your page requires no scripting experience. For advanced users, additional interfaces are available.

This document is designed for webmasters with at least some familiarity with HTML. A technical reference is available for advanced users.

Currently, Scout supports room topics and user counts. It is currently available only for public rooms (those not explicitly set to private or secret).

Document conventions

Need to explain more about escaping and color codes.

A simple tutorial

The easiest way to connect Scout data to your web page is to use the JavaScript interface. It includes two easy-to-use scripts that will insert the requested information.

Three steps are involved:

Loading the utility script and data
Choosing the position of the data
Placing the insertion script

Loading the utility script and data

Scout uses a small piece of software called a utility script to handle common requests. It must be loaded before any Scout functions are used.

To load the first utility script, insert the following either in the <HEAD> tag or at the top of the body:

In addition to the utility script, another script must be loaded for each piece of data you would like to access. For example, if you would like to access the topic of #lobby and the user count of #loft, you will need to load two additional scripts: one requesting the #lobby topic and another requesting the #loft count.

To retrieve a piece of data for future use, insert this code:

Again, for value, use either count (to find the number of users) or topic (to find the topic). You can put all of the above <script> tags in the header for convenience.

Choosing the position of the data

Next, choose where to place the data. Scout offers two main methods for inserting the data:

Immediate insertion

Immediate insertion says "place the data right where this script is." This method is the simplest way to insert data; simply choose any place that text could be placed. For example, you could use a table cell, a heading, or a body paragraph. If you are using a graphical editor, you should mark the position with three Xs; the mark will allow you to easily find the relevant section of your page's code later.

Container insertion (for advanced webmasters)

Container insertion says "replace the contents of this container with the data." A container is created with <div> or <span>. To begin, create a container. You should set its position and style with CSS because any inner HTML will be replaced with the data. Be sure to specify the id parameter to give the container a unique name, for example <div id="usercount">.

Placing the insertion script

The placement of the script depends on which insertion option you have chosen.

Immediate insertion

Find the section of your page's HTML code that corresponds to the exact location at which you would like to place data. At that position, insert one of the following lines:

Container insertion

Find the section of your page body's HTML cody that corresponds to the end of the container (usually a </div> or </span> tag). If you insert the tag before using the container, the script will not find the container or the container's contents will be overwritten. After the container's closing tag, insert one of the following lines:

Advanced topics

JavaScript interface

Scout provides two functions for using its data in JavaScript:

lh_scout_get_html

lh_scout_get_html(channel, op) returns the data in HTML form, suitable for direct insertion into a page.

lh_scout_get_raw

lh_scout_get_raw(channel, op) returns the data in raw form (without HTML escaping), suitable for manipulation inside JavaScript. Do not write this function's output directly to the page without first escaping it. An additional utility function, lh_scout_tohtml(str), provides rudimentary escaping.

Raw interface

A plaintext version of the data is also available; see the technical reference. It is suitable for use on server-generated pages.

Learn about chat room safety
© 2002-2008 liveHarmony. Portions of this work are licensed under a Creative Commons license