Posts Tagged ‘view’

Layouts

Posted in Solar on June 16th, 2009 by Jon – 1 Comment

A layout is basically a view (or collection of views) that wrap around controller specific content. They typically include the repeating parts of a website, such as the header, footer and navigation elements. I’ve written about them briefly in a previous post, but in this post, I will elaborate slightly.

This is the general approach I take when using views and layouts in Solar. This isn’t a CSS framework. This is just an approach to laying out files in such a way that they can be easily shared between various Solar applications.

Let’s start with a basic 2 colum site design where I have my site-wide navigation on the left, a header up on top, and the footer below. In the main column is the controller-specific content. Based on that information, I am going to create 6 individual layout files. That seems like a lot, but it will make more sense shortly.

The Files

The layout files are as follows:

  • 2col-navleft.php
    • _head.php
    • _body.php
      • _header.php
      • _footer.php
      • _nav.php

The main layout file is called 2col-navleft.php. It’s good to choose a descriptive name like this so you know what to expect from the layout. It has 2 columns and the navigation is on the left. This is also the name of the layout you specify in your Solar controllers. For example, your controller would have the following property:

protected $_layout_default = '2col-navleft';

Better yet, you might be using a “Base” controller that all your other controllers extend. In this way, all your child controllers will use the same layout by default. And, of course, you could change this at anytime. More about that later. For now, here is the contents of the main layout.

/**
 * File: 2col-navleft.php
 */
<!DOCTYPE html PUBLIC "-W3CDTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 
<?php
    // generate the <head>
    include $this->template('_head.php');
 
    // generate the <body>
    include $this->template('_body.php')
?>
 
</html>

Nice and simple. You’ve got the doctype and the html block. Within the html block, you can see how to include other layout pieces, such as _head.php and _body.php.

Here is what _head.php looks like. As you can see, its purpose is to create the <head> tags and all the stuff in between.

/**
 * File: _head.php
 */
<head>
<?php
// add meta tags
foreach ((array) $this->layout_head['meta'] as $val) {
    $this->head()->addMeta($val);
}
 
// set the title
$this->head()->setTitle($this->layout_head['title']);
 
// set the uri base
$this->head()->setBase($this->layout_head['base']);
 
// add links
foreach ((array) $this->layout_head['link'] as $val) {
    $this->head()->addLink($val);
}
 
// add baseline styles
$this->head()->addStyleBase("Vendor/styles/2col-navleft.css");
 
// additional baseline styles
foreach ((array) $this->layout_head['style'] as $val) {
    $this->head()->addStyleBase($val);
}
 
// additional baseline scripts
foreach ((array) $this->layout_head['script'] as $val) {
    $this->head()->addScriptBase($val);
}
// done!
echo $this->head()->fetch();
?>
</head>

This layout uses a nice view helper called Solar_View_Helper_Head ($this->head()…). This helper sets all the head elements and displays them in the correct order. A public property (layout_head) need to be set in order for this to work properly. The layout_head public property is an array.

The next file is _body.php. This file, as you can imagine, sets the content between the <body> tags. Here is what _body.php looks like:

/**
  * File:_body.php
  */
<body>
<div id="wrap">
    <div id="header">
	<?php include $this->template('_header.php'); ?>
    </div>
    <div id="nav">
	<?php include $this->template('_nav.php'); ?>
    </div>
    <div id="content">
	<div id="main">
	    <?php echo $this->layout_content; ?>
	</div>
    </div>
    <div id="footer">
	<?php include $this->template('_footer.php'); ?>
    </div>
</div>
</body>

Here, you can see several other includes that point to more “sub layouts”.

  • The _header.php file simply displays the header piece of the page.
  • The _nav.php displays the site-wide navigation.
  • At the bottom is the _footer.php file which displays the footer.
  • Finally, is the php statement which echos $this->layout_content. This is where the controller-specific content is displayed.

