Merge branch 'develop-ascraeus' into develop

* develop-ascraeus:
  [ticket/12509] Add example in doc block
  [ticket/12509] Add missing ',' in arrays
  [ticket/12509] Update calls to set_custom_style in forgotten places
  [ticket/12509] Fix path in adm/index.php
  [ticket/12509] Fix typo in adm/index.php
  [ticket/12509] Fix doc block
  [ticket/12509] Fix the call to set_custom_file in adm/index and messenger
  [ticket/12509] Update acp custom_style setter
  [ticket/12509] Add an option to set the path of custom file for extensions

phpBB/adm/index.php

@@ -50,7 +50,13 @@ $module_id		= request_var('i', '');
 $mode			= request_var('mode', '');
 
 // Set custom style for admin area
-$template->set_custom_style('adm', $phpbb_admin_path . 'style');
+$template->set_custom_style(array(
+	array(
+		'name' 		=> 'adm',
+		'ext_path' 	=> 'adm/style/',
+	),
+), $phpbb_admin_path . 'style');
+
 $template->assign_var('T_ASSETS_PATH', $phpbb_root_path . 'assets');
 $template->assign_var('T_TEMPLATE_PATH', $phpbb_admin_path . 'style');
 

phpBB/includes/functions_messenger.php

@@ -252,7 +252,12 @@ class messenger
 			}
 		}
 
-		$this->set_template_paths($template_lang . '_email', $template_paths);
+		$this->set_template_paths(array(
+			array(
+				'name' 		=> $template_lang . '_email',
+				'ext_path' 	=> 'language/' . $template_lang . '/email'
+			),
+		), $template_paths);
 
 		$this->template->set_filenames(array(
 			'body'		=> $template_file . '.txt',

phpBB/includes/functions_module.php

@@ -581,7 +581,12 @@ class p_master
 
 				if (is_dir($module_style_dir))
 				{
-					$template->set_custom_style('adm', array($module_style_dir, $phpbb_admin_path . 'style'));
+					$template->set_custom_style(array(
+						array(
+							'name' 		=> 'adm',
+							'ext_path' 	=> 'adm/style/',
+						),
+					), array($module_style_dir, $phpbb_admin_path . 'style'));
 				}
 			}
 

phpBB/install/index.php

@@ -250,7 +250,12 @@ $phpbb_path_helper = $phpbb_container->get('path_helper');
 $template = new \phpbb\template\twig\twig($phpbb_path_helper, $config, $user, new \phpbb\template\context());
 $paths = array($phpbb_root_path . 'install/update/new/adm/style', $phpbb_admin_path . 'style');
 $paths = array_filter($paths, 'is_dir');
-$template->set_custom_style('adm', $paths);
+$template->set_custom_style(array(
+	array(
+		'name' 		=> 'adm',
+		'ext_path' 	=> 'adm/style/',
+	),
+), $paths);
 
 $path = array_shift($paths);
 

phpBB/install/install_update.php

@@ -141,7 +141,12 @@ class install_update extends module
 		// Set custom template again. ;)
 		$paths = array($phpbb_root_path . 'install/update/new/adm/style', $phpbb_admin_path . 'style');
 		$paths = array_filter($paths, 'is_dir');
-		$template->set_custom_style('adm', $paths);
+		$template->set_custom_style(array(
+			array(
+				'name' 		=> 'adm',
+				'ext_path' 	=> 'adm/style/',
+			),
+		), $paths);
 
 		$template->assign_vars(array(
 			'S_USER_LANG'			=> $user->lang['USER_LANG'],

phpBB/phpbb/template/twig/twig.php

@@ -211,9 +211,13 @@ class twig extends \phpbb\template\base
 	*
 	* Note: Templates are still compiled to phpBB's cache directory.
 	*
-	* @param string|array $names Array of names or string of name of template(s) in inheritance tree order, used by extensions.
+	* @param string|array $names Array of names (or detailed names) or string of name of template(s) in inheritance tree order, used by extensions.
-	* @param string|array or string $paths Array of style paths, relative to current root directory
+	*	E.g. array(
-	* @return phpbb_template $this
+	*			'name' 		=> 'adm',
+	*			'ext_path' 	=> 'adm/style/',
+	*		)
+	* @param string|array of string $paths Array of style paths, relative to current root directory
+	* @return \phpbb\template\template $this
 	*/
 	public function set_custom_style($names, $paths)
 	{
@@ -234,10 +238,26 @@ class twig extends \phpbb\template\base
 				$namespace = str_replace('/', '_', $ext_namespace);
 				$paths = array();
 
-				foreach ($names as $style_name)
+				foreach ($names as $template_dir)
 				{
-					$ext_style_path = $ext_path . 'styles/' . $style_name . '/';
+					if (is_array($template_dir))
+					{
+						if (isset($template_dir['ext_path']))
+						{
+							$ext_style_template_path = $ext_path . $template_dir['ext_path'];
+							$ext_style_path = dirname($ext_style_template_path);
+						}
+						else
+						{
+							$ext_style_path = $ext_path . 'styles/' . $template_dir['name'] . '/';
 							$ext_style_template_path = $ext_style_path . 'template/';
+						}
+					}
+					else
+					{
+						$ext_style_path = $ext_path . 'styles/' . $template_dir . '/';
+						$ext_style_template_path = $ext_style_path . 'template/';
+					}
 
 					if (is_dir($ext_style_template_path))
 					{