veni vidi Scripsi

Quick Templating System for HTML Page Mock-ups (Mac OS X specific)

For the project I am currently working on at my job I needed to make some HTML page mock-ups. The HTML and CSS were already available within the current version of the website, I just needed to re­struc­ture the content a bit and make a few mock-ups of it to see what sort of issues we'd run into.

Initially I just copied the HTML and replaced the old content with the new content. Then I made another copy and replaced it with different content. I then realised what I needed was a tempting system. If I was going to make 10 pages and some basic thing changed I'd have to modify 10 pages which is just silly.

My re­quire­ments were the following:

  1. It needed to be quick and easy and not overkill. I didn't want to have to install a whole framework like Django or Symfony;
  2. It needed to be based on in­her­i­tance. Ever since I learned Django I'm in love with their in­her­i­tance templating system and I wouldn't have it any other way (read: includes);
  3. It needed to be portable. I will probably have to share the HTML/code with other people and they should be able to run it in minutes.

So I searched around a bit and eventually landed on Twig. Now I'm not a big fan of PHP, you can read why HERE. But I (and my colleagues) work on a Mac which has PHP and Apache installed by default. You just need to turn it on.

The big plus of Twig is that it uses the same syntax as the Django templating system which means there was no learning curve for me. However my PHP was very rusty, so getting it up and running took a little longer.

How I made it work

Turn on Apache and PHP on your Mac

You can skip this if you've got it all set-up and running.

  1. Turn Web Sharing on in your Mac's System Pref­er­ences Sharing. It will display the IP on where you can view the pages from your Sites directory. I don't know how this would work on Mountain Lion as they've removed that option from the sharing pref­er­ences;
  2. Apache is turned on by default (at least it was on my Mac OS X Lion);
  3. Turn on PHP support in Apache by editing /private/etc/apache2/httpd.conf and un­com­ment­ing the line LoadModule ph­p5_­mod­ule        libexec/apache2/libphp5.so;
  4. Create the PHP.ini file by going to /private/etc/ and doing sudo cp php.ini.default php.ini. I also turned debug mode on: search for dis­play_er­rors in php.ini and make sure that Default Value is set to On.
  5. Create a /Users/[y­our_­com­put­er_user­name]/Sites directory if it doesn't already exist;
  6. If you'd like to run projects from other di­rec­to­ries (like I do) I recommend simlinking to them from your Sites directory. However that does mean that you'll have to turn this feature on in Apache by adding Fol­lowSym­Links to Options Indexes Multiviews in /etc/apache2/users/[y­our_­com­put­er_user­name].conf. See this Stack­over­flow question;
  7. Restart Apache: sudo apachectl restart.

Using Twig 'S­tand­alone'

  1. I'm assuming you have a folder somewhere which contains both 'base' template HTML files and the actual 'content' HTML files which inherit the base files (and which I also, for the sake of con­vie­nience, have declared to be template files), which make use of the Twig templating system. Don't forget to create the simlink from the Sites directory to your project if you've not put them in Sites;
  2. Download Twig and unzip;
  3. Place the contents somewhere useful. It doesn't matter where, I put them in my Sites folder. As a side-note: the actual working bit is the Twig folder in lib in the extracted folder, the rest is docs and tests. I got this wrong at first so pay attention to this;
  4. I created the following con­fig­u­ra­tion/loader PHP file to run my HTML files through the tempting engine. I placed it in my project folder with the HTML files. Replace the $twigPath variable with the path to your own Twig install. More specif­i­cal­ly to the Autoloader.php file. And finally point the $tem­plates­Path to where you've stored your HTML files (step 1):
 1      <?php
 2  /* File: loader.php
 3   * Usage: loader.php?file=[filename] (without .html)
 4   * E.g.: http://10.169.32.11/~heleen/OAPDemonstrator/loader.php?file=pub_almelo
 5   * Don't forget to EDIT the CONFIG
 6   * Dependencies: Twig (http://twig.sensiolabs.org)
 7   */
 8      /*** Config ****************/
 9      $twigPath = '/Users/heleen/Sites/Twig/lib/Twig/Autoloader.php'; // Path to Twig's Autoloader
10      $templatesPath = '/Users/heleen/Sites/OAPDemonstrator'; // Path to your HTML templates
11      /***************************/
12 
13      require_once $twigPath;
14      Twig_Autoloader::register();
15 
16      // set up Twig
17      $loader = new Twig_Loader_Filesystem($templatesPath);
18      $twig = new Twig_Environment($loader, array( 'cache' => false));
19 
20      // parse the template
21      $template_file = htmlspecialchars($_GET["file"]);
22      $bindings = array();
23      $template = $twig->loadTemplate($template_file . '.html');
24 
25      echo $template->render($bindings);
26 
27  ?>
  1. You are now ready to view your HTML pages. Go to your localhost URL which you'll find in Mac's System Pref­er­ences, Sharing, Web Sharing pane, and add loader.php?file=[htm­l_­file­name] to the URL. So for example I got http://10.169.32.1/~heleen/project/loader.php?file=pub­li­ca­tion. That's it!

Note

To summarise my personal setup: Twig is in my Sites foleder. The Sites folder also contains a simlink to my project folder. My project folder containes both the loader.php, the HTML template files, and the content files which inherit the template files. To run it the url is: [path to Sites folder]/[project folder]/loader.php?file=pub­li­ca­tion.

Pretty URLs

Edit 14 May 2013: if you would like prettier URLs I can recommend using Apache htaccess. To get links like /pub­li­ca­tion.html instead of /loader.php?file=pub­li­ca­tion read my blog post to enable htaccess on the Mac and add a .htaccess file to your project root with the following contents:

Options +FollowSymlinks
RewriteEngine on

RewriteRule ^(.*)\.html$ loader\.php?file=$1 [NC]

Sources

TinyMCE in one of multiple Textarea fields in Admin » « Oh no! I've Forgotten my Django Admin Password!