Horde_View

Documentation on the Horde_View package. This documentation is adopted from the MAD documentation (http://framework.maintainable.com/mvc/5_view.php), as many of the Horde View ideas are also adopted from MAD, and the helpers are directly compatible between the two systems.

The following explanations correspond to Horde 5.


 Example usage

Calling code



<?php

require_once __DIR__ . '/lib/Application.php';
Horde_Registry::appInit('yourapp');

// use a model to get the data for book authors and titles.
$data = array(
    array(
        'author' => 'Hernando de Soto',
        'title' => 'The Mystery of Capitalism'
    ),
    array(
        'author' => 'Henry Hazlitt',
        'title' => 'Economics in One Lesson'
    ),
    array(
        'author' => 'Milton Friedman',
        'title' => 'Free to Choose'
    )
);

$view = new Horde_View (array('templatePath' => 'viewtest'));
$view->addHelper('Horde_View_Helper_Tag'); 
$view->books = $data;

// and render a template called "template.php"
echo $view->render('template.php');

View template

Put the following code into viewtest/template.php (the template path is set above):



<?php if ($this->books): ?>

<!-- A table of some books. -->
<table>
    <tr>
        <th>Author</th>
        <th>Title</th>
    </tr>

<?php foreach ($this->books as $key => $val): ?>
    <tr>
        <td><?php echo $this->escape($val['author']) ?></td>
        <td><?php echo $this->escape($val['title']) ?></td>
    </tr>
<?php endforeach ?>

</table>

<?php else: ?>

    <p>There are no books to display.</p>

<?php endif ?>


 Base functionality


    assign indiv vars
    assign bulk vars
    __isset/__empty/__get
    add template paths (incl. add missing trailing slash)
    render (w/ .html added if no extension)
    render in path order
    render partials
    render w/ local variables
    render partial collections
    add helpers
    helper method overwrite


 Helper functionality


 Benchmark


    logging


 Capture


    capture output (nested output buffers)
    capture to named view variable


 Debug


    pretty variable dump


 Form Tag


    generate form tags
    generate multipart form tags
    checkbox input
    hidden input
    file input
    password input
    radio input
    select input
    textarea input
    text field input
    submit input


 Form


    initialize defaults from objects
    wrapper around FormTag helpers with object awareness
    formFor($object)
    fieldsFor($object)
    default form builder
    custom form builders


 Javascript


    generate <script> tags


 Number


    human-readable file sizes


 Tag


    xhtml tags with programmatic options
    rewrite checked => true to checked="checked"
    contentTag for tags with nested content
    generate CDATA sections
    single-escaping to not re-escape entities


 Text


    h() shorthand escape
    truncate
    truncate middle
    highlight
    cycle
    pluralize


 Url


    linkTo, either from controller-generated links or string URIs
    default to showing URL as link text
    linkToUnless
    linkToIf
    mailTo
    mailTo with javascript email address obfuscation
    mailTo with hex email address obfuscation
    mailTo with "replace this ..." obfuscation


 Helpers


 Overview

Views separate the presentation from the controllers and models. Views are allowed to have logic, provided that the logic is only for presentation purposes. This presentation logic is small bits of PHP code embedded in the HTML.

Bits of presentation logic code can be extracted into helper methods. Once extracted, a helper method can be called in the view in place of the former code block. Extracting presentation logic into helpers is a best practice and helps keep views clean and DRY.

Helpers are simply methods of a class. The framework mixes the helpers into the view behind the scenes, and makes them appear as methods inside the view. An example of a helper class with a single highlight() helper follows. For more detailed information, refer to http://dev.horde.org/api/FRAMEWORK_4/lib/View/package-View.Helper.html


 Example

In the above example template, a function of Horde_View_Helper_Tag is used. Functions can be overloaded and additional helpers can be defined. For instance, you might whish to highlight a certain name in your booklist. You could define a corresponding function and put it into your own helper class in file yourapp/lib/Helper.php:




<?php
class Yourapp_Helper extends Horde_View_Helper_Base
{
    /**
     * Highlights a phrase within the given text.
     *
     * @param string $text
     * @param string $phrase
     *
     * @return string
     */
    public function highlight($text, $phrase)
    {
        if (empty($phrase) || empty($text)) {
            return $text;
        }
        $highlighter = '<strong class="highlight">' . $this->escape($phrase) . '</strong>';
        return preg_replace('/' . preg_quote($phrase) . '/', $highlighter, $text); 
    }
}

To use this helper, it helper must be added to the view you are using (w/ref. to above view.php):


$view->addHelper('Yourapp_Helper'); 

And in template.php:


...
       <td><?php echo $this->highlight($val['author'], 'Soto') ?></td>
...

It is OK to put HTML into helper class methods because they exist to assist with presentation. However, it is NOT OK to put print/echo statements within a helper class. Helper methods always return a value that is displayed in the view like <?= $this->highlight($text) ?>.


 Organization

As shown above, helpers are methods that are organized into classes. The framework will mix helper methods together through overloading. Inside a view, helper methods from all of the sources above can be called by simply using <?= $this->helperMethod() ?>.