View helpers are used to consolidate code for creating or modifying HTML, simplifying your views and minimizing redundancy. For example, tasks such as escaping HTML, formatting dates, and creating commonly-used interface components are handled by way of view helpers.

For a more complete introduction, read Zend Framework's documentation. This page focuses on using Omeka S's view helpers, listed below. Note that Omeka S also uses many of Zend Framework's native view helpers -- consult their documentation for more information.

Using A View Helper

Helpers are typically called from view scripts. A common example using one of Zend Framework's view helpers is the Url, helper, which generates a URL for a route and action:

$this->url(null, ['action' => 'log'], true);

Note that while view helper names begin with an uppercase letter, the method invoked from $this (the View object) begins with a lowercase letter. Each helper will use its own signature, so consult each helper's documentation for its __invoke method.

Creating A View Helper In A Module

View Helpers should be placed here in the module's directory structure:

MyModule/
  src/
    View/
      Helper/
        MyHelper.php

View Helpers inherit from Zend\View\Helper\AbstractHelper and implement Zend\View\Helper\HelperInterface.

Thus, the basic structure is

namespace MyModule\View\Helper;

use Zend\View\Helper\AbstractHelper;

class MyModuleViewHelper extends AbstractHelper
{
    public function __invoke()
    {
        $view = $this->getView(); // supplied by AbstractHelper
        //return HTML;
}

There are no restrictions on the signature for __invoke, so any necessary data from the view can be added as needed, as in the first example of Url above. Its __invoke method thus looks like:

Config file

For Omeka S to be aware of your View Helper, you must add it to your module's config/module.config.php array. That file will contain a great deal more than this information, but this is what will be relevant to the helper:

return [
    'view_helpers' => [
        'invokables' => [
            'myModule' => 'MyModule\View\Helper\MyModuleViewHelper',
        ],
    ],
]

The invokables key signals that the View Helper class can be directly instantiated (see below on invokables vs factories). Each value in the subsequent array refers to the domain-specific class to refer to.

Invokables vs Factories

Sometimes, a helper will need access to additional services, or data that is accessible only via a service. In this case, the View Helper must be created via a factory, rather than an invokable, as defined in the config.php file. (See also Services and Factories).

To create a factory for your View Helper, put the factory in the following directory:

MyModule/
  src/
    Service/
      ViewHelper/
        MyModuleViewHelperFactory.php

Instead of declaring an invokable in module.config.php's array, declare a factory:

return [
    'view_helpers' => [
        'factories'  => [
            'myModule' => 'MyModule\Service\ViewHelper\MyModuleViewHelperFactory',
        ],
    ],
];

The file structure for the factory will be akin to:

namespace MyModule\Service\ViewHelper;

use MyModule\View\Helper\ViewHelper;
use Zend\ServiceManager\Factory\FactoryInterface;
use Interop\Container\ContainerInterface;

class MyModuleViewHelperFactory implements FactoryInterface
{
    public function __invoke(ContainerInterface $services, $requestedName, array $options = null)
    {
        $config = $services->get('Config');
        $mediaAdapters = $config['my_module_media_adapters'];
        return new MyModuleViewHelper($services->get('Omeka\MediaIngesterManager'), $mediaAdapters);
    }
}

In this example, the View Helper needs information added to the config array, and Omeka\MediaIngesterManager service. Those are not directly available within a ViewHelper, and so the factory is used to inject them into the ViewHelper.

As such, the View Helper's __construct method must deal with the data

namespace MyModule\View\Helper;

use Zend\View\Helper\AbstractHelper;

class ViewHelper extends AbstractHelper
{
    protected $mediaIngester;

    protected $mediaAdapters;

    public function __construct($mediaIngestManager, $mediaAdapters)
    {
        $this->mediaAdapters = $mediaAdapters;
        $this->mediaIngester = $mediaIngestManager;
    }

