Ocular Layout Library
Ocular Layout Library v0.10
The Ocular Layout Library is a set of functions for the Code Igniter PHP framework. It is heavily inspired by the Rails ActionView functionality (and it’s associated helpers). It was designed with Code Igniter version 1.5.4 and PHP 5. No testing has been done to verify whether it works on PHP 4 or not.
Here are a few of the features that it provides you, simply by installing the library.
* Automatically finds and uses views based upon the controller/function name in the URI.
* Uses “application” as a default name for your main template, your css and javascript files. This can be overridden, but makes for a nice default.
* Built in function to render view partials from within other views. This helps us to “Don’t Repeat Yourself”.
* Simple mechanic for passing data to views and partials.
* Automatically combines multiple stylesheets and javascript files to speed up page display for the user.
* Simple creation of static pages with 2 lines of code.
NOTE: This library is now being hosted at Google Code.
Changelog: 11-19-07:
- minor bugfixes.
- modified to allow AutoPages. 11-28-07
- Added remapping example
First, extract and install the files into the proper directories. This should be apparent from the zip file, but a list of files is included at the bottom of these docs for your reference.
In your autoload.php file, you need to autoload the ‘Ocular’ library, and the ‘ocular’ and ‘url’ helpers.
Once the files are installed, you should create the basic template for your site. This could include things like the header and footer that are common throughout the site. Wherever you want your content to be inserted, just add the following line:
<?= ocular::yield() ?>The yield() function will automatically insert a view based on the controller and function listed in the uri. If you’re writing a blog, you might have a uri that looks like: http://www.my-app.com/blog/post/id. Ocular will look in the views directory for a directory named blog and a view named post.php. This view will be automatically inserted.
A sample application.php view file might look like this:
<html>
<head>
<title>My Great App</title>
</head>
<body>
<div id="branding"><h1>My Great App</h1></branding>
<div id="content">
<?= ocular::yield() ?>
</div>
<div id="site_info">
<p>Copyright © by someone</p>
</div>
</body>
</html>The file views/blog/posts.php might look something like this:
<div class="posts">
{blog_entries}
<?= render_partial("post") ?>
{/blog_entries}
</div>There are two important things to note from this. The first is that we’re using Code Igniter’s built-in Template Parser class to render our individual posts. The second is the action that is called for each blog entry in the loop:
<?= render_partial("post") ?>This tells Ocular to render a partial. A partial is a small snippet of html/php that is used to keep us from repeating lots of code, and helps keep everything simple and organized. The partial should be located in the same directory as the view that is calling it (blog in this case) and must have a name that starts with an underscore. So our post partial that is called here would be named views/blog/_post.php.
The following commands provide easy ways to insert scripts and stylesheets into your view.
stylesheet_link_tag(“file1”, “file2”) This inserts two external stylesheet links, one for “file1.css” and another for “file2.css”. The ”.css” extension is optional for files passed in. If no arguments are passed with the file, it inserts a link for a stylesheet named “application.css”. This allows for as much separation (and code reuse) in your stylesheets as you want, without slowing down page display time. Since most browsers only allow 2 simultaneous connections to a server, this helps to speed up the display of your page.
javascript_include_tag(“file1”, “file2”) This inserts the external javascript links. The ”.js” extension is optional for filenames. If no arguments are passed in, it inserts a link for a javascript named “application.js”. One of the benefits of this tag is that you can place it toward the bottom of your template page, and then set_view_data (see below) with a variable that holds your javascript files. This will increase page display time, since the browser pauses it’s display while downloading scripts.
Note: Both of the above functions generate code that helps to optimize your page load times. It does this by creating a link to the assets controller which simply combines all of the files into one file. This reduces load on the server by reducing page hits, and speeds up display of your pages by only having to wait for 1 call to the server. This is especially helpful on slow or busy servers.
Passing data into your views is easy. The data is stored in the $this->ocular object and is automatically passed into the views during render.
set_view_data($name, $data) You can pass an array of data, just like you would for any standard Code Igniter Views, into this function. $name is the index in the $vars array. Inside your views, this will be the variable to access to display or work with this data. $data is a string or an array that you want made available within your views.
get_view_data($name) Retrieves the contents of the variable named $name that you set earlier. This won’t be needed very often, but it is here if you need it.
In your controllers, instead of using $this->load->view(‘view_name’) just call $this->ocular->render(); instead. If you want to use a different template for that page, just pass path/to/layout into the function. For example, you might call $this->ocular->render(‘admin’) for your admin pages.
As of version 0.11, creating a number of static pages is a breeze. Let's say you want to create a series of help files for your site. First, build a controller called help.php. It just needs a few lines to automate it all for you:
<?php
class Help extends Controller {
function _remap() {
// Store our page name
if ($this->uri->segment(2)) {
$this->ocular->set_view_data('_viewName', $this->uri->segment(2));
}
$this->index();
}
function index() {
$this->ocular->render();
}
}
?>Now, just put the html partials that you want displayed for your help files in the views/help/ directory, and they'll immediately be accessible by the name of the partial.
So, if you had a views/help/formatting.php file, it could be accessed by going to http://your-site.com/help/formatting.
In the forums, I've often seen people trying to accomplish some magical routing that swaps the order of the id and function in the url. This might be for a users page where you want the url to look like: http://www.your-site.com/user/username/edit. That's fairly easy to fix with the _remap function, but causes a slight hiccup with Ocular. Using the same technique we used for static pages, we can make the magic work like this:
function _remap($method) {
if (method_exists($this, $method) ) {
// No nickname/id/username provided
$this->$method();
} else {
// Reassign our method to the 3rd uri segment
if ($this->uri->segment(3)) {
$method = $this->uri->segment(3);
// Tell Ocular about it
$this->ocular->set_view_data('_viewName', $this->uri->segment(3) );
} else {
// Tell Ocular about it
$this->ocular->set_view_data('_viewName', $this->uri->segment(2) );
}
// Call the method and pass the username as an argument
$this->$method($this->uri->segment(2));
}
}Then, to use your username that you passed into your function, simply use the PHP func_get_args() function.
The following files are included as a part of the library. The paths shown are where the files should be placed within your project.
+ public
+ images - the default image location
+ javascripts - the default javascript location
+ stylesheets - the default stylesheet location
+ system
+ application
+ config
- ocular.php: Stores the library settings.
+ controllers
- assets.php: Handles combining the stylesheets and javascripts into one file.
+ libraries
- MY_URI.php: Extends the URI class to allow Ocular access to the default controller name.
- Ocular.php: The main library. Takes care of rendering the pages in an intelligent way.
+ helpers
- ocular_helper.php: Provides functions that can be used within your views to add stylesheets, images, javascript, render partial views, and more. * Make the render function work with controllers that are in subdirectories.
* Provide the option to remove comments and whitespace from stylesheets and javascripts.
* Add the image_tag() function.