Using Onionring

Introduction

The Onionring webring system was written by made by Joey and Mord of Allium House around 2020. Allium House is a collection of "mages, rogues, artists, animals, and general weirdos", somewhere in lowland Scotland. Around a third of all modern webrings use Onionring.

Creating a webring takes a little bit of planning. Who is it for and what are the sites about? What site content is eligible or ineligible to join? What sort of webring code design do you want? Can sites change it if they want?

The Files

To fully work Onionring depends on 4 files, three JavaScript files; onionring-widget.js, onionring-variables.js, onionring-index.js, and a CSS file; onionring.css.

onionring-variables.js - contains nearly all the variables used in the other files. These include a list of the sites in the webring, the name of the webring, the ringID (which is also used as the ID of the div or other HTML container to hold the code), whether a list of all the sites in the ring is to be displayed on the webring owner's site, and whether a random site button is to be added to the code.

onionring-variables.js - the working part of the code. It calculates the next, previous and a random site if that is chosen in onionring-variables.js. The file also contains the webring display code which is by default in a table format.

onionring.css - The CSS to control how the display code is actually displayed.

onionring-index.js - This file creates a simple listing of the sites in the webring and is usually only used on a page on the webring owner's site. Some people prefer to code this page themselves and add things such as the URL, a site blinkie, a description of the site and so on.

For basic use, once you have changed the variables in the onionring-variables.js the only other file that needs editing is the onionring.css and what needs to be done in that is to change the #webringid entries into whatever ID you used.

If you want to create a webring and use the Onionring files, take a look at some of the other webrings that have used it and see what they have done. I also suggest you take a look at the various files and understand what they do.

Examples

In these examples, I have used example.com, example.net and example.org which are Internet Assigned Numbers Authority (IANA) reserved domain names for such purposes.

In this example, the webring name is RayRing and the div the code goes in is also given the id of RayRing. To show some of the things that can be done, I have given the webrings on this page a version number such as RayRingv1 and altered the name of the various files and their variables to reflect that.

v1 - No CSS

This is what the code looks like with no CSS

v2 - Standard CSS

v3 - Edited CSS

v3 - Edited Files

Members

The number of sites in the ring is not included in the original files, so I added a new variable called numsites to the index.js file using:

var numsites=sites.length

I then added the line:

<p>There are ${numsites} sites in this ring...</p>

just before the <ul> tag where the list of sites is displayed

To put the text and links on the page, I created a new div named index, and in that put:

All the Onionring scripts used on this page can be found in the JS folder of this section of the site. The files all begin with onionring-

Troubleshooting

As with any programming language when something goes wrong with the JavaScript code, it is not always easy to find and correct. JavaScript and other errors are written to the console. To access the console, put the browser into developer mode which is usually done by pressing F12. Once there, look along the top menu for a symbol that look like a screen with a > symobol in it.

Onionring error

The above error, "GET https://brisray.com/web/onionring-rayringv4-widget.js net::ERR_ABORTED 404 (Not Found)" is relatively easy to repair. It means that the browser cannot find the file onionring-rayringv4-widget.js. What happened here is that I did not put the file where I later said I did in the page code.

Other errors such as "Uncaught TypeError: Cannot read properties of null (reading 'insertAdjacentHTML') at onionring-rayringv4-widget.js:58:7 (anonymous) @ onionring-rayringv4-widget.js:58" are a little harder to decypher. What it is actually saying is that the ringID in the widget.js file, does not match the div id I gave it on the page it is supposed to appear and so it cannot write to insertAdjacentHTML.

Adding Sites

When someone asks to join your webring, all you have to do is ask them to link to your Onionring JavaScript and CSS files on their page.They do not need the index.js file, if you use it to produce a list of sites on one of your pages.

So if someone asks to join RayRingv4 in the above examples, I would ask them to add the following code to where they want it to appear:

All you have to do to add them to the ring is add their URL to the list in variables.js. As the webring owner hosts the file, there is no need for other webring members to do anything. This is one reason the webring owner should host the files, there should only be one list of site URLs for the webring. If all the sites in the webring kept their own list of URLs they will quickly become unsynchronised.

Some people prefer to ensure the site has added the code for the ring before adding them to the list. In that case, the site will see a message saying "This site isn't part of the webring yet. You should talk to the manager to have your site added to the list!"

No one likes broken webrings, so you may want to check occasionally that the ring code is still on the page, pages are redesigned now and then and people don't always add the code back to their new pages, and sometimes the entire site disappears.

Different Designs

You may want to offer the sites joining your webring a choice of designs to add to their page. To offer this, you have to create the new designs in different widget.js and onionring.css files and have them link to the files of their choice. Of course, you could use inline CSS in the widget.js file which means the onionring.css file is not needed.

When creating a CSS file it should be remembered that the wisdget code will need to be in it's own names container, otherwise the CSS styles may be applied to something else on the site's page which probably will not be welcomed.

If you use images in the design, then it may be best to send the new site owner those and let them host those themselves rather than them hotlinking the images from your site.