This entry is based on the Building Browsergames entry: Getting Started With A Templating System (PHP)

Since we’re using Ruby on Rails, we’re don’t have to select a templating system, there’s one already built into Rails itself. It offers many different features to make it easy to build web pages out of parts, cache parts of pages or whole pages, etc. As with most (probably all) parts of Rails, alternatives are available to what’s built in but you’ll be satisfied with what’s already there for quite a while.

I particularly want to amplify something Luke said in the original posting. He thought a lot of developers were fans of developing their own templating systems. Wow. If that is in fact true, then you are seriously misguided if you go down that path. What’s built into Rails and the Smarty templating system Luke used for his PHP work is more than enough to get your pages done. Do not waste your time on side projects like building a templating system, use the time to improve your overall programming skills or build your game. If you do, you might be one of the few percent who actually finishes a project and others get to play it.

Using Rails Views

The design of Rails is already about separating the view which builds our HTML from the controller which connects the model to the view. So displaying the user’s name in the view is as simple as adding some code like the following to the already existing app/views/welcome/index.html.erb:

<%= render :partial => 'users/user_bar' %>
 
<% if flash[:notice] %>
  <%= h flash[:notice] %>
<% end %>
 
<h1>Welcome To The Game</h1>
 
<% if logged_in? %>
  <p>Hello, <%= @current_user.login %>!</p>
<% end %>

It’s the same as it was before except that we’ve added the section at the end that checks to see if we’re logged in and greets us if we are. Now, as long as the controller method that is called for this page sets up a @current_user variable the view will pull the login out of it and display it within the page. The restful_authentication plugin provides us with an easy to use function to check if the user is logged in or not and put the user’s info into the @current_user variable if he/she is. We’ll call that from our controller (app/controllers/welcome_controller.rb) in the index function (remember, the flow of a user’s page request always goes to the controller first to set everything up and then to the view from there).

def index
  current_user
end

If you recall from before, the old index method didn’t do anything. Now it calls the function which will fill in the @current_user variable before the index.html.erb file gets used to generate the view. At this point if you login you should find that everything works nicely.

By this point we’ve seen that the templating code (in the .html.erb files) gives us the ability to include partials pages to reuse sections of HTML, pull data from variables, and even conditionally show or not show parts of the page.

Extra Credit

1. To learn more about the functions that restful_authentication makes available to you, look in the file lib/authenticated_system.rb. There are several functions in there to help you determine whether or not the user is logged in, restrict pages from users who aren’t yet logged in, etc.

Working Title only has a few pages that will need to be displayed – according to Design 1.0, there are a total of 7 – Home, Design Document, Register, Login, Logout, Codex, and Play. This will make developing the templates very easy, as there are only a few that I need to build.

I’m going to use HTML::Template for my templating system, just like we have been in our Perl-based browsergame tutorial. However, my templating setup will be slightly different; I am planning on nesting two templates within each other. I’ll have a simple outer template which defines some of the global styles for all of the pages, and then another inner template that is populated with the information unique to the page(this is an example of applying DRY to my templates).

To that end, I’ve whipped up a quick outer template for Working Title, that will(for the moment) do what I need it to. There isn’t much to it, but you can take a look at it here.

Is it a rough template? Yes. Will it change before Working title is done? Probably. But it’s enough to get me up and running, and free up my time to work on developing the rest of the game, instead of just working on the template.

But there’s a nebulous step in between designing your game and actually building it, that a lot of new developers tend to miss: your game’s template.

While we’ve been working through how to build a game, we’ve been creating some very basic HTML for our templates – but nothing fancy, and definitely not what you’d want to use for a game you planned on releasing to the public.

So what’s a developer to do? Most of the developers I know couldn’t design their way out of a wet paper bag – no matter how much they may try to delude themselves otherwise. If you’re a developer reading this and you actually can design, go celebrate – you are a true rarity among developers.

Thankfully, for those of us who can’t design, there are options out there. Here’s a couple of sites that will help you out with building your template:

• Layout Gala

  Layout Gala is one of my favorite websites for this sort of thing – 40 CSS based layouts written with valid CSS and HTML, and good cross-browser compatability. Whenever I’m building something, I tend to start with a LayoutGala layout and hack it to suit my needs. They’re all free to use, and as far as I can tell there’s no license placed on them stating you need to attribute their author – although I tend to leave a comment in my source code for anyone who’s really interested.

• Arcsin Templates

  Arcsin Templates has a lot of neat, free templates – both for regular websites and Wordpress. The only rule is that if you use their templates for free, you need to leave the link back to their website intact – but if you’re willing to spend $20 US, you can pay for the rights to remove the link. The benefit to using an Arcsin template over one from LayoutGala is that it’s already nicely styled and graphic’d – with a LayoutGala template you’ll need to re-style it yourself, whereas an Arcsin template is ready to go right out of the box.

• Elance

  Finally, if you’re willing to shell out a bit more cash for your design and get it done by a professional, you can use services like Elance – all you have to do is put up your project and a detailed description, and watch people bid on it – then you choose which bidder will do the project for you, and wait. While I haven’t personally tried Elance, I’ve heard a couple of raving reviews over it – much moreso than any other online outsourcing service.

These are just a few of the options available to you when looking to build your site’s template – and everyone’s preferences are different. While I prefer Layout Gala templates and then modifying them to whatever I need them to be, you might prefer something pre-built like Arcsin’s templates, or even getting something build-to-order with Elance. They’re all valid approaches, and they’ll all help you hammer out that template before you start building anything.

It’s important to choose a templating system before you start building any functionality more complex than your registration and login system – it will help you speed up your development time, and keep your code and your design separate. If you’re like me, that means that you can safely pass your template off to someone who actually can design, and get them to work their magic on your template – without having to worry about your code breaking.

