JS Guide

So far we haven't covered JavaScript at all! Well unless you count the editing of the config file. Static Ultra handles JavaScript files in a very similar manner to how it handles stylesheets.

Site-Wide JavaScript

Sometimes you want JavaScript to run regardless of theme or page. Maybe you're using a library or a third party script.

Static Ultra enables you to have as many side-wide scripts as you want, and you can name them whatever you want.

Open su-config.js for editing. Scroll down and you'll see a section like this:


	this.SITE_SCRIPTS = [
		"site.js"
	];

This is your place to put site-wide scripts. Static Ultra comes with a site.js that is prepared for use, but does nothing so that if you decide to add site-wide JS functionality, you're good to go.

Adding additional site-wide scripts might look like this:


	this.SITE_SCRIPTS = [
		"my-library.js",
		"my-library-extras.js",
		"site.js"
	];

These scripts will be loaded once on first page load. Static Ultra then looks for a special class with events (which just so happens to already be in the site.js mentioned above):


	function SUSite()
	{
		this.onSiteLoad = function()
		{
			console.log( "suSite.onSiteLoad()" );
		}
		
		this.onThemeLoad = function()
		{
			console.log( "suSite.onThemeLoad()" );
		}
		
		this.onPageLoad = function()
		{
			console.log( "suSite.onPageLoad()" );
		}

		this.onPageUnload = function()
		{
			console.log( "suSite.onPageUnload()" );
		}
		
		this.onThemeUnload = function()
		{
			console.log( "suSite.onThemeUnload()" );
		}
	}

	var suSite = new SUSite();

These are your entry points for actually doing stuff.

onSiteLoad() is called when someone visits your site. It's not called again until a visitor starts a new session, e.g. if they go and visit another site, then visit your site again, or if they close their browser and visit your site again.

onThemeLoad() is called when a theme is loaded, as soon as the theme HTML has been inserted. This will happen when someone visits your site (since the default theme has to be loaded) or if the theme is changed by the user switching themes, or by a page forcing a theme with theme override. It's a place where you can do theme related stuff, although you'll usually want to do that in the theme itself as per the themes tutorial.

onPageLoad() is called every time the page changes, as soon as the theme and page HTML has been inserted. An example of using this is as follows:

The onPageUnload() and unThemeUnload() functions are called when the page changes or theme changes, but just before the page or theme are actually removed, giving you a chance to free up memory or whatever. I've yet to need them myself, but you never know. :P

As an example, the su-config.js for this Static Ultra website you're looking at now is as follows:


	this.SITE_SCRIPTS = [
		"js/prism.js",
		"js/site.js"
	];

Prism.js is a free syntax highlighting library that colours in all the code blocks on this site. However to make it run, I need to call a function whenever a new page is loaded. Here is my site.js:

This saves me having to include Prism on every page that uses it, because it is loaded once, and then ran on every page.


	function SUSite()
	{
		...

		this.onPageLoad = function()
		{
			Prism.highlightAll();
		}

		...
	}

	var suSite = new SUSite();

Ya gets?

Theme Specific Scripts

Static Ultra has a special class and events for themes too. In fact, the default theme uses it, but it's a tad complex for an example. Let's say you wanted to add scripts to the theme from earlier in the tutorial. You could create a theme.js and paste in the following:


	function SUTheme()
	{
		this.onThemeLoad = function()
		{
			console.log( "Called when this theme has loaded" );
		}

		this.onPageLoad = function()
		{
			console.log( "Called when a page is loaded, but only when this theme is active" );
		}

		this.onPageUnload = function()
		{
			console.log( "Called when a page is unloaded, but only when this theme is active" );
		}

		this.onThemeUnload = function()
		{
			console.log( "Called when this theme is unloaded" );
		}
	}

	var suTheme = new SUTheme();

Then you just put the following in your theme.html:


	<script src="theme.js"></script>

Page Specific Scripts

And finally, sometimes you just want scripts only on a specific page. Let's explain this one by example.

Right here, we have a button! Try clicking it. It's a very polite button!

The HTML for the button is as follows:


	<p>
		<input type="button" class="js-test" value="Click Me!">
	</p>

The script that makes it work is located at js/js-guide.js on my website.

To include it in my page, I put the following just after <body> in this page.


	<!-- [SU_SCRIPTS]
		js/js-guide.js
	[/SU_SCRIPTS] -->

And JS Guide contains the following:


	function SUPage()
	{
		var testBtn = null;

		...

		this.onPageLoad = function()
		{
			testBtn = document.querySelector( ".test-button" );
			testBtn.addEventListener( "click", onTestBtnClick );
		}

		this.onPageUnload = function()
		{
		}

		...

		function onTestBtnClick()
		{
			if( testBtn.value == "Click Me!" )
			{
				testBtn.value = "Thanks for clicking!";
			}
			else
			{
				testBtn.value = "Click Me!";
			}
		}
	}

	var suPage = new SUPage();

If you have multiple scripts on the same page, you can include them like following:


	<!-- [SU_SCRIPTS]
		js/js-guide.js
		js/some-other-script.js
		js/some-even-more-other-script.js
	[/SU_SCRIPTS] -->

There's one more thing you might want to know about. And that's re-usable HTML blocks!