Shout-Maru Help

If you're reading this, then something is not right, because it's supposed to be self-explanatory. Or maybe you're just geeky curious, like me.

I should make some disclaimers. The use of this service is free. BUT. I may decide I don't want to provide this service at some point in the future. Or, I may break something. Or, I may lose all your messages and data. Or, I may decide I don't want you personally to use it. If any of these possibilities alarms you, then you should probably go look elsewhere.

You want to leave messages in the shoutbox

Umm, just fill in the name, url/email (optional), and message fields, then click the Post button. If your message doesn't show up, then, whoops! Contact the webmaster of the site you're trying to use and bug them about it.

About the url/email field: you can enter either your email address or your web URL. Sorry, can't do both - this is a shoutbox, not some fancy schmancy web forum. Make sure your email address looks like an email address and a URL looks like a URL or it will be ignored.

In a similar vein, if you enter something that looks like a web URL inside of "<" and ">" (ie "<http://something.blah>") in your message, then it will automatically get hyperlinked. Don't try to put HTML into your messages, they will get entity-ized. Smilies are automatically filled in for you (if the webmaster hasn't turned this off) - see the smilies reference for usage details.

The Help button brings you here. The Reload button will reload the page/frame/whatever. The Save/Clear button will store your name and url in a cookie if you get sick of typing it in or you get uneasy about leaving a cookie with your name, respectively.

If you post a message and you don't see it show up in the shoutbox, then try reloading the page. Still no? The admin of the shoutbox may have banned you, check with them. Or, maybe you've triggered flood protection because you were posting too much too rapidly. Slow down.

If you are seeing a message complaining Shoutbox lookup error or Unrecognized shoutbox or some other such error, it's most likely because the webmaster of the site you are visiting has misconfigured their HTML usage of this service. Bug them about it.

You want to have a shoutbox on your site

Follow the directions you get when you login and set up a shoutbox.

What?!? You need more than that?

The Shout-Maru call

Here's an explanation of the various "switches" you can use when calling your shoutbox. They can be used in combination, where it makes sense. Just separate with an ampersand. For example:

That can all be one line, if you want. Specific details will be provided when you create your shoutbox, so you can copy & paste the HTML snippet then. If that's all you care about, you can stop reading now.

If you'd like HTML output instead, use output=html. If you are asking yourself why you'd want to do this, then you probably don't need to worry about it.

Messages & Form (messages=false & form=false)

The thing with those other shoutbox services is that you're kinda bound to how they format stuff, which is one reason I made this one. If you want to separate out the messages and forms in separate calls for example (maybe you're a control freak like me and want to format them specially, say messages in an iframe and the posting form outside of it), you can use messages=false or form=false. These turn off message display and form display respectively. Duh.

Controlling the number of messges shown (num= & start=)

You can control the number of messages to output in your shoutbox using the "num" parameter in the call. For example, the following call would generate your shoutbox with 20 messages (the default is 10):

http://shout.x-maru.org/shout?id=xyz&num=20

A related switch indicates which message number at which to start. For example, the following would show messages 20 through 40:

http://shout.x-maru.org/shout?id=xyz&num=20&start=20

Time format (time=)

You can specify the format of the [TIME] variable via the option "time". Something like:

As you can see, there are a number of "variables" you can use: [ODDEVEN], [USER], [TIME], and [MESSAGE]. There's also [CUSTOM] if you'd like to use it (see the section on forms below). If you know some HTML, you can create your own template using these variables and that's how the messages in your shoutbox will be HTML-ized. The only ones you need to use are [USER] and [MESSAGE], because otherwise what's the point?

Note about [ODDEVEN]: this will alternate between "odd" or "even" with each message, if you decide to use it. You can use it in conjunction with CSS to format alternating colors, for example.

Note about user identifier URLs: If the user entered something in the email/url field that looks like an email address, then a mailto: will be generated. If the user entered something that looks like a web URL, then a regular web link will be generated. Otherwise, it will be ignored and the anchor tag left off.

Protect A Username

The idea here is that on your own site, you want to use a certain username in your shoutbox, but you don't want anyone else to use your username to "forge" posts as if from you. So you enter a username for this option and when someone (maybe you) uses that username, they are required to enter the username with password in a speciallly coded format like so:

myusername*password

To further drive this point home, if the username you set for this option is "xo" and your Shout-Maru password is "thisisdumb", then when you use your shoutbox, you would enter the following for the username in your shoutbox:

xo*thisisdumb

Not to put too fine a point on it: if this option has been set, any message submitted as that username but without a password encoded as described will be ignored.

Note that if the username you choose to protect or your password contains an asterisk, this feature won't work! What did you expect, MAGIC?!?

Check Referrer

The problem with shoutboxes done via remote Javascript is that any site can include the same snippet of HTML you do and make your shoutbox appear on their pages, in essence hijacking your shoutbox. One way around this is by checking the "referrer": when a request comes in for your shoutbox, the request usually contains an indication of which URL asked for it. This can be checked to make sure only your web page is intiating the request.

To use this feature, just enter something in the referrer field if your shoutbox's settings. Then, only if the request's referrer info contains this string will the shoutbox be displayed. So, for this site's shoutboxes, I might enter "http://shout.x-maru.org" in the check referrer field.

Now, the problem with this approach is that not all browsers (or any proxies in the mix) send a referrer. For those visitors using such browsers (or proxies) no shoutbox will be displayed if you're using this option. Furthermore, there's no way to check this on message posts due to the way things work. However, most modern browsers send this information and it works as intended. Still, use at your own risk.

Ban IPs

People suck. People on the internet suck even more because they are anonymous. So, if you find your shoutbox is being abused by someone, you can ban them from posting to your shoutbox. Check the message history and see which addresses are causing problems, then enter them in the ban box. You can have multiple entries separated by commas. It's just a string match so you can put in something like "192.168.0." to catch the whole class C range.

Censoring

You may want to censor certain words in your shoutbox. For whatever reason. Enter the words where indicated, separated by commas, and each instance of that word in a shoutbox message will be replaced by asterisks.

Caching

For performance purposes, your shoutbox is cached until a new message comes in, then a new cache is generated. Makes it easy on this server since there will always be more views than posts. However, certain sequences of events can cause your cache to go stale (most commonly, you change your shoutbox call so that different switches are used). This will always clear up the next time a message is posted, or, if you are impatient and don't want to post a dummy message, you can just Update your shoutbox settings (whether you made any changes or not) to clear the cache.

Form Syntax

Here's the basic syntax of the posting form, for reference. This is only important if you plan on doing some heavy lifting and customizing. Note that the form automatically generated for you differs; this is unstyled and is just a skeleton to build from. The lines in gray are not required, per se.

Shout-Maru provides one user-defined field in addition to the standard ones. If you plan on using this, you must define your own form and submit a value with the name "custom". You must also define its output in a template using the [CUSTOM] variable.

Epilogue

Don't you wish you never asked? I suppose if you made it this far, I should at least give you an email to contact me. It's shout@x-maru.org, or Google Talk me at hellfroze.