Merge branch 'hotfix/26'

Close #26

Author: weierophinney

doc/book/zend.view.helpers.advanced-usage.md

@@ -0,0 +1,194 @@
+# Advanced usage of helpers
+
+## Registering Helpers
+
+`Zend\View\Renderer\PhpRenderer` composes a *plugin manager* for managing helpers, specifically an
+instance of `Zend\View\HelperPluginManager`, which extends
+`Zend\ServiceManager\AbstractPluginManager`, and this extends `Zend\ServiceManager\ServiceManager`.
+As you can see, the *HelperPluginManager* is a specialized service manager, so you can register a
+helper/plugin like any other service (see the Service Manager documentation
+<zend.service-manager.intro> for more information).
+
+Programmatically, this is done as follows:
+
+```php
+// $view is an instance of PhpRenderer
+$pluginManager = $view->getHelperPluginManager();
+
+// Register as a invokable class:
+$pluginManager->setInvokableClass('lowercase', 'MyModule\View\Helper\LowerCase');
+
+// Register as a factory:
+$pluginManager->setFactory('lowercase', function ($pluginManager) {
+   $lowercaseHelper = new MyModule\View\Helper\LowerCase;
+
+   // ...do some configuration or dependency injection...
+
+   return $lowercaseHelper;
+});
+```
+
+Within an MVC application, you will typically simply pass a map of plugins to the class via your
+configuration.
+
+```php
+// From within a configuration file
+return array(
+   'view_helpers' => array(
+      'invokables' => array(
+         'lowercase' => 'MyModule\View\Helper\LowerCase',
+         'uppercase' => 'MyModule\View\Helper\UpperCase',
+      ),
+   ),
+);
+```
+
+If your module class implements `Zend\ModuleManager\Feature\ViewHelperProviderInterface`, or just
+the method `getViewHelperConfig()`, you could do the following (it's the same as the previous
+example).
+
+```php
+namespace MyModule;
+
+class Module
+{
+    public function getAutoloaderConfig(){ /*common code*/ }
+    public function getConfig(){ /*common code*/ }
+
+    public function getViewHelperConfig()
+    {
+        return array(
+           'invokables' => array(
+              'lowercase' => 'MyModule\View\Helper\LowerCase',
+              'uppercase' => 'MyModule\View\Helper\UpperCase',
+           ),
+        );
+   }
+}
+```
+
+The two latter examples can be done in each module that needs to register helpers with the
+`PhpRenderer`; however, be aware that another module can register helpers with the same name, so
+order of modules can impact which helper class will actually be registered!
+
+## Writing Custom Helpers
+
+Writing custom helpers is easy. We recommend extending `Zend\View\Helper\AbstractHelper`, but at the
+minimum, you need only implement the `Zend\View\Helper\HelperInterface` interface:
+
+```php
+namespace Zend\View\Helper;
+
+use Zend\View\Renderer\RendererInterface as Renderer;
+
+interface HelperInterface
+{
+    /**
+     * Set the View object
+     *
+     * @param  Renderer $view
+     * @return HelperInterface
+     */
+    public function setView(Renderer $view);
+
+    /**
+     * Get the View object
+     *
+     * @return Renderer
+     */
+    public function getView();
+}
+```
+
+If you want your helper to be capable of being invoked as if it were a method call of the
+`PhpRenderer`, you should also implement an `__invoke()` method within your helper.
+
+As previously noted, we recommend extending `Zend\View\Helper\AbstractHelper`, as it implements the
+methods defined in `HelperInterface`, giving you a headstart in your development.
+
+Once you have defined your helper class, make sure you can autoload it, and then register it with
+the plugin
+manager <zend.view.helpers.register>.
+
+Here is an example helper, which we're titling "SpecialPurpose"
+
+```php
+// /module/src/MyModule/View/Helper/SpecialPurpose.php
+namespace MyModule\View\Helper;
+
+use Zend\View\Helper\AbstractHelper;
+
+class SpecialPurpose extends AbstractHelper
+{
+    protected $count = 0;
+
+    public function __invoke()
+    {
+        $this->count++;
+        $output = sprintf("I have seen 'The Jerk' %d time(s).", $this->count);
+        return htmlspecialchars($output, ENT_QUOTES, 'UTF-8');
+    }
+}
+```
+
+Then assume that we \[register it with the plugin manager\](zend.view.helpers.register), by the name
+"specialpurpose".
+
+Within a view script, you can call the `SpecialPurpose` helper as many times as you like; it will be
+instantiated once, and then it persists for the life of that `PhpRenderer` instance.
+
+```php
+// remember, in a view script, $this refers to the Zend\View\Renderer\PhpRenderer instance.
+echo $this->specialPurpose();
+echo $this->specialPurpose();
+echo $this->specialPurpose();
+```
+
+The output would look something like this:
+
+```php
+I have seen 'The Jerk' 1 time(s).
+I have seen 'The Jerk' 2 time(s).
+I have seen 'The Jerk' 3 time(s).
+```
+
+Sometimes you will need access to the calling `PhpRenderer` object -- for instance, if you need to
+use the registered encoding, or want to render another view script as part of your helper. This is
+why we define the `setView()` and `getView()` methods. As an example, we could rewrite the
+`SpecialPurpose` helper as follows to take advantage of the `EscapeHtml` helper:
+
+```php
+namespace MyModule\View\Helper;
+
+use Zend\View\Helper\AbstractHelper;
+
+class SpecialPurpose extends AbstractHelper
+{
+    protected $count = 0;
+
+    public function __invoke()
+    {
+        $this->count++;
+        $output  = sprintf("I have seen 'The Jerk' %d time(s).", $this->count);
+        $escaper = $this->getView()->plugin('escapehtml');
+        return $escaper($output);
+    }
+}
+```
+
+## Registering Concrete Helpers
+
+Sometimes it is convenient to instantiate a view helper, and then register it with the renderer.
+This can be done by injecting it directly into the plugin manager.
+
+```php
+// $view is a PhpRenderer instance
+
+$helper = new MyModule\View\Helper\LowerCase;
+// ...do some configuration or dependency injection...
+
+$view->getHelperPluginManager()->setService('lowercase', $helper);
+```
+
+The plugin manager will validate the helper/plugin, and if the validation passes, the helper/plugin
+will be registered.

