Documentation

Part 1) Installation

If you've already read the Installation Page and are still having trouble, this is the place to be. We'll start here where we left off there.

Configuring Your config.php File

A very important part of the inner workings of Templatto is the config.php file, conveniently located in the "templatto" folder. This file contains all of the (duh) configuration settings that Templatto will use to do its job. There are two PHP variables in this file that you'll HAVE TO HAVE TO HAVE TO change.

The first important PHP variable is the "$absolute_path" variable. This is the absolute path to the location of the directory that houses the "templatto" folder. Since this will most likely be a Linux file system path, it might throw you off a little bit. Luckily, if you read the notes in the config file, you will have noticed that you can echo out the "$_SERVER['DOCUMENT_ROOT']" variable to help give you a better idea of where you should make this. It'll probably look something like "/root/user/www" and there's a good chance that this is what you'll need to put in for the "$absolute_path" variable. You might have to tack on an extra folder or two. Just remember not to put a trailing slash on there.

The second important PHP variable is the "$absolute_url" variable. This is simply the absolute "HTTP" link to the location of the directory that houses the Templatto folder. Say your website is "www.pancakepeter.com," and you're using Templatto as your main templating script (ie. it's not in a subfolder), then what you'll put here is "http://www.pancakepeter.com" without a trailing slash.

There are a few other things you can change in your config.php file, put nothing that's needed to get it running.

Modifying Your .htaccess File

If you've followed the instructions on the Installation Page and you're still having trouble with your .htaccess file, then I can't help you. Luckily for you, Apache can. Templatto uses mod_rewrite, which is an Apache module written by someone who likes to write things that people will never fully understand, even after looking through the documentation a few times. Even though I can't help you with all that mod_rewrite stuff, I can tell you exactly how Templatto works.

Part 2) How Templatto Works

The way Templatto works is very simple, so I'm going to try and make this explanation simple. Let's take this page as an example, and assume that I'm using Templatto on this website (which I am). You go to "http://www.templatto.com/documentation.php" and it looks like you went to a static PHP file, but you've been duped! Mod_rewrite made you THINK you went to a static file, when in actuality, you went to the following: http://www.templatto.com/templatto/templatto.php?page=documentation. Templatto then grabbed the page "documentation.php," pulled the necessary variables out of it, and displayed the page with a nice little template surrounding it. Neat, eh?

File Name Conventions

Since I'm on the subject, I might as well tell you now that your HTML/PHP files must abide by certain naming conventions. Don't worry, though, they're actually for your own good. And when I say "conventions," I really mean "convention." All they have to do is be matched by the following regular expression: ([0-9a-zA-Z_\-\/]+).php. What that regex means is that your file name can only contain letters (upper and lower case), numbers, and dashes. It also must be followed by ".php" and not something else like ".html" or ".asp." You should note, though, that this can be changed quite easily with a few keystrokes, if you know what you're doing. If you don't know what you're doing, go ahead and fool around. If you break things too much, you can always re-download Templatto, right?

Templatto Works Throughout All Subfolders

As the title already told you, Templatto will put a template around all pages in all subfolders under which the .htaccess file is contained. Perhaps you're wondering what you're supposed to do if you want a certain file or folder to NOT pass through the templating engine. It's simple:

To deactivate Templatto for an entire folder (and all folders contained within that folder), add an .htaccess file with the following command in it: RewriteEngine Off. In fact, you might have noticed that the Templatto directory contains just such a file, which you can copy, if you'd like.

To deactivate Templatto for a single file, simply add an "@" to its filename. This works because of the regular expression used to match file names, which doesn't pick up files that have an "@" in it. Easy, right? There are other characters that will work just as well, too, in case you don't like "at" signs. (Usage Example: instead of "party.php," make it "@party.php" or "p@rty.php.")

Part 3) Using Templatto

Templates

