Introduction

Ocular was designed to help you get more done, with less code written on your part. It was heavily inspired by Rails' ActionView library, though it has started to go it's own way since then.

Why Another Template Engine?

There are already so many template engines out there that can be used with CodeIgniter, even including not using one and just sticking with the default libraries and straight php that CodeIgniter provides. Why make another one?

While working on my first big project with CodeIgniter, I realized how much stuff had to be done for each function to get a common display. I tried various template engines found from the Wiki, and, while they were all good, none was as simple to use as I wanted. To me, the ideal template engine provides what you need, then gets out of the way. It assumes enough that you can get started and use very little code in the process. Streaminling the development process - that was the goal. Why fight with the display process when you've got more creative uses of your time with the rest of your site?

So I went back to some of my experiments with Rails and starting building my own library. It's easy on designers and developers both.

Convention, not Configuration

That's Rails' motto throughout, and we've all seen or heard how rapidly it allows you to put an application together. Instead of having to configure everything before you call, it makes intelligent assumptions about how things work. As long as you follow along with the conventions of Ocular, it does as much for you as it can, and gets out of the way. For more information on the conventions, read through the Configuration page.

Since CodeIgniter creates url's out the controller and function that's being called, that seemed the best way to manage your views.

All that's necessary for rendering the page from within your function is to call:

$this->ocular->render();

Site Templates

Every site has one (or more) basic templates that it uses. This probably has the header and footer the same on every page, and a place for all of the rest of the (changing) content to go smack dab in the middle. That code template becomes your site layout. By default, it is named application.php in the template directory of your views folder, but can be renamed in the config file.

Don't worry, you can always specify a different template for different portions of your site, like the Admin section.

As of version 0.25, Ocular checks for templates within the /views/templates directory that matches the name of the controller being called. If it finds it, that template is used instead of the default (/views/templates/application.php). This allows each controller to have their own tweaked layout. Maybe including different sidebars or menus?

Yield, please

You know that spot in the middle of your site template where you want the content to go? Simply put a yield() function call in there, and let Ocular do it's magic. It should look something like this:

<div id="content">
  <?= $this->ocular->yield(); ?>
</div>

When called, Ocular pulls up a new view based upon the controller name and function name.

Auto Views?

How does Ocular determine what view to display within the site layout? That's easy. It's all based on your controller name and function name. It looks in the views directory that you've specified for a folder with the same name as your controller. Then it looks for a view with the name of the function being called. Here's a quick example:

Let's say that a user wants to register for your site. You're registration function is in the Auth class, and the url looks like: www.my-site.com/auth/register.

Ocular would look in the following place for the view file:

/application
  /views
    /auth
      - *register.php*

And it would look for the template to wrap it in here:

/application/
  /views
    /templates
      - *auth.php*

Why enforce a standard location like this? Because it helps to keep things organized during a big project, and makes things as fast as possible for Ocular to find the view it needs. I've tried to keep Ocular as fast as I could, while still maintaining enough flexibility to get the job done.

Menus and Ads and Partials, oh my!

A number of frameworks use the term partial to describe a block that gets used over and over. Ocular uses this concept, also. By using partials, you can stick to the "Don't Repeat Yourself" mantra, and make changing your site down the line a no-brainer.

Within your template, simply insert the command render_partial() to display a view that holds just that one piece of information. It could be a menu block, or it might pull information from your Ads module and show it in the right space. There is no limit. Here's an example template file using partials:

<html>
<head>
  <title><?= $page_title ?></title>
</head<
<body>
  <!-- Site Branding or Header -->
  <div id="branding">
    <?= render_partial('/branding'); ?>
  </div>

  <!-- Main Content -->
  <div id="content">
    <?= $this->ocular->yield(); ?>
  </div>

  <!-- Sub Content, or Sidebar -->
  <div id="content_sub">
    <?= render_partial('menu'); ?>
  </div>
  
  <!-- Site Info or Footer -->
  <div id="site_info">
    <?= render_partial('/site_info'); ?>
  </div>

  </div>
</body>
</html>

If you include a "/" before the partial name, it looks for it in the /views/templates directory. If it doesn't find it there, it looks in the current controller's directory. All partials must be prefixed with an underscore, so the file list needed for the above template would look like this:

/application
  /views
    /controller
      - _menu.php (this might be a menu specific to each controller)
    /templates
      - _branding.php   (the "header" partial)
      - _site_info.php  (the "footer" partial)
      - application.php (the main template)

Scripts and Styles

Okay, you've got some working pages now, but you want to make them look pretty, right? Easily enough done. Ocular provides tags for inserting stylesheets and scripts.

Why use Ocular's instead of hard coding it? One reason is for flexibility. If you setup your primary files in the config file, then call the defaults from each template, you only have to change it in one place. Future versions will also provide minification and cacheing.

The most important reason, though, is for faster page display. This isn't the time that it takes your application to create the layout. Instead, this helps the page display in the browser faster, by compiling all of the scripts into one server call, thus reducing the user's wait time while the server responds to several different calls. In future versions, the option to compress and minify your code will be there, also, all handled with these two simple calls.

Stylesheets

To use the defaults stylesheets as specified in the config file, use the following call in your application.php layout file:

<?= stylesheet_link_tag(); ?>

You can specify the media of the default stylesheets like this:

<?= stylesheet_link_tag(":screen"); ?>

To specify stylesheets different than the default, do it like this:

<?= stylesheet_link_tag("reset", "application", ":screen"); ?>

Javascripts

Javascripts are included in much the same way. A default is specified in the config file, and they can be inserted like so:

<?= javascript_include_tag(); ?>

Specifying your own is done like this:

<?= stylesheet_link_tag("jquery", "effects"); ?>

What about MY data?

In almost every view, you're going to need to pass data to it to be displayed. To do this with Ocular, you can simply set and get the view_data which is then passed to the views when they're rendered, just like you would with any other CodeIgniter view.

Setting Data

To make data available for use within your views, you just pass a string or array into Ocular with the

$this->ocular->set_view_data('key', $value);

Once set, this data is available in your views as a variable with the name you passed into the set_view_data function, just like standard CodeIgniter functions.

Getting Data

While you'll probably never need this function, you can also get the data out by passing the name of the variable you want into the:

$this->ocular->get_view_data('key');

Reserved View Data Names Several names are used for special purposes within the view_data. These names are always given a default value if you have not set one before calling the render() function. They are as follows:

• page_title - The page title and site name that appears in the html head section, and displays on the browser title bar. In the Configuration section, you can specify the site name, whether it is prepended, or appended to the page name, and the type of divider used. When setting a value for this, do not include the site name or a divider. This defaults to a phrase built from the controller and function that is being displayed. The format is as follows:

Function_name Controller_name

Some examples might be:

- Create Users
- Edit Pages
- Delete Stories

You can farther refine what is displayed in the page title by using the following function:

 $this->ocular->show_in_title();

It accepts the following constraints: 'function', 'controller', and 'none'. To reset what is shown, call the function without any arguments.

• body_id - An id that can be attached to the html body tag. This defaults to the Controller name. The string passed to the views contains the "id =" portion of the tag, so you do not have to set that in your variable or your layout.

• body_class - A class that can be attached to the html body tag. This has no default value. The string passed to the views contains the "class =" portion of the tag, so you do not have to set that in your variable or your layout.

• view_name - if you want to render a different view from within your function than Ocular would default to, set the view_name variable and Ocular will handle the rest.