Of course, these are just the basic layouts you can use. You could add more layouts as you see fit. Things like an _auth.php layout, a _topnav.php layout, etc.

Vendor- and Application-specific Layouts

So, why break them into such small pieces? Well, for one, you could easily alter the overall structure of your site by using a different main layout (2col-navright.php or 2col-navtop.php). Or, you could implement a CSS framework such as the Stenhouse CSS Framework. Also, Solar enables a nice heirachy of includes that you can easily have a different _header.php and _nav.php layout for each vendor or even each application. Have a look at the following directory structure to help understand how that works. Let’s start the “include” folder.

include/
    Vendor/
        App/
            Base/
                Helper/
                Layout/
                    2col-navleft.php
                    _body.php
                    _footer.php
                    _head.php
                    _header.php
                    _nav.php
                Locale/
                View/
            Index/
                Helper/
                Layout/
                    _nav.php
                Locale/
                View/
    Solar/

In this example, let’s assume that our Vendor_App_Base class extends Solar_Controller_Page. That class specifies the default layout as 2col-navleft.

<?php
class Vendo_App_Base extends Solar_Controller_Page {
 
    protected $_layout_default = 'main';
 
    // The array needed in the _head.php layout
    public $layout_head = array(
        'title'  => null,
        'base'   => null,
        'meta'   => array(),
        'link'   => array(),
        'style'  => array(),
        'script' => array(),
        'object' => array(),
    );
.
.
.
}
?>

Vendor_App_Index extends Vendor_App_Base.

<?php
class Vendor_App_Index extends Vendor_App_Base {
     protected $_action_default = 'browse';
    public function actionBrowse()
    {
	// layout_head defined in parent class
	$this->layout_head['title'] = "Here is my happy site";
    }
.
.
.
}
?>

By default, any class that extends Vendor_App_Base will use the specified default layout (2col-navleft.php) and all sub layouts. However, In Vendor_App_Index_Helper, we have another _nav.php layout. Whenever you request the index application, this application-specific navigation layout will be used instead of that in the base application. Solar doesn’t need any explicit instructions to do this. It just knows.

Interacting with the Layouts (and Views)

As I have mentioned before, both Solar views and layouts have access to public properties in your controller (and those it extends). In the above example, $this->layout_head is a public property, therefore, the layouts and views have access to it via $this->layout_head. Knowing this should help the _head.php layout make even more sense.

Wrapping Up

Views and layouts aren’t too complex. The best way to learn them is to try it all out. The other really important thing you would be wise to learn about are view helpers.

View Helpers

Posted in Solar on June 6th, 2009 by Jon – Be the first to comment

View helpers are very useful for performing repetitive tasks and, more importantly, an essential way to keep domain logic out of your views. View helpers can be very simple, such as displaying a date in a particular format, or they can be quite complex, such as displaying a complete html form. Solar is packed with many very useful view helpers. Additionally, the way Solar applications are organized makes it easy to create your own view helpers and have them available to several applications.

To use a view helper, simply call it in your view. Take, for example, the title view helper bundled with Solar. This helper simply puts the <title> tags around whatever text you pass to it.

<html>
<head>
	<?php 
          // assume $pagetitle was set in the controller and is public 
        ?>
	<?php echo $this->title($this->pagetitle); ?>
</head>

Ok, so that is a very simple example that you might never use, but you never know. What is important in a helper like this is the automatic escaping of text.

One view helper that I use all the time is the action view helper (Solar_View_Helper_Action). This helper displays an escaped link with the properly formed <a> tags. It takes 3 parameters, the second and third are optional.
It works something like this:

<?php echo $this->action($spec, $text = null, $attribs = null); ?>

$spec is the link,
$text is the text (or a locale key for automatic translation),
$attribs is an array of option attributes to use in the link, such as class, style, or even onclick.

For example:

<?php // assume TEXT_BROWSE is a locale key and translates to 'Browse' ?>
<?php echo $this->action('index/browse', 'TEXT_BROWSE'); ?>

