what is onionring.js?
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?
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:
- upload the script files somewhere - that's
onionring-index.js, see the specific section about that)
- edit the
onionring-variables.jsfile so that
siteslist contains the full URL of every site in the ring (ie it should include the http:// bit)
ringNameequals the name of your webring - this will show up in the widget as "part of the
ringIDis some uniquely identifiable value - this is so there's no conflict if a person is part of multiple rings which use this code
- edit the
onionring.cssfile so that all instances of
#webringidequal the same as the
ringIDyou 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:
...where 'scriptURL' is the full URL of the place where the manager is hosting the
onionring-variables.jsfiles, and 'webringid' is the same as the
ringIDthe manager decided on.
they might also want to include this:
<link rel="stylesheet" href="scriptURL/onionring.css">
<head></head>part of their page to apply some basic styling to the widget. again, 'scriptURL' should be the URL where the
onionring.cssfile 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:
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?
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.
where can i get the script?
- 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.
24th nov 2020 - widget code now checks if the url it's on begins with the one in the list, rather than matching it exactly. this should allow you to put it in multiple places on your site, if you want.
9th nov 2020 - added ability to give widget a unique id to avoid conflicts and instructions on how to do that. pulled some of the css styling out of inline style tags and into the css file. made the script installation instructions clearer. added more detail and beginner's resources to styling section