Enable disabling of unique block wrappers and improve theme flexibili…

…ty and documentation.

CHANGELOG-1.4.md

@@ -33,6 +33,7 @@ CHANGELOG - ZIKULA 1.4.x
       - MailerEvents::SEND_MESSAGE_FAILURE - Occurs when a message could not be sent.
     - Lengthen ip address fields for IPv6 support (#2893).
     - More intelligent handling of missing mail transport options (#2148).
+    - Enable disabling of unique block wrappers and improve theme flexibility and documentation (#3013).
 
  - Core-2.0 Features:
     - AdminModule updated to Core-2.0 Spec (#2856, #2860).

src/docs/Core-2.0/Themes/Class.md

@@ -0,0 +1,12 @@
+ThemeClass
+==========
+
+Filename: `<Vendor><Name>Theme.php`
+
+Status: Required
+
+Must: `extends Zikula\ThemeModule\AbstractTheme`
+
+Description: This class establishes the extension in the Symfony ecosystem as a **Bundle**.
+See the parent classes for more information. This class does not require any content, though overriding certain
+parent methods can provide for additional customization.

src/docs/Core-2.0/Themes/ComposerFile.md

@@ -0,0 +1,31 @@
+Theme Composer file
+===================
+
+Filename: `composer.json`
+
+Status: Required
+
+Description: define the extension and various features and capabilities. Specific keys are required and others are optional.
+The composer.json file is also used by composer and packagist to enable package installation.
+
+Please see the [Official JSON Schema](https://getcomposer.org/doc/04-schema.md) for full details on most items
+
+ - name: (required) can be anything, but typically `<vendor>/<name>-<type>`
+ - version: (required) must adhere to [semver requirements](http://semver.org).
+ - description: (required) a one sentence description of the extension (translatable)
+ - type: (required) zikula-theme
+ - license: (required) License name (string) or an array of license names (array of strings) under which the extension 
+   is provided. You must use the standardized identifier acronym for the license as defined by 
+   [Software Package Data Exchange](http://spdx.org/licenses/)
+ - authors: (optional but recommended) an array of objects indicating author or group information
+ - autoload: (required) object defining psr-4 namespace object
+ - require: (required) object defining bundle dependencies
+ - extra: (required) the zikula object with required keys
+   - zikula: (required)
+     - core-compatibility: (required) a [version compatibility string](https://getcomposer.org/doc/01-basic-usage.md#package-versions) defining core compatibility
+     - class: (required) the fully qualified name of the Bundle class
+     - displayname: (required) the common name for the bundle (translatable)
+     - capabilities: (required if controllers are used) an object of objects defining capabilities of the extension
+         - user: true|false
+         - admin: true|false
+         - xhtml: true|false

src/docs/Core-2.0/Themes/Config.md

@@ -0,0 +1,33 @@
+Theme Config
+============
+
+file: `/Resources/config/theme.yml`
+
+Status: Required
+
+Must: define a 'master' realm
+
+Description: define various 'realms' within a theme. Within a realm, a pattern is defined that is used by regex
+to match the (1) path, (2) route id, or (3) the module name. The realms are matched from top to bottom returning the
+first match (case-insensitive). Therefore, more specific definitions must be higher than general definitions.
+
+Two additional 'alias' realms may be defined and neither requires a pattern:
+  1) Defining an 'admin' realm will be used when @Theme('admin') annotation is detected in the method
+  2) Defining a 'home' realm will be used when the path = `/`
+
+Any block positions in the page's template must be defined here.
+
+Do not duplicate realm names or later entries will override previous entries
+
+
+Optional Values
+---------------
+
+ - bootstrapPath
+    set a full path from the site root to override the core bootstrap.css
+    - e.g.: `bootstrapPath: themes/BootstrapTheme/Resources/public/css/cerulean.min.css`
+ - blockWrapping
+    set a boolean value to indicate whether ALL blocks will be wrapped with a unique container `<div>`
+     - e.g. `blockWrapping: false`
+     - default: `true` (if no parameter is set)
+     - WARNING: certain core functionalities (e.g. collapseable blocks) require this `<div>` and break without it.

src/docs/Core-2.0/Themes/DependencyInjection.md

@@ -0,0 +1,22 @@
+DependencyInjection
+===================
+
+Just like any Symfony bundle, Zikula themes are allowed to utilize the DIC (Dependency Injection Container). 
+
+reference: http://symfony.com/doc/current/components/dependency_injection/index.html
+
+Status: Optional
+
+The DependencyInjection component of Symfony can be quite complex, but the initial implementation of it can be
+done quite simply. Here, the extension file must be named `<Vendor><Name>Extension.php` and simply
+creates a loader and loads the `services.yml` file.
+
+----
+
+Filename: `services.yml`
+
+Status: Optional
+
+Description: The DependencyInjection component of Symfony can be quite complex. Several filetypes can be used
+(.yml, .xml, etc). Please see the symfony documentation for further information.
+http://symfony.com/doc/current/components/dependency_injection/index.html

src/docs/Core-2.0/Themes/Structure.md

@@ -0,0 +1,48 @@
+Theme File Structure
+====================
+
+Reference: http://symfony.com/doc/current/cookbook/bundles/best_practices.html
+
+```
+SpecTheme/
+    Controller/
+        FooController.php
+    DependencyInjection/
+        SpecThemeExtension.php (required if services are used)
+    Listener/
+        FooListener.php
+    Resources/
+        config/
+            theme.yml (required)
+            services.yml (required if services are used)
+        docs/
+            index.rst
+        meta/
+            LICENSE
+        public/
+            css/
+            images/
+            js/
+        translations/
+            messages.en.pot
+            zikulaspectheme.pot
+        views/
+            Block/
+                block.html.twig
+            Body/
+                2col.html.twig
+            Include/
+                footer.html.twig
+                header.html.twig
+            admin.html.twig
+            home.html.twig
+            master.html.twig
+    Twig/
+        SpecThemeExtension.php (required to create filters and functions)
+    vendor/
+    ZikulaSpecTheme.php (required)
+    CHANGELOG.md
+    README.md
+    composer.json (required)
+    phpunit.xml.dist
+```

src/docs/Core-2.0/Themes/TemplateOverrides.md

@@ -0,0 +1,27 @@
+Theme Template Overrides
+========================
+
+**Theme resource overrides** are placed here under the target FQ Module name.
+
+```
+    Resources/
+        config/
+        public/
+        views/
+        ZikulaSpecModule/
+            public/
+                css/
+                    style.css
+            views/
+                Foo/
+                    index.html.twig
+```
+
+#### System Resource Overrides
+Symfony has a system in place to override Resources of any Bundle. See 
+[Overriding Resources](http://symfony.com/doc/current/cookbook/bundles/inheritance.html#overriding-resources-templates-routing-etc)
+**Note that in Zikula, System Resource overrides take precedence over Theme Resource overrides.**
+
+##### Override references
+ - see `\Zikula\Bundle\CoreBundle\EventListener\ThemeListener::setUpThemePathOverrides` (for @ZikulaFoo/Bar/index.html.twig type notation)
+ - see `\Zikula\Bundle\CoreBundle\HttpKernel\ZikulaKernel::locateResource` (for ZikulaFooBundle:Bar:index.html.twig type notation)

src/lib/Zikula/Bundle/CoreBundle/Resources/views/Default/blockwrapper.html.twig

@@ -0,0 +1 @@
+<div class="z-block z-blockposition-{{ position|lower }} z-bkey-{{ type|lower }} z-bid-{{ bid }}">{{ content|raw }}</div>

src/lib/Zikula/Bundle/CoreBundle/Resources/views/Default/maincontent.html.twig

@@ -0,0 +1 @@
+<div id="z-maincontent" class="{{ classes|lower }}">{{ maincontent|raw }}</div>

src/system/ThemeModule/AbstractTheme.php

@@ -63,14 +63,13 @@ public function __construct()
     public function generateThemedResponse($realm, Response $response, $moduleName = null)
     {
         $template = $this->config[$realm]['page'];
-        $content = '<div id="z-maincontent" class="'
-            . ($realm == 'home' ? 'z-homepage' : '')
-            . (isset($moduleName) ? ' z-module-' . strtolower($moduleName) : '') . '">'
-            . $response->getContent()
-            . '</div>';
-        $response->setContent($content);
-
-        return $this->getContainer()->get('templating')->renderResponse($this->name . ':' . $template, ['maincontent' => $response->getContent()]);
+        $classes = $realm == 'home' ? 'z-homepage' : '' . (empty($classes) ? '' : ' ') . (isset($moduleName) ? 'z-module-' . $moduleName : '');
+        $content = $this->getContainer()->get('templating')->render('CoreBundle:Default:maincontent.html.twig', [
+            'classes' => $classes,
+            'maincontent' => $response->getContent()
+        ]);
+
+        return $this->getContainer()->get('templating')->renderResponse($this->name . ':' . $template, ['maincontent' => $content]);
     }
 
     /**
@@ -94,12 +93,31 @@ public function generateThemedBlockContent($realm, $positionName, $blockContent,
             'title' => $blockTitle,
             'content' => $blockContent
         ];
-        // @todo add collapsable block code see \BlockUtil::themeBlock
-        // @todo including check for `isCollapsed` like \BlockUtil::checkUserBlock
 
         return $this->getContainer()->get('templating')->render($template, $templateParameters);
     }
 
+    /**
+     * Enclose themed block content in a unique div which is useful in applying styling.
+     *
+     * @param string $content
+     * @param string $positionName
+     * @param string $blockType
+     * @param integer $bid
+     * @return string
+     */
+    public function wrapBlockContentWithUniqueDiv($content, $positionName, $blockType, $bid)
+    {
+        $templateParams = [
+            'position' => $positionName,
+            'type' => $blockType,
+            'bid' => $bid,
+            'content' => $content
+        ];
+
+        return $this->getContainer()->get('templating')->render('CoreBundle:Default:blockwrapper.html.twig', $templateParams);
+    }
+
     /**
      * load the themevars into the themeEngine global vars
      */

src/system/ThemeModule/Engine/Engine.php

@@ -152,7 +152,7 @@ public function wrapBcBlockInTheme(array $blockInfo)
     }
 
     /**
-     * Wrap the block content in the theme block template and wrap that with a unique div.
+     * Wrap the block content in the theme block template and wrap that with a unique div if required.
      * @api Core-2.0
      * @param string $content
      * @param string $title
@@ -168,28 +168,10 @@ public function wrapBlockContentInTheme($content, $title, $blockType, $bid, $pos
             // legacy blocks are already themed at this point. @todo at Core-2.0 remove $legacy param and this check.
             $content = $this->getTheme()->generateThemedBlockContent($this->getRealm(), $positionName, $content, $title);
         }
+        $themeConfig = $this->getTheme()->getConfig();
+        $wrap = isset($themeConfig['blockWrapping']) ? $themeConfig['blockWrapping'] : true;
 
-        // always wrap the block (in the previous versions this was configurable, but no longer) @todo remove comment
-        return $this->wrapBlockContentWithUniqueDiv($content, $positionName, $blockType, $bid);
-    }
-
-    /**
-     * Enclose themed block content in a unique div which is useful in applying styling.
-     *
-     * @param string $content
-     * @param string $positionName
-     * @param string $blockType
-     * @param integer $bid
-     * @return string
-     */
-    private function wrapBlockContentWithUniqueDiv($content, $positionName, $blockType, $bid)
-    {
-        return '<div class="z-block '
-            . 'z-blockposition-' . strtolower($positionName)
-            .' z-bkey-' . strtolower($blockType)
-            . ' z-bid-' . $bid . '">' . "\n"
-            . $content
-            . "</div>\n";
+        return $wrap ? $this->getTheme()->wrapBlockContentWithUniqueDiv($content, $positionName, $blockType, $bid): $content;
     }
 
     /**

src/themes/BootstrapTheme/Resources/config/overrides.yml

@@ -1,8 +1,4 @@
 ## YAML Override template
 ## original/file.tpl: override/file.tpl
 ---
-#system/UsersModule/Resources/views/User/main.tpl: themes/BootstrapTheme/Resources/views/modules/ZikulaUsersModule/User/main.tpl
-system/UsersModule/Resources/views/Block/login_topnav.tpl: themes/BootstrapTheme/Resources/views/modules/ZikulaUsersModule/Block/login_topnav.tpl
 system/BlocksModule/Resources/views/Block/Extmenu/topnav.tpl: themes/BootstrapTheme/Resources/views/modules/ZikulaBlocksModule/Block/Extmenu/topnav.tpl
-system/UsersModule/Resources/views/Authentication/AuthenticationMethodSelector/loginblock/Base.tpl: themes/BootstrapTheme/Resources/views/modules/ZikulaUsersModule/Authentication/AuthenticationMethodSelector/loginblock/Base.tpl
-modules/OpenID/templates/Authentication/LoginFormFields/loginblock/Google.tpl: themes/BootstrapTheme/Resources/views/modules/OpenID/Authentication/LoginFormFields/loginblock/Google.tpl

src/themes/BootstrapTheme/Resources/config/theme.yml

@@ -25,3 +25,4 @@ master:
       center: "Block:block.html.twig"
       topnav: "Block:topnavblock.html.twig"
 bootstrapPath: themes/BootstrapTheme/Resources/public/css/cerulean.min.css
+#blockWrapping: false