In teaching and workshops I used to get students to question the idea that websites are ‘published’. They’re not released into the world in a fixed, immutable form – they’re a set of blueprints which only reach their final form in your browser window. This makes it possible to change the way websites look and behave.

Mozilla used to have a nifty educational tool called X-Ray Googles. Using it you could explore the code underlying a web page and do fun things like inserting new text or images. I encouraged students to try hacking ASIO’s home page.

ASIO home page with some added First Dog on the Moon.

There are other ways you can fiddle with websites. For example, most browsers have a developer console that exposes the code and styling of a page. You can use the console to edit HTML elements or toggle styles, but your changes won’t be saved.

One way you can save and share your web site customisations is by creating userscripts. Userscripts are little bits of Javascript code that run in your browser after a web page loads. These scripts can change many aspects of a page – not just how it looks, but also how it works.

Some old userscripts

I’ve been playing around with userscripts for a long time. Back in 2008, I created a userscript that completely overhauled the way that digital files were presented in the National Archives of Australia’s online database, RecordSearch. My userscript added new options for navigating and printing the file, and even made it possible to view the complete file contents on a 3D zoomable wall.

This customised RecordSearch interface was created by a userscript.

The userscripts I’ve created over the years have tended to either be useful little hacks aimed at fixing annoying aspects of GLAM websites, or experiments in thinking about the sort of information that’s presented online by GLAM organisations, and how it might be different.

In the first category are hacks like my RecordSearch show pages userscript. In 2009, I got annoyed that there was no way of knowing how many pages were in a digitised file until you clicked on the link. So I fixed it. With my userscript running, the links to digitised files are rewritten to display the number of pages. I’ve updated the code numerous times over the years, adding new features, and dealing with changes to RecordSearch. The last update was just a few days ago.

In the second category is my userscript that inserts photos from The Real Face of White Australia into RecordSearch. The are many thousands of records in the National Archives of Australia that document the impact of the White Australia Policy on the lives of ordinary people. But it’s often hard to understand this from the file descriptions. The userscript displays portrait images extracted from the files alongside the metadata – it tells you there are people inside.

Amidst my recent self-archiving binge, I realised I’d never updated this userscript to work with the latest data from The Real Face of White Australia, so I spent some time getting it working again. In the process I realised that RecordSearch now included content security policies that made it a bit harder to insert new images. The solution was to use one of the special userscript functions, GM_addElement(), rather than plain old Javascript. But then I discovered that the if the show pages userscript ran after this one, it would trigger the security restrictions nonetheless! To avoid this I made sure that the two userscripts operated on separate elements. So now the show people userscript is working again!

And a new userscript to improve Trove lists

Fixing up the ‘people inside’ code reminded me of how much fun it was playing around with userscripts, so when David Coombe mentioned a problem he had using Trove lists on Mastodon last night, I had to have a go at fixing it.

The problem is that Trove lists display all the tags associated with each individual item. Some items have lots of tags, so this eats up the screen real estate, making it harder to browse the contents of a list. Notes attached to items can be hidden, but not tags. Why not?

My brand new userscript hides tags by default, and adds a new link to toggle their visibility for each individual item. The link also displays the number of tags attached to each item. This gives the user control over which tags are displayed and when.

The new userscript in action – toggle your tags!

The main difficulty in creating this userscript was knowing when the page had actually finished loading. The current version of Trove uses a lot of Javascript to load and manipulate content, so you have to tell the userscript to wait until everything has settled down. Otherwise the script could fire too soon and cause unexpected results. I tried a number of different approaches to handling this problem, but eventually settled on the waitForKeyElements script. (I just realised there’s a more recent version of this script that doesn’t require JQuery, so I might need to investigate this further.)

Another Trove problem fixed!

Using userscripts

In addition to the userscripts mentioned above, I’ve also created one that enables you to browse Trove newspaper pages using the arrows on your keyboard. Left and right arrows go to the next and previous pages, while up and down arrows jump between issues. Searching is great, but sometimes you just want to browse. Install this userscript for that old-time, authentic newspaper reading experience!

But how do you install userscripts? First of all you need a browser extension to manage your userscripts – I use TamperMonkey or ViolentMonkey. Just follow the instructions to add one of them to your browser.

To install one of my userscripts, you need to go to the script (saved as a GitHub Gist) and click on the ‘Raw’ button. Your userscript manager will then ask you if you want to add the userscript. Click install!

Click on the ‘Raw’ button to install.

Once they’re installed the userscripts will run automatically when specified pages are loaded. If you ever want to disable them, you can do that from your userscript manager’s dashboard.

For convenience, here are the Gist links to all the userscripts I’ve mentioned:

• RecordSearch show pages
• RecordSearch show people
• Trove lists hide tags
• Trove newspapers keyboard navigation

As with anything you install on your computer, you want to make sure that you trust the source of any userscripts you add.