PHP code example of mxc-commons / mxc-layoutscheme

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

mxc-commons / mxc-layoutscheme example snippets

		    return array(
		        'modules' => array(
		            // ...
					'MxcGenerics',
		            'MxcLayoutScheme',
		        ),
		        // ...
		    );

2. Copy options file 'mxclayoutscheme.global.php.dist' to your configuration\autoload directory. Rename it to 'mxclayoutscheme.global.php'.


Options
-------

The MxcLayoutScheme module has options to setup and select layout schemes. After installing MxcLayoutScheme, copy
`./vendor/maxence/MxcLayoutScheme/config/mxclayoutscheme.global.php.dist` to
`./config/autoload/mxclayoutscheme.global.php` and change the values as desired.

`Options are structured in two sections:

- **defaults** - Settings to control service operation
- **options** -  Settings for different layout schemes

		'mxclayoutscheme' => array(
			'defaults' => array(
				'active_scheme' => 'myScheme',   //-- name of your layout scheme definition 
				'enable_mca_layouts' => true,    //-- apply layouts based on
										    	 //-- module, controller, action 
				'enable_route_layouts' => true   //-- apply layouts based on routes`
				'enable_error_layouts' => true;  //-- apply layouts for dispatch errors
				'enable_status_layouts' => true; //-- apply layouts based on response status codes
			),
			'options' => array(
				<scheme-definition>,
				...
			),
		);


- **active_scheme** - Name of the scheme which is active by default. Default is `zf2-standard`. 
- **enable_mca_layouts** - Rules for module, controller, action get applied for layout selection. Default: `true`
- **enable_route_layouts** - Rules for module, controller, action get applied for layout selection. Default: `true`
- **enable_status_layouts** - Rules based on status code get applied for layout selection on dispatch errors. Default: `true`
- **enable_error_layouts** - Rules based on event error code get applied for layout selection on dispatch errors. Default: `true`


Each `<scheme-definition>` is structured into four sections:

		'myScheme' => array(
			'mca_layouts' => array(
				'options' => array(
					<mca-rule-definition>,
					...
				),
				'defaults => array(
					<default-settings>
				),
			),
			'route_layouts' => array(
				'options' => array(
					<route-rule-definition>,
					...
				),
				'defaults => array(
					<default-settings>
				),
			),
			'error_layouts' => array(
				'options' => array(
					<error-rule-definition>,
					...
				),
				'defaults => array(
					<default-settings>
				),
			),
			'status_layouts' => array(
				'options' => array(
					<status-rule-definition>,
					...
				),
				'defaults => array(
					<default-settings>
				),
			),
		);
				
Each of these sections is optional (regardless of the `enable_xxxLayouts` settings).

Rule Definition Keys
--

All `<xxx-rule-definition>` have identical structure. The array key specifies the rule,
the values specify the layout templates to apply.


#### `<mca_layouts>`

Keys for `<mca_layouts>` are like `<moduleName>[\<controllerName>[\<actionName>]]`, 
where `<moduleName>` is the name of the module, `<controllerName>` is the name of the controller as it is registered to the ControllerLoader, `<actionName>` is the name of the the controller action.
		
		Examples

			Generic

				'MyModule'							//--- applies to all controllers in module
				'MyModule\MyController'				//--- applies to all actions of a controller
				'MyModule\MyController\MyAction'	//--- applies to a particular controller action

			ZfcUser controller (registered as zfcuser)
	
				'ZfcUser'							//--- applies to all controllers of ZfcUser (there is only one ;)
				'ZfcUser\zfcuser'					//--- applies to the controller registered with 'zfcuser'
													//--- (ZfcUser\Controller\UserController) 
				'ZfcUser\zfcuser\login'				//--- login action

			MxcUserManagement controller (registered as 'MxcUserManagement\Controller\UserManagement')

				'MxcUserManagement'					//--- applies to all controllers of module MxcUserManagement

				'MxcUserManagement\MxcUserManagement\Controller\UserManagement'	 
													//--- applies to controller registered with 'MxcUserManagement\Controller\UserManagement' 
													//--- *** In this rule the first occurance of'MxcUserManagement' identifies the module.
													//--- *** The second occurance is part of the controller registration string.

				'MxcUserManagement\MxcUserManagement\Controller\UserManagement\index'	//--- index action 


