Enrober basics - Tutorial

Why Enrober is necessary

A common pattern in PHP is to start each page by including an external header file and end it with an external footer file, allowing all the pages on a site to share a common look.

```
<?php include('header.php'); ?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

```
<?php include('footer.php'); ?>
```

This approach works well but it has its drawbacks. Since the <head> tag is inside header.php, you can't change things in the document head such as giving each page a unique title or a page-specific CSS file. With a bit more work you can pass things into header.php by defining some variables before including header.php.

```
<?php
```
```
$page_title = 'Example Page';
```

$css = '<link href="page_specific.css" rel="stylesheet" type="text/css" media="all"></link>';

```
include('header.php');
```
```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

```
<?php include('footer.php'); ?>
```

Doing things this way can quickly become unmanageable.

Enrober is a PHP object that offers an easier and more flexible way of wrapping a page in a theme. Enrober also offers a number other advanced features including the ability to cache the generated page for quicker retrieval later.

Installing Enrober

After downloading Enrober unzip it. You'll find a number of files and a couple of directories. The "docs" directory contains documentation of Enrober's API; this is a good place to look to get to know Enrober's features better.

To install Enrober, simply copy the "enrober" directory into the document root of your web server. No additional configuration is needed to get things up and running.

Basic usage

After including enrober.php, the most basic use of Enrober can be accomplished with a single line of code:

```
<?php
```
```
include_once('enrober/enrober.php');
```
```
$enrober->go();
```
```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

$enrober is an singleton object that enrober.php automatically creates; all of Enrober's functionality is accessed through methods of the $enrober object. The go() method should be called before the calling script creates any output. go() buffers the page output, wraps it in a theme, and applies any content filters that have been added to the $enrober object previous to invoking go().

Basic configuration

Configuration files for Enrober are kept in the "cfg" subdirectory. The default config file is named "config.default.php".

If you want to make changes to the config, rename it "config.php". If it exists, Enrober always tries to read "config.php" and use it instead of "config.default.php". Copying the default config instead of just editing it will ensure that installing a new version of Enrober will not overwrite your customized files.

There are a number of configuration settings that are not necessary to get things working, but allow you to customize your site. This is done by editing constants in config.php. ENROBER_SITE_NAME and ENROBER_TAGLINE constants change the name and tagline that show up in the template headers. You might also want to change the ENROBER_DEFAULT_THEME constant. The default theme that currently ships with Enrober is called "simple", Enrober also comes with a theme called "pressy" or you can create your own (more on this later).

If you want to rename the directory or put the Enrober directory in a subdirectory of your web root, you can change the ENROBER_URL constant in /enrober/cfg/config.php to point to the new path instead of "/enrober". For instance if your site is at "http://www.example.com/useres/~foo/" you would set ENROBER_URL to "/users/~foo/enrober".

Adding a title to the page

The previous example is a pretty boring use, it will wrap the page in the default theme and won't include any extras such as a <title> tag. We can add a title to the page by adding it as a parameter when we call go().

```
<?php
```
```
include_once('enrober/enrober.php');
```
```
$enrober->set_theme('pressy');
```
```
$enrober->go('Enrober example');
```
```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

Adding the parameter to go() has set the page <title> tag to 'Enrober example'. You may have also noticed The call to set_theme(). Set theme overrides the default theme, in this case it is loading the Kubrick inspired 'pressy' theme instead. If you want to change the theme on all of your pages, it's best to just change the ENROBER_DEFAULT_THEME constant in your config; but if you need a specific page on your site to have a different theme, set_theme() is the tool for the job.

Adding META descriptions and keywords

Meta tag descriptions are usually used as descriptive text on search engine SERPs and can be quite useful. Meta-keywords are not as useful today since Google and most other search engines completely ignore meta keywords. Enrober adds descriptions and keywords with the add_desc() and add_keywords() methods respectively.

```
<?php
```
```
include_once('enrober/enrober.php');
```

$enrober->add_desc('This is an example page showing how to use add_desc() and add_keywords()');

