News
050326: Small tweak to make shoutmaru better behaved with non-English character sets. May break stuff. Email me if you have problems.
040322: Release
A box like this on your site!
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.
What, you're still here? OK, if you insist. Below are some notes on usage of this service. It's broken into two categories: info for people doing the shouting and info for webmasters using the service.
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.
Follow the directions you get when you login and set up a shoutbox.
What?!? You need more than that?
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:
<script type="text/javascript" src="http://shout.x-maru.org/shout?id=xyz&x=1&y=off&z=abc"> </script>
output=)By default, output is accomplished through Javascript: a bunch of Javascript commands are generated to actually display your messages and the form. Use it like this:
<script type="text/javascript" src="http://shout.x-maru.org/shout?id=xyz"> </script>
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=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.
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=)You can specify the format of the [TIME] variable via the option "time". Something like:
http://shout.x-maru.org/shout?id=xyz&time=1
The formats are (ask me if you want something else added):
sort=)By default, the messages are sorted newest on top, oldest on bottom (for the set of messages displayed- see the section on limiting the number of messages). You can reverse via:
http://shout.x-maru.org/shout?id=xyz&sort=oldest
smilies=off)By default, certain character sequences are converted into graphical smilies. If you don't like this, use smilies=off in your shoutbox call.
Additionally, your shoutbox can be configured in various ways when you're logged in. Here's a description of the options.
If you need an explanation for this, I hate you.
This is a template for the HTML generated for your shoutbox. It comes with a default that looks like this:
<p class="[ODDEVEN]"> <strong>[USER]</strong> - <small>[TIME]</small><br /> [MESSAGE]</p>
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.
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?!?
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.
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.
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.
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.
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.
<form action="http://shout.x-maru.org/post" method="post"> <p> Name: <input type="text" name="user" /> URL: <input type="text" name="url" /> Message: <input type="text" name="message" /> Custom: <input type="text" name="custom" /> <input type="submit" value="Post" /> <input type="button" value="Help" onclick="help=window.open('http://shout.x-maru.org/help?shout=0#shouters')" /> <input type="button" value="Refresh" onclick="window.location.reload()" /> <input type="hidden" name="id" value="xyz" /> </p> </form>
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.
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.
050326: Small tweak to make shoutmaru better behaved with non-English character sets. May break stuff. Email me if you have problems.
040322: Release