The easiest way to get started with Templatto is to simply hack away at the default template until you get things looking just right. Knowing a good bit of HTML and CSS can certainly go a long way. If you need tutorials for those things (or more), I'd suggest you check out w3schools.com or tizag.com, or both. They're pretty good resources for n00bs and pros alike.

PHP Functions in Templates

To make the templates work properly, you'll need to use a few PHP functions. If you're afraid of PHP, don't worry, they're of the Cut 'n' Paste variety. Here's a nice little list of the functions:

<?php get_header(); ?> - This one grabs the "header.php" file in the template's directory and spits it out wherever you stick this function.
<?php get_content(); ?> - This function prints out the content of the page being call up. For example, this text you're currently reading what brought to you by this function.
<?php get_footer(); ?> - As you might have guessed, this function will grab the "footer.php" file from your template's directory, and of course, displays it where you put the function, which is generally at the bottom of the page.

Regular Pages

Finally, we're at the most important part of the documentation. The whole reason you're using Templatto is to put a design around your regular pages, right? Here's how to do it:

Say you have a regular HTML file that looks something like this:

<html>
     <head>
          <title>This Page Rocks!</title>
          <meta name="description" content="This is the most awesome page ever.">
          <meta name="keywords" content="keyword, party time, excellent">
     </head>
     <body>
          <h1>Awesome Page!</h1>
          <p>
               This page is so cool, that it's amazing.
          </p>
     </body>
</html>

Clearly, the above page isn't going to have any style associated with it, as it doesn't have a header, footer, or stylesheet, but Templatto will gladly fix that. Here's the same page in Templatto, but this time with a sweet design surrounding it:

<?php

$pagetitle = "This Page Rocks!";
$metadescription = "This is the most awesome page ever.";
$metakeywords = "keyword, party time, excellent";

?>

<h1>Awesome Page!</h1>

<p>
     This page is so cool, that it's amazing.
</p>

As you can see, this newer example is a bit simpler, which is cool, but that's not why we did it -- it also put a template around the content, effortlessly. Click here to see what the first example looks like, then click here to see what the second example looks like, using this website's template. Be sure to "View Source" on the second example to get a feel for exactly what it is that Templatto does.

Templatto Variants

We're using "variant" as a noun, not an adjective. A Templatto variant is a PHP variable used inside of individual pages to configure Templatto on a page-by-page basis. In the example above, three variants were used: $pagetitle, $metadescription, and $metakeywords. There are a lot more Templatto variants that you can use to tweak your page so it's just right:

$pagetitle: This variant is used to tell Templatto (and the browser) what the title of the page is.
$pagename: The $pagename variant is a little like the $pagetitle variable, but instead of being used for the entire page title, it is only used for part of the page name. An example of this variable can be seen on this page, by looking at the title of this page. Notice that the full title of this page is "Templatto Documentation « Templatto, the PHP-based website templating engine." The "Templatto, the PHP-based website templating engine." of the title is simply the website name, which is set in the Templatto config. The "Templatto Documentation" part of the title is from the $pagename variable.
$metakeywords: This variant simply sets the meta keywords for the particular page, which should be different for every page you have, depending on its content.
$metadescription: This variant, similar to the one above, sets the meta description for each page.
$template: If you want to use a completely different template for a particular page on your website, simply set this variant to the name of the folder that your template is in. The $templatepage variant can be used to specify which template page should be used, and if it's not set, the "main.php" page will be used by default.
$templatepage: The $templatepage variant is used to tell Templatto which page of your template to use. The default is "main.php," but you can set it to anything you'd like. This variant is used if you want to have two different page layouts, but use the same basic design for both.

Since a variant is simply a PHP variable, you can make new ones as you need, and simply use it wherever you need -- in the Templatto configuration, in your template, or anywhere else. You should note, though, that since variants are used by Templatto, you probably shouldn't use variables bearing the same names in your PHP code. If you really need to, you can always change the variant names... just make sure you change them in the templatto.php file!