Download the PHP package mxc-commons/mxc-layoutscheme without Composer

MxcLayoutScheme

Version 0.5.0 created by Frank Hein and the mxc-commons team.

MxcLayoutScheme is part of the maxence Open Source Initiative by maxence business consulting gmbh, Germany.

Introduction

Did you ever want to apply a different layout phtml based on the route matched or for a particular module, controller or action? This is what MxcLayoutScheme can do for you.

MxcLayoutScheme allows to dynamically exchange the layout template used by the renderer. You define layout schemes which are a collection of rules to select layouts. Within each scheme you can assign a distinct layout to a particular route matched. Further you can define a distinct layout for each module, controller and action.

MxcLayoutScheme supports the configuration child ViewModels together with associated view templates to get rendered to captures you define.

Further, MxcLayoutScheme intercepts dispatch errors. You can apply layouts for particular error codes and http status codes the same way you do for routes and controllers.

MxcLayoutScheme provides an event interface to allow you to select the layout scheme applied at bootstrap time.

Requirements

• Zend Framework 2 (latest master)

Features / Goals

Main design goal of MxcLayoutScheme is to encapsulate the layout specific settings within the applied layout view template as far as possible. We want to achieve that within the controller action as less as possible remains to be done regarding the layout. So controller programmers can focus on the page 'content' part of the page regardless of the target layout (which can be very different for different target platforms (JQuery, JQuery Mobile, Dojo, ... whatever).

1. Provide the capability to assign the layout dynamically

• based on the current route matched
• for each module
• for each controller
• for each action implemented by a controller

2. Provide hierarchical matching of modules, controllers, actions and routes

• route match supersedes action match
• action match supersedes controller match
• controller match supersedes module match
• module match supersedes global settings

3. Encapsulate layout selection rules into layout schemes

4. Support to add child ViewModels to the layout by configuration

5. Allow selection of active layout scheme based on custom criteria

• You may select the layout scheme selection in response to an event provided.

6. Allow configuration of a global default layout for each layout scheme

7. Provide hooks for pre- and postprocessing

8. Provide a controller plugin to control scheme selection and setup of layout variables

9. Provide support for dispatch errors

10. Provide support for content view template

In the current version you can either assign the layout variables within the controller action via layoutScheme controller plugin. Alternatively you may supply an event handler for pre- and postprocessing. We provide an example here.

Installation

Main Setup

By cloning project

1. Clone this project into your ./vendor/ directory.

With composer

1. Add this project in your composer.json:

   json
   
       "require": {
           "mxc-commons/mxc-generics": "dev-master,
           "mxc-commons/mxc-layoutscheme": "dev-master"
       }

2. Now tell composer to download MxcLayoutScheme by running the command:

   bash
   
   $ php composer.phar update

Post installation

1. Enabling it in your application.config.phpfile.

   php
   
       ` in the layout template)

Example 2:

May the module be Reporting, the controller class WbsController, the action be prjListAction. May the the child ViewModel definition be 'panelLeft' => '<default>'.

The templateName computes to 'reporting\wbs\prj-list-panel-left'.

templateName '<none>' :

If you specify '<none>' as the templateName the computation of the particular capture gets omitted. There is no need to specify a '<none>' rule within the 'defaults' section. That would be the same as not specifying that particular capture at all.

'<none>' rules are used to override 'defaults' for a particular route rule or mca rule.

Example:

Given a layout template named 'layout\master' which renders to captures panelLeft and content. panelLeft provides a standard left navigation. Could look like this:

master.phtml:

    <html>
        <header>
            ...
        </header>
        <body>

                <div data-role="panel-left">

                </div>

            <div data-role="content">

            </div>
        </body>
</html>

In some cases you may not want to render a left navigation. The login page is a good example if anonymous users are not allowed to navigate through the application at all.

If we define have a layout scheme 'master' defined like this a default child ViewModel gets applied to capture 'panelLeft' and template 'layout\leftNavigation'. This child ViewModel gets applied by default every time MxcLayoutScheme assigns the layout 'layout\master'. The mca rule 'ZfcUser\User\login' overrides the default 'panelLeft' setting by defining 'panelLeft' => '<none>'. The resulting markup does not contain not contain the <div data-role="panel-left"> ... </div> section at all.

mxclayout_scheme.global.php:

    return array(
        'options' => array(
            'master' => array(
                'mca_layouts' => array(
                    'options' => array(
                        'ZfcUser\zfcuser\login' => array(
                            'layout' => 'layout\master',
                            'panelLeft' => '<none>',
                        ),
                    ),
                    'defaults' => array(
                        'panelLeft' => 'layout\leftNavigation',
                    ),
                ),
            ),
        ),
        'defaults': 
            'active_scheme' => 'master',
            'enable_mca_layouts => true,
            'enable_route_layouts => true,
            'enable_error_layouts => true,
            'enable_status_layouts => true,
    );

The Controller Plugin

MxcLayoutScheme registers a controller plugin to allow access to the child view models of the layout applied. From within a controller action you can access the controller plugin with $this->layoutScheme.

layoutScheme provides the following interfaces:

getActiveScheme(): get the currently active layout scheme.

getChildViewModel($capture): returns the child view model registered for the $capture capture. Null if capture is not registered.

getChildViewModels(): returns the array of child view models like array ( 'capture' => ViewModel )

setVariables($variables, $override = false): see ViewModels setVariables for parameter specification. The layoutScheme setVariables function applies the same variables provided through $variables to the controller's layout and to all registered child ViewModels.

useControllerContentTemplate($flag = true): MxcLayoutScheme supports the provision of content templates via it's configuration (capture = 'content'). If you want to override the MxcLayoutScheme configuration with your own template set in the controller's action, you should inform MxcLayoutScheme not to override your setting by calling useControllerContentTemplate().

Note

If you want or need to assign different sets of variables to the main layout and the child layouts you can do this by explicit access and assignment.

Example:

$this->layout()->setVariables($varMain); // assign variables to the layout's ViewModel
$this->layoutScheme()->getChildViewModel('panelLeft')->setVariables($varPanelLeft); // assign variables to leftPanel child

Notes

If you do not define a scheme or if the active scheme does not register a master layout the ViewManager configuration gets applied. If you define a master layout (capture layout) within your schemes it overrides the ViewManager configuration.

Common use cases for MxcLayoutScheme are

1. Apply different layouts for mobile devices based on mobile detection and distinct mobile route definitions
2. Apply different layouts for authenticated and anonymous users or based on user roles
3. Apply different layouts for functional modules (themes)

Credits

MxcLayoutScheme was inspired by EdpModuleLayouts by Evan Coury. EdpModuleLayouts is a lean and mean module which allows to set module specific layouts.

License

MxcLayoutScheme is released under the New BSD License. See license.txt.