Pages Tutorial

So you've set-up your new Hummingbird instance and you need to add a contact page.

How do you do it?

In this tutorial you'll learn how to add pages and work with templates.

Adding the page

To get started, you'll need to open the file functions.inc.php that resides under the external folder.

sshot-10

Note: This file is a common place to register stuff that you site needs and to perform run-time changes to it, so you'll find yourself adding code to it quite commonly.

Now, go to the very end of the file (but still inside of the php tags) and add the following line:

$site->addPage('contact', 'page-contact');

It should look like this:

sshot-11

With that line of code, you've just told the platform that there is a page named contact (thus accesible via /contact) and that it will use a template named page-contact.

But, what are templates?

An introduction to templates

Hummingbird includes a very simple template engine that allows you to reuse and organize your code efficiently.

In contrast to other frameworks that use middleware packages for its templating, adding lots of files and classes to your project, Hummingbird has a leaner approach to templates.

In fact, PHP is a templating language on its own, and adding another layer on top seems a bit off if you want a high performance framework.

So we took the keep-it-simple route and reduced our template support to a couple of functions: render() and partial().

But before getting started on the templating functions, let's create the template file itself.

To do so, locate the templates folder, open it and you should find two folders: pages and partials:

sshot-12

Open the pages folder and there you'll see a file named page-home.php, open it up with your text editor and you should see something like this:

sshot-13

That is the Home page template.

If you look closely, you'll notice that it doesn't have a complete HTML page. Its missing the html, header and body tags. It doesn't even have a valid DOCTYPE declaration!

But if you fire up your browser, go to your test link and look at the source code, all those the tags are in place, showing a complete HTML document:

sshot-14

If you create a site with 10 pages, all of them will have the same code to declare an HTML document, open the html tag with its contents like stylesheets and meta tags, open the body tag with the page contents and then close everything you'll repeat a big chunk of code everytime.

But if you look carefully at the Home page template you'll notice that, instead of HTML boilerplate you have a group of calls to the partial() function:

sshot-15

As you may have guessed, what the partial() function do is to simply take a fragment of code and print it in-place.

Technical note: While the native include directive can do the same (in fact that's what partial uses internally), we're using a wrapper function to deal with security issues as well as to provide a properly initialized environment for the code fragment.

These code fragments, or partials are located on the templates/partials folder:

sshot-16

There you can find the four partials refered on the Home page template: The two header and the two footer components.

When you call the partial() function, it loads these files and adds them to the original page-home file, thus completing the HTML document.

You may use partials for sidebars, widgets, toolbars and other finite components that can be reused on your site, and by including PHP code in them, you can validate or restrict certain features to very specific conditions, like hiding a toolbar if the user isn't allowed to see it, for example.

Creating the template

So, now that you know how the templating engine generates the pages, it's time to create our Contact page template.

To make things easier, copy and paste the existing page-home.php file and rename it to page-contact.php. Remember, that's the name you just used when registering it so it must match or otherwise you'll get a 404 error:

# Register the /contact page using the page-contact template
# That means you'll have top create a page-contact.php file in the templates/pages folder
$site->addPage('contact', 'page-contact');

Technical note: Please notice how when you register the template you don't include the .php extension but when you place the file on your pages folder it must have it.

Now change the title on the page-contact.php file and add a simple contact form like this:

sshot-17

Save the file and point your browser to your test link, for this example it would be http://localhost/hummingbird/contact, and after some CSS styling you should see something like this:

sshot-18

That means you page is now properly registered and the template ha been correctly placed.

Tip: To practice, create an 'About us' page on /about-us using the page-about-us template.

Go back to previous page