Action rules are evaluated before controller rules. Controller rules are evaluated before Module rules. So if you apply an action rule and a module rule for the same module, the
module rule applies for all controllers and actions but the one action which has an own
rule.
			

#### `<route_layouts>`	

Keys for `<route_layouts>` are like `<route>`, where `<route>` is a registered route. 

#### `<status_layouts>`	

Keys for `<status_layouts>` are like `<status>`, where `<status>` is status code (type string).

		Example

			'403'			//--- applies to status code 403
 
#### `<error_layouts>`

Keys for `<error_layouts>` are like `<error>`, where `<error>` is the error code returned by the `MvcEvent` (type string).

Rule Definition Values
---

Each rule definition is a list of values like `<capture> => <template>`. The special capture `'layout'` defines the layout applied to the root ViewModel. All other captures define child ViewModels which get applied to the root ViewModel with the capture `<capture>` using the template `<template>`. Template names must be resolvable by either TemplatePathStack or TemplateMap resolvers.

		Example mca rule:

			'MyModule\MyController\index' => array(
				'layout' 	=> 'layout/layout',
				'panelLeft' => 'layout/panel-left',
				'header' 	=> 'layout/header',
				'footer' 	=> 'layout/footer',
			),


Rule Construction
---

While constructing the layout set to apply the service initializes the set with the values from the `'defaults'` section. Then, if a rule matches, the particular set associated with the rule overrides/extends the default set.

		Example

			route_layouts => array(
				'options' => array(
					'home' => array(
						'panelLeft' => 'layout/panel-left'
					),
				),
				'defaults' => array(
					'layout' => 'layout/layout',
					'header' => 'layout/header',
					'footer' => 'layout/footer',
				),
			),
 
Accessing the route `home` causes a match of the according rule. Defaults get applied and afterwards the settings from the matched rule. So the resulting template set is:

		Example result

			array(
				'panelLeft' => 'layout/panel-left'
				'layout' => 'layout/layout',
				'header' => 'layout/header',
				'footer' => 'layout/footer',
			),
 


How MxcLayoutScheme works
-------------------------

1. On Bootstrap MxcLayoutScheme hooks into the route event of the application's EventManager with low priority (-2000).
2. On Bootstrap MxcLayoutScheme instantiates the controller plugin `'layoutScheme'` to inject a reference to the application's ServiceManager instance.
3. On route MxcLayoutScheme evaluates the current route matched, the module name, the controller name and the action name.
4. Then MxcLayoutScheme triggers an `MxcLayoutSchemeService::HOOK_PRE_SELECT_SCHEME` event. If you registered an event handler for that event in the bootstrap somewhere you can set the active scheme with `$e->getTarget()->setActiveScheme($schemeName)` with a `$schemeName`of your choice. Alternatively, you can set the active scheme within the controller action using the controller plugin: `$this->layoutScheme()->setActiveScheme($schemeName)`.
5. Then, MxcLayoutScheme loads the currently active scheme.  
6. MxcLayoutScheme checks the `route_layouts` for a key matching the matched route name. If the key exists the layout template registered to that match gets applied. If the rule defines child view models they get merged with the (optionally) defined default child view models and get applied to the layout. If match continue at 11.
7. MxcLayoutScheme then checks the `mca_layouts` for a key matching Module\Conroller\Action. If the key exists the layout template registered to that match gets applied. If the rule defines child view models they get merged with the (optionally) defined default child view models and get applied to the layout. If match continue at 11.
8. Then, MxcLayoutScheme checks the `mca_layouts` for a key matching Module\Conroller. If the key exists the layout template registered to that match gets applied. If the rule defines child view models they get merged with the (optionally) defined default child view models and get applied to the layout. If match continue at 11.
9. Then, MxcLayoutScheme checks the `mca_layouts` for a key matching the Module. If the key exists the layout template registered to that match gets applied. If the rule defines child view models they get merged with the (optionally) defined default child view models and get applied to the layout. If match continue at 11.
10. Then, MxcLayoutScheme checks the `default` for a key `global`. If the key exists the layout template registered to that match gets applied. If the rule defines child view models they get merged with the (optionally) defined default child view models and get applied to the layout. 
11. Finally MxcLayoutScheme triggers an `MxcLayoutSchemeService::HOOK_POST_LAYOUT_SELECT` event. You may register an event handler to do custom post processing. Example: Assign variables to the selected layout ViewModel and it's child ViewModels using the controller plugin. See an example below

