imagine yourself and a bunch of friends or people you share an interest with, in a circle, all holding hands. everyone's left hand links them to the previous person in the circle, and everyone's right hand links them to the next person. now imagine that you're a website, and your hands are hyperlinks. that's a webring! and if you click 'next' on every site, you'll eventually get back to where you started.

back when search engines weren't very good, this was a useful way to connect your website with more users, and users with more websites that have similar content to stuff they already like. people still like to use them now because 1) we're all nostalgic for a simpler time and 2) they feel like a more honest and organic way to discover content on the internet.

it's as simple as everyone agreeing to link to each other in a circular fashion.

well, ok, there are some tricky parts. how do you decide which order people are in the ring? what happens when new people want to join or leave? what if you want to go to a random site, or see everyone in the list? suddenly it doesn't seem very simple at all! the onionring.js script is one solution to that. there are others, but we designed this one to be as simple and versatile as possible.

first thing's first: everyone who wants to be in the ring should at the very least have a site where they can directly edit the html. one person then needs to agree to be the manager of the ring.

the manager should:

1. upload the script files somewhere - that's onionring-variables.js, onionring-widget.js, and onionring.css (and optionally onionring-index.js, see the specific section about that)
2. edit the onionring-variables.js file so that
   • the sites list contains the full URL of every site in the ring (ie it should include the http:// bit)
   • the ringName equals the name of your webring - this will show up in the widget as "part of the ringName webring"
   • ringID is some uniquely identifiable value - this is so there's no conflict if a person is part of multiple rings which use this code
3. edit the onionring.css file so that all instances of #webringid equal the same as the ringID you set. make sure it still has the # at the front, though!

everyone in the ring (including the manager) should:

put the following code on their webpage where they want the widget to appear:

<div id='webringid'>
<script type="text/javascript" src="scriptURL/onionring-variables.js"></script>
<script type="text/javascript" src="scriptURL/onionring-widget.js"></script>
</div>
      

they might also want to include this:

<link rel="stylesheet" href="scriptURL/onionring.css">
      

that's it! that's as much as you need to do to get it working.

the manager should create a page to be used as the index. it might be good to write a little description of what the ring's about - for example is there a theme? what kind of content can you expect to find? can anyone join, or is it just you and your friends?

then all you have to do is include the following:

<div id='index'>
<script type="text/javascript" src="scriptURL/onionring-variables.js"></script>
<script type="text/javascript" src="scriptURL/onionring-index.js"></script>
</div>
      

at the moment all this does is display a bulleted list of the URLs in the sites list. in future, we might make it possible to include stuff like icons, owner names and descriptions.

you can make it look like basically anything you want if you're willing to touch a little bit of code. onionring.js uses html to structure the widget and css to make it look pretty.

if you're the manager you can change both the onionring.css file and the html output of the onionring-widget.js script however you want. changes you make here will apply to everyone in the ring (except if they're overriding the css with their own). we've tried to include comments in the files explaining what they do, but you'll also want to know some basic stuff about html and css if you don't already.

if you're not the manager, you can override the default css by selecting #webringid (or whatever your manager has called it) wherever you do your css stuff. this might be in a separate css file or inside some <style></style> brackets. you can learn how to work with css here, and you can also download the default onionring.css file down below if you want to understand what specific elements to select.

• onionring-widget.js - creates the widget which is shown on each page in the ring
• onionring-index.js - creates a simple list of all the pages in the ring
• onionring-variables.js - holds the variables that both -widget.js and -index.js use
• onionring.css - applies some basic styling to the widget and index

you can also click here to down everything in a zip file.