This will output:

<a href="/docroot/index/browse">Browse</a>

The docroot part comes from the uri action path in your config file: $config['Solar_Uri_Action']['path'] = ‘/docroot’;

What’s interesting here is that, if you dive into the code, the action helper actually refers to other helpers, actionHref and escape via the $this->_view property. Now you can see how powerful view helpers can be! In fact, many of Solar’s view helpers utilize other Solar view helpers. It just makes sense.

Writing your own view helpers is a snap. You can make them as simple or as complex as you like. Each time you create an application using Solar’s Command Line Interface (CLI), a Helper sub folder is creating in your application’s namespace. For example, if your vendor is named Vendor and your application is named Example, then the Helper folder will exist in a folder structure similar to this.

Vendor/
    App/
	Example/
	    Helper/
	    Layout/
	    Locale/
	    View/
	    Example.php

So, here is an example of a very simple view helper that will take a Canadian postal code in this format A1B2C3 and convert it to the proper A1B 2C3 format.
The helper file is named PostalCode.php and is located in the Helper sub folder of your application.

Here is what it might look like:

<?php
 
/**
 * View Helper to format a postal code from 6 alpha numeric 
 * characters without a space
 * to 6 with a space. T9E5W7->T9E 5W7
 */
class Vendor_App_Example_Helper_PostalCode extends Solar_View_Helper {
 
    public function postalCode($code)
    {
	// Get the first 3 chars (note the use of another 
        // view helper called escape)
	$first_three = $this->_view->escape(strtoupper(substr($code, 0, 3)));
 
	// Get the last 3 chars
	$last_three = $this->_view->escape(strtoupper(substr($code, 3, 3)));
 
	// Return the newly formated code with a space
	return $first_three."&nbsp;".$last_three;
    }
}
?>

To use this view helper in your view it’s as simple as:

<?php echo $this->postalCode($code); ?>

Another nice feature of view helpers is that they ultimately extend Solar_Base. This means they handle the config files just like all the other Solar classes. If you don’t know about Solar’s config file, then you should definitely read about it.

If you want to create a view helper that has a property that can be customized, then just follow Solar’s standards for classes and objects. Here is an example taken from Solar’s date view helper. I have simplified this from the real file.

<?php
class Solar_View_Helper_Date extends Solar_View_Helper
{
    /**
     * 
     * User-defined configuration values.
     * 
     */
    protected $_Solar_View_Helper_Date = array(
        'format' => 'Y-m-d',
    );
 
    public function __construct($config = null)
    {
        parent::__construct($config);
    }
 
    /**
     * 
     * Outputs a formatted date.
     * 
     */
    public function date($spec, $format = null)
    {
	if (! $format) {
		$format = $this->_config['format'];
         }
	return date($format, strtotime($spec));
    }
}
?>

As you can see, the default format is ‘Y-m-d’. But, that can be changed in 2 ways.
First, you can pass whatever format you want to the helper, and second, you can set a $config value in your config file to override the default.

In a view it would look like this:

<?php echo $this->date('Yesterday', 'm jS, Y'); ?>

If you changed the default in your config file, the file would have an entry like this:

<?php
$config['Solar_View_Helper_Date']['format'] = 'm jS, Y';
?>

That is the basic idea behind view helpers. Remember, if you need to access the current view object from within the view helper, you do so using $this->_view.
What’s really important is that these keep unnecessary logic out of the view!

Views, Layouts, and Locales

Posted in Solar on April 8th, 2009 by Jon – 1 Comment

Views and layouts are responsible for displaying content in the browser. Views are generally specific to a controller action. For example, an action method such as actionIndex() would display its output in a view called index.php. Layouts, on the other hand, are typically shared by the entire application and wrap around the view. A layout usually contains the header, footer, navigation, and the content area where the view’s output is displayed.
read more »