davewid/owl

A class based View library for 5.3+

Maintainers

Details

github.com/daveWid/Owl

Homepage

Source

Issues

Installs: 22

Dependents: 0

Suggesters: 0

Security: 0

Stars: 3

Watchers: 2

Forks: 0

Open Issues: 0

1.2.2 2012-08-28 13:31 UTC

Requires

MIT 30ef0253f3691ed02a77b97341c1554ef741a653

viewview class

This package is not auto-updated.

Last update: 2024-10-26 13:44:37 UTC

README

Owl is a view library that can interface with different template rendering engines. Owl uses Mustache as the default rendering engine. Requires PHP 5.3+.

Installing

As of version 1.2.x you can now use Composer to install the Owl library. Owl is hosted on Packagist so all you will need to add to the require section of composer.json file is below.

"require":{
	....
	"davewid/owl": "1.2.*"
	....
}

Alternatively you can visit the downloads page and click on the latest version to grab the files. If you download the files from github you will need to setup autoloading by hand.

PHP-FIG

Owl is in compliance with PSR-0 and PSR-1

Setup

The Owl library strives for flexibility in rendering engines and finding files. Unfortunately this flexibility adds a few more steps in the setup process. Below are the two things you can inject, the rendering engine and the file finder.

Engine

By default, a Mustache rendering engine is setup. If you would like to use a different engine you can set it with setEngine. Your engine will have to implement the \Owl\Engine interface. The rendering engine is shared between any view and layout classes you use in a request, so you only need to set the engine once per request.

<?php

// Please don't do this as the Mustache engine is default, this is just an example
$engine = new \Owl\Engine\Mustache;
\Owl\View::setEngine($engine);

File Finder

We need a way to find the template files to load and then eventually render. You will need to specify a class that implements \Owl\Finder to do that. Provided are a direct file system class and if you are using the Kohana framework, a finder that uses the cascading file system (Badass!).

<?php

$path = __DIR__.DIRECTORY_SEPARATOR."views";
$finder = new \Owl\Finder\FileSystem($path);
\Owl\View::setFinder($finder);

Usage

Now that you are setup, lets start creating your view classes and building your application!

The first thing you will want to do is create a new class that extends \Owl\View.

<?php

class Homepage extends \Owl\View
{
	public $name = "Dave";
	public $title = "Welcome";
}

Along with the view class you will need the mustache template. The template files are loaded automatically from the template directory, based on the class name. All underscores and namespace separators in the class name are converted to directory separators. If you want to specify the full path to your files manually, override the getFile function.

In our example above, we will want to create our template at __DIR__/views/Homepage.mustache.

Hello {{name}}

Then all we will need to do is render our view class (echo works also).

<?php

// Assuming file finder is already set from above.
$content = new Homepage;

echo $content->render(); // Output: Hello Dave
// echo $content; <-- this works too

Layout

The Owl library also comes with a layout class that can help you build reusable layout files. Let's take a quick look at an example.

<?php

class Layout_Browser extends \Owl\Layout
{
	public $title = "My Page";
}

Our template file at __DIR__/views/Layout/Browser.mustache would then hold our html page.

<!doctype html>
<html>
<head>
	<title>{{title}}</title>
</head>
<body>
	Content goes here...
</body>
</html>

This is great, but where it gets really dynamic is being able to add content into the layout.

Adding Content To a Layout

First we will need to modify our layout template file to have a content partial.

<body>
	{{> content}}
</body>

Then we can pass in either an \Owl\View class or raw html into the layout.

<?php

$layout = new Layout_Browser;
$layout->setContent($content);
echo $layout->render();

When the layout is rendered, it will replace the content partial {{> content}} with the content you passed into the layout, which in our example is the Homepage view.

{{> content}} would then be replaced with Hello Dave. This lets you have a reusable layout and change the page content based on the page. Pretty cool huh?

Added To Layout

One last thing you should know about is the addedToLayout function.

When a class that extends \Owl\View is passed into a layout class, the addedToLayout function is called and the current layout is passed in as the only argument.

This is powerful because now you can use this function to add things to the layout.

Say you wanted to add some more js or css files because the specific page is a little more dynamic or styled differently, you would do it in the addedToLayout function.

For a quick example, I will add the title from the view class onto the layout title.

<?php

class Homepage extends \Owl\View
{
	public $name = "Dave";
	public $title = "Welcome";

	public function addedToLayout(\Owl\Layout $layout)
	{
		$layout->title .= "ยป {$this->title}";
	}

Now we the layout is rendered the title tag will render out as so.

<title>My Page &raquo; Welcome</title>

Flash Messages

The Owl library provides a Message class so you can pass messages between requests in your application

Setup

Before you can use the Message class you will need to supply a session driver that implements \Owl\Session. If you are using the Kohana framework, a wrapper class for the internal Session class has been provided at \Owl\Session\Kohana.

Once you have your session driver you will need to inject it into the class.

<?php

// Anything that implements \Owl\Session will work.
$session = new \Owl\Session\Kohana;
\Owl\Message::setSession($session);

Now the library is ready to go!

Getting Messages

To get a message all you need to do is run get:

<?php

\Owl\Message::get();

If no message is found this function will return false.

Setting Messages

To set a flash message all it takes is the following:

<?php

\Owl\Message::set($type, $message);

Properties

Wrapper methods

There are also methods that are wrappers for the different types of messages.

<?php

\Owl\Message::error($message);
\Owl\Message::success($message);
\Owl\Message::notice($message);
\Owl\Message::warn($message);

Exploration

There is more to explore in the Owl library, but I'll leave that to you. If you have any questions/bugs/concerns please use the bug tracker here on github.

Hacking

If you use a different framework than those currently supported fork this repo and add those files. The only thing I ask is to please use and send pull requests on the develop branch.

License

This code is licensed under the MIT license.

Developed by Dave Widmer.