To that end, what Perl templating systems are there out there?

There are a lot of Perl templating systems available. There’s Template::Toolkit, and HTML::Template, and scores of others. For the sake of this quick guide, I’ve chosen to use HTML::Template – although really, you can use whatever templating system you want to(although my examples will all use HTML::Template).

To begin with, we need to install HTML::Template. There are a number of ways to go about this, and if you’ve never installed a Perl module before I recommend that you read this guide to installing CPAN modules, and then install HTML::Template on your system. Alternately, a lot of systems with Perl on them come with the cpan shell – at which point all you need to do to install the module is run this command:

1

cpan install HTML::Template

At this point, HTML::Template is installed – so let’s build a quick tester script to take advantage of that. First off, we’ll set up the template for the index page that our login page from earlier sends non-administrator users to:

1
2
3
4
5
6
7
8

<html>
<head>
	<title>My Index Page</title>
</head>
<body>
	<p>Hello, <!--tmpl_var name='username'-->!</p>
</body>
</html>

It looks like a regular HTML file, doesn’t it? And that’s the great thing about templating systems. With a templating system, you can write regular HTML and just intersperse markers for whatever content you’re going to dynamically add, instead of hard-coding your content into your template.

We’ll call that template file index.tmpl – our index page will load it in when it outputs the user’s information. Really, you can use whatever extension you like – I just like .tmpl.

The next thing we need to do is write the code for the page that actually loads in and outputs the template. Here’s what that looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#!/usr/bin/perl -w
 
use strict;
use CGI qw(:cgi);
use HTML::Template;
 
my $query = new CGI;
my $cookie = $query->cookie('username+password');
 
my ($username) = split(/\+/,$cookie);
 
my $template = HTML::Template->new(
		filename	=>	'index.tmpl',
	);
$template->param(username	=>	$username);
print $query->header(), $template->output;

All we do in this code is load in the value of the cookie that we set in our login page – named ‘username+password’. Then, we split it based on ‘+’, to return our username and password – because we only need the username, we discard the password:

10

my ($username) = split(/\+/,$cookie);

This obviously shows us that there’s a bit of a problem with our cookie – if a user signs up with a ‘+’ in their username, our split will no longer work! One good way to work around this is to use something a little more complex to divide our username and password, or modify our code slightly to use a regular expression capture instead of split:

10
11

$cookie =~ /(.+)\+/;
my $username = $1;

This way, we’ll retrieve all information that comes before the last ‘+’ sign – because crypt returns characters in the set [./0-9A-Za-z], we don’t need to worry about a ‘+’ sign cropping up and wrecking our regular expression.

Once that’s done, all we do is create a new template object, tell it where to load our template from, and then populate the paramater ‘username’ with the value we pulled out of our cookie. And then we’re finished!

As you can see, working with a templating system isn’t that hard – and the gains you make by being able to instantly use the same template accross many pages are huge. There’s really no reason not to be using some sort of templating system – whether you roll your own, or use a pre-existing system.

If you want to see the example code in action, register, and then login, and you’ll be redirected to the index page – which will display the value out of our cookie.

The answer is that you can – and should. It will help you separate your design from your code, which(if you’re anything like me) means that you can have someone with actual designing skills come through and fix up your template before you push your site out to the rest of the world.

This will be a brief rundown on how to get up and running with a templating engine, which is what we will be using to build all of the other parts of our browsergame in progress. For a PHP templating engine, I’ve chosen Smarty. I did this by taking a look at Smarty’s list of features, and deciding whether I liked them or not – when you choose a templating engine, that’s really all the forethought you need to put into it – will it work for you, and are you okay with working with it? As an aside, if you don’t like your templating system you can always switch systems for your next project.

A lot of developers are fans of “rolling their own” templating system. While this can definitely work, you’re probably going to make larger gains by simply using an existing one – if you need anyone to help you with your game later(or it really takes off and you hire someone), it will be a benefit to be using a system that they might already know as opposed to a proprietary system. Also, why do all that work when it’s already been done for you?

The Smarty website has a smarty quick start tutorial, which you can use to get yourself up and running with Smarty.

Once you’ve gotten Smarty set up on your system, we’ll be building the index page that our login page from earlier redirects to for non-administrator users. To start off with, we’ll just use the testing index.tpl file from the Smarty quick start:

1
2
3
4
5
6
7
8

<html>
<head>
	<title>My Index Page</title>
</head>
<body>
	<p>Hello, {$name}!</p>
</body>
</html>

Next, we’ll use the index.php file from the Smarty quick start, and modify it so that it displays the currently authenticated user’s username:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php
 
// put full path to Smarty.class.php
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty();
 
$smarty->template_dir = '/web/www.domain.com/smarty/templates';
$smarty->compile_dir = '/web/www.domain.com/smarty/templates_c';
$smarty->cache_dir = '/web/www.domain.com/smarty/cache';
$smarty->config_dir = '/web/www.domain.com/smarty/configs';
 
session_start();
$smarty->assign('name', $_SESSION['username']);
$smarty->display('index.tpl');
 
?>

As you can see, there isn’t that much of a change made – we add a call to session_start() to load up our previously stored session values, and then we use one of them to display the user’s username. If you visit your testing page, you should see the username that you logged in with – which means that Smarty is working! With Smarty we’ll be able to make sure that our code and designs no longer have to be intermingled – meaning that there’s less chance of accidentally screwing up one while working on the other.

If you want to see it in action, you can first register, then login to get redirected to the index page – which will show you the username you’re currently logged in with.