Umleiten

Umleiten is a Router for Grav CMS. It allows you to create custom routes with controllers and middlewares.

Table of Contents

Installation

Umleiten is not part of the official Grav repository.

Check our guide for manually installing Open-Source plugins.

Configuration

Setting Description Type
Enabled Enables / disables plugin functionality Boolean (default: true)

The default configuration can be found at user/plugins/gravy/gravy.yaml:

enabled: true

Usage

Create routes listening for the onRegisterRoutes event.

We create routes similarly to many MVC Frameworks. But this particular way is based on Laravel.

We declare routes using Grav\Plugin\Umleiten\Route and passing a controller. The controller can be a function array, a Closure or an invokable class.

We can also declare Middlewares to modify the request or intercept it.

At the end of onRegisterRoutes, the Router will try to find a match for the current $request.

If a Route is matched by the $request, it will be booted and will execute its Middlewares in order, passing the $request for possible mutations.

If the $request is still a ServerRequest at the end of the Middlewares execution, it will be passed in to the Controller. Otherwise, it will return a $response.

At the end of the Router process, the $response will try to be solved depending on its type:

  • Grav\Common\Page\Page: Will force Grav to process the page on that route.
  • Psr\Http\Message\ServerRequestInterface: Will set $this->grav['request'] as it.
  • Anything else will tried to be output directly as string.

If the $response was null or gave an error on output, the Route will be ignored, and the Grav process will continue.

As you could see, the plugin comes with a static class View with a bunch of helpers to make the code more abstract.

We can create a View by passing a twig template and data directly to it.

View implements Stringable, so if we return a View directly through a Route, it will be processed and output as an HTML string.

However, we may want to still take advantage of Frontmatter and the Grav Page Processor.

For this, we want to return a Page using one of the following methods:

  • withPage($pagePath): Processes the template with the path of a file given (Normally an .md)
  • asPage(): Processes the template with the file corresponding to the same path as the template
  • asJson(): Processes the template and then the output is passed to an empty JSON page.
  • withJsonPage($pagePath): Same as withPage but tries to force the template and language to JSON.
  • asJsonPage(): Same as asPage but tries to force the template and language to JSON.

Example:

theme/pages/signin.md:

theme/templates/signin.html.twig:

Then inside onRegisterRoutes:

Route::get('/app/signin', function () {
    return View::make('signin')->asPage();
});

Support