![[Go To www.civilution.com]](http://www.civilution.com/gifs/logotransp90x155.gif)
Tools for evolving civilizations
Back to Civilution Home
Back to The Sextant Documentation Index
The Sextant HOWTO
So, by perusing our weblog you've gotten a taste of what our system can do, and want to do it for your website, too. Lucky you, because it's pretty easy. There's what you do:
1. Insert the Javascript header
Put our javascript into the HTML of the header of the page that contains the links you want to register with Sextant. For instance, let's look at the header of our weblog page at www.civilution.com/weblog.html:
...
</BODY>
Q: Why a separate remote file? Is it some kind of secret?
Normally, you do not upload your template file to us. The Sextant system goes and downloads it from your web server (or someone else's server, for that matter). To figure out just which URL points to your template file, it loads up the calling page and finds this line in it. It's fast, so don't worry: It only digs up the template URL when it needs to.
Q: Why on earth are you doing it this way? Why not have a regular upload page?
If you have really big bargraphs, you may want to set the align= parameter. Also, putting in some alt= text would probably be nice, too.
In our case, we use the sextant_from_url parameter here because we prototype our weblog on a staging server with a different domain name than www.civilution.com. Thus, we set the sextant_from_url to where the link will be, when it's on our public website, so it'll log clicks and draw bargraphs and make the discussion forums as if it were already working at www.civilution.com/weblog.html.
Once we upload the website to www.civilution.com, however, this statement becomes redundant because the javascript defaults this variable to the actual page, "http://www.civilution.com/weblog.html", all by itself. We could comment it out them, but don't.
upon being loaded by a web browser, would end up giving you:
The link rocket sandals! is all set up to log clicks, which will fill up the bargraph. Also, the bargraph will be a link to a new discussion forum (though we didn't do it here in this HOWTO page). Bingo.
As it stands, you have to call the javascript function after you define the link you want to Sextant-ize, and before you define another. If this isn't good enough for you then email us: there is a workaround.
Q: Javascript? What?! What if a reader doesn't have javascript turned on?
Your page looks and works just like it would have if Sextant had never existed. Try it by turning javascript off on your browser and going to our weblog.
Q: Wait a minute. If you're logging clickthroughs on my links, what happens if your servers go down? Will my links break?
2B. OR make a standalone forum. For example: I want to create a forum on my website where my friends and I debate about whether to switch from Diet Coke to Pepsi One. I don't want the comment-counting bargraph, either.
We've got you covered there, too. You can create a link to a forum that does not refer to an outside page. You use a different javascript call to make it:
Your template file has to live on a web server somewhere, so that our server can get to it. You can use someone else's, on someone else's web server, if you want, but it'd be nice to ask them first.
Making a template from scratch is a bigger deal than falling off a log, so the best thing to do first would be to hit the template tester page and snoop around other people's templates to get a rough idea of what's going on. Check out the Template FAQ and then the tag definitions for the real deal on what specific elements you have to work with.
<HEAD>
<title>Required Reading: The Civilution Weblog</title>
<!-- ********* Begin Civilution Sextant javascript header ********
Check the documentation at www.civilution.com/doc for more
explanation of what's here -->
<SCRIPT SRC="http://www.civilution.com/sextant-defs.js"></SCRIPT>
<SCRIPT>
// ---You can customize the following parameters, but don't need to.---
/* COMMENTED TAG PLANTED FOR DOWNLOAD BY SEXTANT SERVER
* <sextant_template_url = "http://www.abc.com/mytemplate.html">
* DON'T UNCOMMENT -- NOT JAVASCRIPT!
*/
// sextant_bargraph_height = 10 // default 10
// sextant_bargraph_width = 40 // default 40
// sextant_bargraph_other_html_options = "border=0" // default "border=0"
sextant_bargraph_bg = "FFFFCC" // default "CCCCFF"
sextant_bargraph_fg = "0000CC" // default "0000FF"
// sextant_bargraph_min = 1 // default 1
// sextant_bargraph_max = 20 // default 20
// sextant_bargraph_map = "linear" // default "linear"
sextant_from_url = "http://www.civilution.com/weblog.html" // default the URL of this page.
// Don't forget to include to include the bit: onLoad="sextant_onload()"
// in your body tag! (Damn IE)
</SCRIPT>
<!-- ********** End of Civilution Sextant javascript header ******** -->
</HEAD>
<BODY background="gifs/backgroundbig.gif" alink=red link=#000066 vlink=#AA0000 text=#000022 onLoad="sextant_onload()">
<SCRIPT SRC="http://www.civilution.com/sextant-defs.js"></SCRIPT>
The bulk of the javascript code is kept in a remote file on our website. It mainly consists of function definitions, like that of the sx_graphlink() function itself and all of its helper functions.
/* COMMENTED TAG PLANTED FOR DOWNLOAD BY SEXTANT SERVER
* <sextant_template_url = "http://www.abc.com/mytemplate.html">
* DON'T UNCOMMENT -- NOT JAVASCRIPT!
*/
This line must stay commented out, always. It's not meant for the javascript interpreter at all, but instead for the Sextant system when it checks back to your page to get the URL of your template file. The template file dictates the formatting and functionality of your discussion / clickthrough statistics page. Check the Template Tester Page to see some actual template files and how they look and work. We also have a template FAQ and documentation for each of our special template tags.
Because this way you don't have to "sign up" for any services or priveleges. We don't need to assign you any special identity or password. No one can break into our system and re-assign your discussion pages to use a different template, because there's nothing for them to break into. Your template file is as secure as your web server.
This line tells sextant how high you want your clickthrough bargraph, in pixels. Here we leave it commented because we want the default, 10.
Take a guess... That's right, it's the width of the clickthrough bargraph in pixels. Once again, we at Civilution leave it commented out because we want the default, 40.
The Sextant javascript writes out the HTML for the bargraph image. It already knows what to set the width= and height= attributes to from the two above parameters, but here is where you set its other HTML attributes. Just put them into this string variable as if were going inside the <IMG ... > tag. The default, "border=0", makes sure that the image doesn't get a fat, ugly border put around it.
The background color of the bargraph is the color around the graph elements. Usually, you'll set this to the background color of your page. This has to be in hex form (no "white" or "black").
The foreground color of the bargraph is the color of the bar elements when they're filled-in. Usually, you'll set this to about the same color as your link color, though maybe a little darker. This, too, has to be in hex form.
At what count does your bargraph start to fill in? The default, one, is a logical choice, but if you want a link to overcome a "threshold" of 100 or so before it starts to fill in, well, then go for it.
At what count will you bargraph be full? The default, 20, is pretty low if you get a lot of traffic, so you'll want to bump this one up.
On "linear," if the first bargraph element takes 10 clicks to fill up, so will the next and last. On "log," each bar element takes twice as many clicks to fill us as the one before it. This might be just the trick if you want to fill up at a very high number, but also want to register the first few clicks quickly.
This parameter defaults to the URL of the page that contains it, which is almost always right. However, when you move a link from its original page to another (like an archive page), you'll need to "manually override" this parameter to the the URL of its original page. This way, it will keep logging clicks in the same place and draw the same bargraphs. Otherwise, Sextant will see it as an entirely new link and start you over from zero with no clickthrous and a clean discussion forum.
You have to insert this little snippet into your BODY tag, or the system just won't work on Internet Explorer. (Thanks, Bill.)
After laying all the groundwork in the javascript, all you have to do now is make a call to the function sx_graphlink() after defining a link. For instance, the HTML code:
This morning Bob called me up to tell me about these new ACME <a href="http://www.acme.com/forsuckers/rocketsandals.html">rocket sandals!</a>. <SCRIPT>sx_graphlink()</SCRIPT>This morning Bob called me up to tell me about these new ACME rocket sandals!.
Then your page works just like normal, no kidding:
No, your links will still work, no fooling. We specifically designed our system so that your pages will work, even if our system goes down for some reason.
Q: Wait a minute. So if I want to make a discussion forum, I have to make up a link to an outside page to attach that forum to? What if I just want to make a forum that stands on its own?
... and get a regular text link to that forum:
Look, everybody. The pop machine has only one button working, so we're going to have to decide whether to fill it with Diet Coke or Pepsi One. Go to <SCRIPT>sx_internalforumlink("this discussion forum", "Should we switch from Diet Coke to Pepsi One or not?")</SCRIPT> to get your two cents in.
Look, everybody. The pop machine has only one button working, so we're going to have to decide whether to fill it with Diet Coke or Pepsi One. Go to to get your two cents in.
The template system works exactly the same as with the regular weblog-style forums. (Keep in mind, though, that the "clickthrough" statistics are meaningless in this case because a standalone forum doesn't have a "target" page to speak of. The clickthrough numbers will always show up as zero, so you should exclude them from your template.)
The tempate file tells us how to format your discussion / clickthrough statistics page. You don't have to make your own, because you'll just get our template by default. However, it's just so much more fun to make it look just like how you want it to.
webmaster@sextant.civilution.com