$enrober->add_keywords('list,of,keywords');

$enrober->add_keywords(array('arrays', 'work', 'too'));

$enrober->add_keywords('more, calls, to, add_keywords, add, to, list');

$enrober->add_desc('Unlike add_keywords(), multiple calls to add_desc() replace the old value.');

$enrober->go('Description & Keyword example');

```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

Adding per-page CSS and JavaScript files

Standard CSS and JavaScript files that need to appear on all of your pages should be included as part of your theme files, but sometimes you might need to insert page-specific CSS or JavaScript into a page. CSS and JavaScript files can be inserted into a page by using the add_css() and add_js methods respectively.

```
<?php
```
```
include_once('enrober/enrober.php');
```
```
$enrober->add_css('example.css');
```
```
$enrober->add_js('example.js');
```
```
$enrober->go('Enrober CSS/JS example');
```
```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

Canonical URLs

Often there are multiple ways to get to a webpage. A site might be reachable with or without a www prefix or from a completely different domain name. A index page can usually be reached by just entering the URL of the directory it is in, or by it's full name (index.html, index.php, etc). Including or excluding the trailing / on a URL will usually yield the same page too. A page might have a query sting attached to it that doesn't really effect the content of the page.

Search engines are usually pretty good at figuring out if two URLs are really the same page, but sometimes they can not. If a search engine thinks you have multiple pages with duplicate content you can be penalized for it.

That's why Google created their canonicalization standard. Enrober makes it easy to include a canonical >link< element on each page by using it's url() method.

```
<?php
```
```
include_once('enrober/enrober.php');
```

$enrober->url('/php/enrober/tutorials/basics.php');  // The canonical url for this page

$enrober->url('http://www.example.com/php/enrober/tutorials/basics.php');  // Full URLs work too

$enrober->go('Enrober page with a canonical URL set');

```
?>
```
```
<h1>Page content goes here</h1>
```

<p>Lorem ipsum dolor sit amet, foo adipiscing elit.</p>

Theme basics

A comprehensive guide to creating Enrober themes will be posted later, but for now there a few things you need to know about using themes. Themes are stored in the "themes" subdirectory of the Enrober directory. Each theme has it's own directory. Inside a theme's directory, it consist of two HTML files and any CSS and image files that are referenced in the HTML files. The HTML files are named head.html and foot.html.

Head.html contains the header for each page including the doctype, html tag, head tag and it's content, the opening body tag, and the opening tags for anything that wraps the content. Foot.html contains the closing tags for any tags opened but not closed in head.html, including the closing body and html tags.

There are a number of theme tags that can be added to a head.html and foot.html to control the insertion of generated content, such as the page title, description and keywords. Theme tags are in the form of %tagname%. So in head.html the %title% tag will be the insertion point for the <title> tag, %desc% for the <meta> description, %keywords% for the <meta> keywords, etc. JavaScript and CSS are inserted at the %js% and %css% tags.

The official themes include the %css% tag in the header and the %js% tag in the footer. If you need the JavaScript loaded in the header you can create your own new theme with %js% or a custom theme tag in the head. There is also a special theme tag called %themepath% which contains the absolute url to the theme's files. You can use %themepath% to easily include CSS and JavaScript files from your theme directory, for an example take a look the head.html file from a theme that ship with Enrober.

You can also create your own theme tags and use them in your custom themes. For information on how to do this and the full list of built-in theme tags, check out add_tag() in the documentation that comes with Enrober .

Mobile Themes

As of version 1.1 Enrober has mobile browser detection built in. To add mobile support to your theme, simply create a subdirectory called "m" in your theme directory. The structure of the mobile theme is the same as the regular one, including a head.html, foot.html and any assosiated CSS, image or JS files. When a mobile theme is loaded, the %themepath% tag is automatically altered to refer to the "/m/" directory, so you don't need to include "/m/" in any of your file paths.

Next: Cachging (coming soon)

Back to the Enrober homepage

Useless Code