    public function __invoke()
    {
        $mediaForms = [];
        foreach ($this->mediaIngester->getRegisteredNames() as $ingester) {
            if (array_key_exists($ingester, $this->mediaAdapters)) {
                $mediaForms[$ingester] = [
                    'label' => $this->mediaIngester->get($ingester)->getLabel(),
                ];
            }
        }
}

Using Partials Within View Helpers

A common tactic in Omeka S is to invoke a View Helper to create HTML content, but also for that helper itself to use a view page. That is achieved by using a partial within the helper.

These usualy appear in a common directory within the plugin:

MyModule/
  views/
    common/
      my-module-view-helper-partial.phtml

A shorter, more readable name is in order for the readability of a real module.

A View Helper might then create its HTML like so:

<?php
namespace MyModule\View\Helper;

use Zend\View\Helper\AbstractHelper;

class MyModuleViewHelper extends AbstractHelper
{
    protected $user;

    public function __construct($user)
    {
        $this->user = $user;
    }

    public function __invoke()
    {
        $userRole = $this->user->getRole();
        return $this->getView()->partial(
            'common/my-module-view-helper-partial',
            [
                'userRole' => $userRole,
            ]
        );
    }
}

The __invoke method then depends upon the partial in common to produce the HTML. The second parameter also passes along a $userRole variable to the partial for it to use. Depending on the needs of the module, that might or might not be needed.

Built-in View Helpers

Omeka S comes with quite a few view helpers:

• api: iew helper for direct access to API read and search operations.
• assetUrl: View helper for returning a path to an asset.
• blockAttachmentsForm: View helper for rendering a form for adding/editing block attachments.
• blockLayout: View helper for rendering block layouts.
• blockShowTitleSelect: View helper for rendering an attachment title display select element.
• blockThumbnailTypeSelect: View helper for rendering a thumbnail type select element.
• cancelButton: View helper for rendering a cancel button.
• ckEditor: View helper for loading scripts necessary to use CKEditor on a page.
• dataType: View helper for rendering data types.
• deleteConfirm: View helper for rendering the delete confirm partial.
• filterSelector: View helper for rendering a browse filtering form.
• formAsset: get the asset form element
• formCkeditor: get the Ckeditor form element
• formCkeditorInline: get the Ckeditor inline form element
• formColorPicker: get the color picker form element
• formRecaptcha: get the Recaptcha form elemnt
• formRestoreTextarea: get the restore textarea form element
• htmlElement: View helper for rendering a HTML element.
• hyperlink: View helper for rendering a HTML hyperlink.
• i18n: View helper for rendering localized data.
• itemSetSelect: View helper for rendering a select menu containing all item sets.
• itemSetSelector: View helper for rendering the item set selector form control.
• jsTranslate: View helper for rendering translations for JavaScript strings.
• lang: View helper for getting a BCP 47-compliant value for the lang attribute.
• logger: View helper for getting the Zend logger.
• media: View helper for rendering media.
• messages: View helper for proxing the messenger controller plugin.
• navigationLink: View helper for rendering a navigation links.
• pageTitle: View helper for rendering a title heading for a page.
• pagination: View helper for rendering pagination.
• params: View helper for getting params from the request.
• passwordRequirements: View helper for rendering the password requirements.
• propertySelect: View helper for rendering a select menu containing all properties.
• propertySelector: View helper for rendering the property selector.
• queryToHiddenInputs: View helper for building a hidden form input for every query in the URL query string
• resourceClassSelect: View helper for rendering a select menu containing all resource classes.
• resourceSelect: View helper for rendering a select menu containing all of some resource.
• resourceTemplateSelect: View helper for rendering a select menu containing all resource templates.
• roleSelect: View helper for rendering a select menu containing all roles.
• searchFilters: View helper for rendering search filters.
• searchUserFilters: View helper for rendering search user filters.
• sectionNav: View helper for rendering section navigation.
• setting: View helper for getting settings.
• sitePagePagination: View helper for rendering site page pagination.
• siteSelect: View helper for rendering a select menu containing all sites.
• siteSetting: View helper for getting site settings.
• sortLink: View helper for rendering a sortable link.
• sortSelector: View helper for rendering a sorting form.
• status: View helper for getting MVC status.
• themeSetting: View helper for getting theme settings.
• themeSettingAssetUrl: View helper for getting a path to a theme setting asset.
• thumbnail: View helper for rendering a thumbnail image.
• trigger: View helper for triggering a view event.
• uploadLimit: View helper for rendering the upload size limit.
• userBar: View helper for rendering the user bar.
• userIsAllowed: View helper for authorizing the current user.
• userSelect: View helper for rendering a select menu containing all users.
• userSelector: View helper for rendering the user selector.
• userSetting: View helper for getting user settings.