🌿 garlic 🧄 garden 🌿

what is onionring.js?

it's quite likely you got to this page through a link on someone's webring widget. onionring.js is the script that makes that widget work - it's just a few javascript files that help you create and manage a webring, even (or especially!) if you don't know anything about coding (if you know your stuff, you can just skip to the download section)

onionring.js and the files that make it up are licensed under the cooperative non-violent license (CNPL) v4+, which means, roughly, that anyone is allowed to download, change and share the files as long as you don't use them for purposes that hurt other people.

what's a webring?

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.

how do you make one?

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.

how do i use the script?

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 needs to agree to be the manager of the ring - that person should have a place they can host the script files. they should edit the onionring-variables.js file so that the sites list contains the URL of every site in the ring, and the ringName equals the name of your webring.

everyone in the ring (including the manager) should put the following code on their webpage where they want the widget to appear:


<div id='webring'>
<script type="text/javascript" src="scriptURL/onionring-variables.js"></script>
<script type="text/javascript" src="scriptURL/onionring-widget.js"></script>
</div>
      
...where 'scriptURL' is the full URL of the place where the manager is hosting the onionring-widget.js and onionring-variables.js files. they might also want to include this:

<link rel="stylesheet" href="scriptURL/onionring.css">
      
in the <head></head> part of their page to apply some basic styling to the widget. again, 'scriptURL' should be the URL where the onionring.css file is hosted - it'll probably be the same as the one used in the widget source. that's it! that's as much as you need to do to get it working.

how do i use the index?

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

what if i want it to look different?

this section is pending a rewrite to make it simpler and more in depth

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 the onionring.css file however you want.

if you're not the manager, you can still override the default css by targeting the #webring div wherever you do your css stuff.

where can i get the script?

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