doc/book/zend.view.helpers.base-path.md

@@ -0,0 +1,38 @@
+# View Helper - BasePath
+
+## Introduction
+
+While most *URL*s generated by the framework have the base *URL* prepended automatically, developers
+will need to prepend the base *URL* to their own *URL*s (usually inside an href attribute) in order
+for paths to resources to be correct.
+
+If you're running on ZF2's MVC base, `basePath()` will point to the `public` folder of the
+application's root.
+
+## Basic Usage
+
+Usage of the `basePath()` helper is straightforward:
+
+```php
+/*
+ * The following assume that the base URL of the page/application is "/mypage".
+ */
+
+/*
+ * Prints:
+ * <base href="/mypage/" />
+ */
+<base href="<?php echo $this->basePath(); ?>" />
+
+/*
+ * Prints:
+ * <link rel="stylesheet" type="text/css" href="/mypage/css/base.css" />
+ */
+<link rel="stylesheet" type="text/css"
+     href="<?php echo $this->basePath('css/base.css'); ?>" />
+```
+
+> ## Note
+For simplicity's sake, we strip out the entry *PHP* file (e.g., "`index.php`") from the base *URL* .
+However, in some situations this may cause a problem. If one occurs, use
+`$this-plugin('basePath')-setBasePath()` to manually set the base path.

doc/book/zend.view.helpers.cycle.md

@@ -0,0 +1,94 @@
+# View Helper - Cycle
+
+## Introduction
+
+The `Cycle` helper is used to alternate a set of values.
+
+## Basic Usage
+
+To add elements to cycle just specify them in constructor:
+
+```php
+<table>
+    <?php foreach ($this->books as $book): ?>
+        <tr style="background-color: <?php echo $this->cycle(array('#F0F0F0', '#FFF'))
+                                                     ->next() ?>">
+            <td><?php echo $this->escapeHtml($book['author']) ?></td>
+        </tr>
+    <?php endforeach ?>
+</table>
+```
+
+The output:
+
+```php
+<table>
+    <tr style="background-color: #F0F0F0">
+       <td>First</td>
+    </tr>
+    <tr style="background-color: #FFF">
+       <td>Second</td>
+    </tr>
+</table>
+```
+
+Or use `assign(array $data)` method and moving in backwards order:
+
+```php
+<?php $this->cycle()->assign(array('#F0F0F0', '#FFF')) ?>
+
+<table>
+    <?php foreach ($this->books as $book): ?>
+    <tr style="background-color: <?php echo $this->cycle()->prev() ?>">
+       <td><?php echo $this->escapeHtml($book['author']) ?></td>
+    </tr>
+    <?php endforeach ?>
+</table>
+```
+
+The output:
+
+```php
+<table>
+    <tr style="background-color: #FFF">
+        <td>First</td>
+    </tr>
+    <tr style="background-color: #F0F0F0">
+        <td>Second</td>
+    </tr>
+</table>
+```
+
+## Working with two or more cycles
+
+To use two cycles you have to specify the names of cycles. Just set second parameter in cycle
+method: `$this->cycle(array('#F0F0F0', '#FFF'), 'cycle2')`
+
+```php
+<table>
+    <?php foreach ($this->books as $book): ?>
+        <tr style="background-color: <?php echo $this->cycle(array('#F0F0F0', '#FFF'))
+                                                     ->next() ?>">
+            <td><?php echo $this->cycle(array(1, 2, 3), 'number')->next() ?></td>
+            <td><?php echo $this->escapeHtml($book['author']) ?></td>
+        </tr>
+    <?php endforeach ?>
+</table>
+```
+
+You can also use `assign($data, $name)` and `setName($name)` methods:
+
+```php
+<?php
+$this->cycle()->assign(array('#F0F0F0', '#FFF'), 'colors');
+$this->cycle()->assign(array(1, 2, 3), 'numbers');
+?>
+<table>
+    <?php foreach ($this->books as $book): ?>
+        <tr style="background-color: <?php echo $this->cycle()->setName('colors')->next() ?>">
+            <td><?php echo $this->cycle()->setName('numbers')->next() ?></td>
+            <td><?php echo $this->escapeHtml($book['author']) ?></td>
+        </tr>
+    <?php endforeach ?>
+</table>
+```