When applying child layouts MxcLayoutScheme maintains references to the child ViewModels for use by the `'layoutScheme'` controller plugin. The controller plugin enables you to apply variables to the child view models
from within the controller action.

How MxcLayoutScheme handles dispatch errors
-------------------------------------------

On Bootstrap MxcLayoutScheme hooks into the dispatch.error event with priority -1000.

When a dispatch error occurs, MxcLayoutScheme first checks for a rule applying to the error code from the `$event->getError()`. If no rule applies MxcLayoutScheme then checks for a rule applying to the status code from $event->getResponse()->getStatusCode().

How MxcLayoutScheme handles content templates
---------------------------------------------

Content templates may be specified via rules like any other template. `<capture> => <template>`.

While the child layouts to the root layout get attached onRoute, the content template gets attached on the dispatch event. 'MxcLayoutScheme' checks for a child template registered to the `content` capture. If found it replaces it's view template. If no content viewmodel is present,
MxcLayoutScheme creates one and with the configured template attached to the `content` capture.

#####Note: 
If you need to set a content view template within your controller action and want it to override a given LayoutScheme definition, you
need to inform layoutScheme to skip it's content view template definition (if present). Using the controller plugin you do that by `$this->layoutScheme()->useControllerContentTemplate()`. 


Example Event Handler to choose the active scheme
--------------------------------------------------

	use MxcLayoutScheme\Service\LayoutSchemeService;

	...

    public function onBootstrap(MvcEvent $e)
    {
    	$app = $e->getApplication();
    	$em = $app->getEventManager();
		$sem = $em->getSharedManager();
    	$sem->attach('MxcLayoutScheme\Service\LayoutSchemeService',
			LayoutSchemeService::HOOK_PRE_SELECT_SCHEME, 
			function($e) {
				switch ($weather) {
					case 'sunny':
						$schemeName = 'sun';
						break;
					case 'rainy':
						$schemeName = 'umbrella';
						break;
					default:
						$schemeName = 'default';
						break;
				}
				$e->getTarget()->setActiveScheme($schemeName);
			}, 100);
    }

Example Event Handler to do some postprocessing after layout selection has finished
-------------------------------------------------------------------------------------

	use MxcLayoutScheme\Service\LayoutSchemeService;

	...

    public function onBootstrap(MvcEvent $e)
    {
    	$app = $e->getApplication();
    	$em = $app->getEventManager();

        $sem = $em->getSharedManager();
        $sem->attach('MxcLayoutScheme\Service\LayoutSchemeService',
        		LayoutSchemeService::HOOK_POST_SELECT_LAYOUT,
        		function($e) {
        			$variables = array(
        					'berliner' => 'Ich',
        					'ein' => 'bin',
        					'bin' => 'ein',
        					'ich' => 'Berliner! :)'
        			);
        
        			// apply this set of variables to the layout view model and all registered
        			// registered child view models
        			$e->getTarget()->setVariables($variables);
        
        		}, 100);

    }

Special Child Template Names
----------------------------

A child view model is defined by an array entry `<capture> => <templateName>`. `templateName` is either the name of an explicitly registered template in the ViewManager's `template_map` or a template name which can automatically be resolved via the ViewManager's `template_path_stack`.

Additionally, there are two reserved values which you can use instead: `'<default>'` and `'<none>'` (including < and >)

####templateName `'<default>'`:

If you specify `<default>` as the templateName, MxcLayoutScheme computes a template name which can be resolved by the `TemplatePathStack` resolver. Based on the actual `<module>`, `<controller>` and `<action>` the rule `<capture> => <default>` the `Zend\Filter\Word\CamelCaseToDash` gets applied to the string `<module>\<controller>\<action>-<capture>` and the result gets assigned lowercase to the templateName. 

######Example 1:

May the module be `Reporting`, the controller class `WbsController`, the action be `listAction`.
May the the child ViewModel definition be `'header' => '<default>'`.

The templateName computes to `'reporting\wbs\list-header'`. If you provide a template named `list-header.phtml` within the folder `view\reporting\wbs\` of your module directory it gets found by the `TemplatePathStack` resolver when rendering the `header` capture of the layout (by ` echo $this->header 

 if ($this->panelLeft) : 

 echo $this->panelLeft 

 endif; 

 echo $this->content