Getting and customizing a Clio-based site
Clio is a small CMS for doing histories and news. It’s essentially a blog with a few extra features, namely the ability to report on an event that happened in the past, and the fact that the events in the site show up in a nifty timeline view. Clio is written as a web application in the Ruby programming language, and uses the Rails framework and a database such as MySql as well as a bunch of other stuff (like ImageMagick to do image resizing, ffmpeg for video conversion, etc).
The basic Clio installation is detailed in the project documentation. It’s a difficult but not impossible task for a beginner to get it running, with the main trouble being that certain parts of the documentation aren’t complete yet. If you are comfortable dealing with a sentence like “install Ruby on Rails and MySql, run the data migrations and install any gems that give you errors”, well, go for it. Most beginners won’t be able to handle this, and I’m trying to write up enough tutorials to get people to the point where they can easily modify their own (running) code and see the results.
However, if all you want to do is to customize the templates for a Clio site, it’s not necessarily the case that you need to have all the code running. You can just check out the site code and you should be able to modify what you need to. Let’s take the CNS site as an example.
About subversion
For development purposes, the site code sits on a special kind of server called a subversion server. As someone who just wants to modify a few templates, you might be asking yourself, “why does Yoss want to piss me off by putting the site code into this weird system where I can’t easily get at it?” There are a bunch of reasons why programmers use subversion (often called svn).
First, it keeps track of every revision to the code. That is, every time somebody changes the code, subversion makes a note of the change, and it’s always possible to roll the version backwards if the change turned out to be a big mistake.
Second, it allows multiple people to work on the site code at the same time. Using subversion, people all over the world can be working on the same website and not be worried that they’re going to accidentally change a file that somebody else was working on at the same time.
The code sits on the subversion server – you can think of this as the master copy of the site, the one that actually matters. If you want, you can even see it by going to the code browser at http://escapegoat.org/projects/cns/browser/trunk/cns and poking around. That code browser shows us who changed which files, when they changed it, what each change consisted of, and what the person thought the change was supposed to do. On an Ubuntu or Debian system, subversion is easy to install, just
sudo apt-get install subversion
To work on the site, you will need to grab your own copy of the code. This is called checking out the code. Fire up a command line terminal, and grab the code by typing this at the command line:
svn checkout svn://escapegoat.org/cns/trunk/cns
This will get the code from the subversion server and you’ll end up with a copy on your local machine. You can then mess with the code to your heart’s content, and when you’re ready to put your changes back into the master copy, you can go into the top-level folder of your checked-out code (in this case, it’s called cns on your filesystem), and type:
svn commit
At this point, something very frightening is going to happen – subversion will open up a command line text editor and show a list of files that you changed. Assuming you’re on Ubuntu, the text editor will be called nano, and it’s fairly easy to use. All you need to do is type in a message detailing what you did, hit ctrl-x to save the commit message, say y (as in yes, you want to save), and hit enter.
What’s this all about? A commit message like this one tells other people working on the project what it was you changed, and maybe a bit about why. You don’t need to write War and Peace (or one of my overly long blog posts), just something like changed the ‘recent events’ graphic or maybe altered the css so that the title is now blue or whatever.
At this point, you’ll be asked for the username and password you’re going to use to commit the code. Enter the username and password supplied by your system administrator and the code will wing its way to the central code repository – and you’ve just changed the master copy of the site!
Note that this doesn’t mean you’ve changed the running site which is available on the internet (if there is one). Your changes will now be available for the next time somebody deploys the site code to a live server.
