About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:plugins:controllers

This is an old revision of the document!


Building a Controller

Every time you access a VuFind URL, work is being done by a controller class to render a response. You can add new actions to VuFind by building new controllers, and you can modify existing behavior by extending or overriding existing controllers.

Background

A full description of Laminas controllers is beyond the scope of this page, but in a nutshell:

Controller workflow:

  • The framework determines which controller class to load based on routing rules in the application/module configuration.
  • Routing also determines the name of the action to trigger – each action is a method in a controller class.
  • When generating a link to an action in a template, the name of the route from the application/module configuration can be sent to the url view helper to create an automatic link.

What controllers do:

  • Each action method in a controller needs to return either data to pass to a view or a response object if a non-standard action (like a redirect) is necessary.

Some of the resources on the Laminas page provide more detailed documentation.

VuFind-Specific Controller Conventions

Some VuFind-specific tips for building controllers:

  • All VuFind controllers should extend \VuFind\Controller\AbstractBase in order to get access to useful convenience methods.
  • VuFind controller actions designed to render a template should usually return a view model object generated with \VuFind\Controller\AbstractBase::createViewModel(). This ensures that the view is automatically pre-populated with certain values (like the flash messenger object) that are expected by a wide variety of templates.

Overriding an Existing Controller

To override an existing controller, follow these steps:

  • Create a custom module if you do not already have one.
  • Create a new class in your module's namespace which extends the core VuFind controller you wish to override. Change methods as desired.
  • In your module's config/module.config.php, add a new invokable controller setting pointing to your new controller:
$config = [
    'controllers' => [
        'factories' => [
            'YourNamespace\Controller\ControllerNameController' => 'Laminas\ServiceManager\Factory\InvokableFactory',
        ],
    ],
];

Creating a New Controller

Creating a new controller is much like overriding an existing one.

  • As described above, create a custom module, build a new controller, and set up an invokables entry for it.
  • Now you need to add routing rules so the framework knows how to find your controller and so you can conveniently link to it within templates. VuFind's main configuration (module/VuFind/config/module.config.php) contains some variables and loops which automatically generate most of its routes. You may wish to copy some of this logic into your own module's configuration file so you can set up routes in a similar fashion.

Example - How to add a new page to your theme

Note: this example shows how to modify the VuFind core; localizing changes to a separate module requires some additional work.

  • Create a new controller in /vufindroot/module/VuFind/src/VuFind/Controller and name it as you want (e.g. TestController.php).

It extends AbstractBase and contains just a function that returns an array:

class TestController extends AbstractBase
{
	/**
	 *
	 * @return \Laminas\View\Model\ViewModel
	 */
	public function homeAction()
	{
		return $this->createViewModel();
	}
}
  • In /vufind2root/module/VuFind/config/module.config.php

below the 'controllers' ⇒ array( add a new

    'invokables' => array(
      'test'  => 'VuFind\Controller\TestController',

and below $staticRoutes = array( add your template filename and path

'Test/Home',
  • Then create in your theme a directory and a file (lowercase) named as in the configuration (e.g. /vufindroot/themes/demovufind/templates/test/home.phtml)
  • Put your contents in that file. For test you can try with

<?=$this->render('search/home.phtml');?>

development/plugins/controllers.1583266803.txt.gz · Last modified: 2020/03/03 20:20 by demiankatz