mockup/master: Merge pull request #785 from plone/thet-structureupdater-doc

Repository: mockup
Branch: refs/heads/master
Date: 2017-07-13T14:22:48+02:00
Author: Johannes Raggam (thet) <[email protected]>
Commit: https://github.com/plone/mockup/commit/69c3cc7d4ec15fe0dcb496192b5cd243f3493498

Merge pull request #785 from plone/thet-structureupdater-docs

Add docs on how to customize the structure updater pattern

Files changed:
A mockup/patterns/structure/README.rst
M CHANGES.rst
M mockup/patterns/structure/pattern-structureupdater.js

diff --git a/CHANGES.rst b/CHANGES.rst
index 0159fe78..acb27972 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -6,7 +6,8 @@ Changelog
 
 New features:
 
-- * Add item here *
+- Added docs for the structureupdater pattern.
+  [thet]
 
 Incompatibile changes:
 
diff --git a/mockup/patterns/structure/README.rst b/mockup/patterns/structure/README.rst
new file mode 100644
index 00000000..a8ec6ef2
--- /dev/null
+++ b/mockup/patterns/structure/README.rst
@@ -0,0 +1,108 @@
+How to customize the Structure Updater pattern
+==============================================
+
+The ``mockup-pattern-structureupdater`` updates the title and description on the page - if available - when a folder is changed in the structure pattern. It's triggered by the class ``template-folder_contents``, which is available on the body tag when the folder contents page is opened. The pattern listens on the ``context-info-loaded`` event, which is triggered by the structure pattern.
+
+Often you will have customized layouts, where you need to update also other parts of the site when the user changes to another folder.
+
+
+Pattern configuration
+---------------------
+
+For simple cases, you can customize the CSS selector for the title and description via the options ``titleSelector`` and ``descriptionSelector`` for the pattern.
+This can be done by adding options for that pattern via the resource registry control panel under the "Pattern options" tab or via the ``registry.xml`` profile like so::
+
+  <record name="plone.patternoptions">
+    <value purge="False">
+      <element key="structureupdater">{"titleSelector": "h1.documentFirstHeading", "descriptionSelector": "footer"}</element>
+    </value>
+  </record>
+
+.. note::
+    For the ``titleSelector`` and ``descriptionSelector`` you have to provide valid JQuery selectors.
+    Like with any CSS selector you can also specify mutliple selectors by seperating them via a comma sign.
+
+
+Pattern overloading
+-------------------
+
+If you need some more control, you can overload the pattern and provide your own.
+
+The pattern is registered in the RequireJS configuration in ``mockup/js/config.js`` under the name ``mockup-patterns-structureupdater`` and under the path ``patterns/structure/pattern-structureupdater``.
+
+If you provide another path you can point it to your own implementation.
+
+This can be easily done in Plone, where the RequireJS configuration are ``plone.app.registry`` entries.
+
+For example, in your project's ``registry.xml`` profile, add this::
+
+    <?xml version="1.0"?>
+    <registry i18n:domain="plone" xmlns:i18n="http://xml.zope.org/namespaces/i18n">
+
+      <records
+          prefix="plone.resources/mockup-patterns-structureupdater"
+          interface='Products.CMFPlone.interfaces.IResourceRegistry'>
+        <value key="js">++plone++my.project.resources/mockup-patterns-structureupdater.js</value>
+      </records>
+
+    </registry>
+
+
+In that example the custom implementation of the structure updater pattern lives in a ``plone.resource`` directory named ``my.project.resources``.
+This is configured in the project's ``configure.zcml``::
+
+    <?xml version="1.0"?>
+    <configure
+        xmlns="http://namespaces.zope.org/zope"
+        xmlns:plone="http://namespaces.plone.org/plone">
+      <plone:static
+          directory="resources"
+          name="my.project.resources"
+          type="plone"
+      />
+    </configure>
+
+The custom implementation ``mockup-patterns-structureupdater.js`` looks like so::
+
+    define([
+        'pat-base',
+    ], function(Base) {
+        'use strict';
+        var Pattern = Base.extend({
+          name: 'structureupdater2',
+          trigger: '.template-folder_contents',
+          parser: 'mockup',
+          init: function() {
+            $('body').on('context-info-loaded', function (e, data) {
+              // Do something
+              $('.breadcrumb').html(data.object && '<li>' + data.object.Title + '</li>');
+            }.bind(this));
+          }
+        });
+        return Pattern;
+    });
+
+
+You probably want to include the original behavior.
+If you have given the pattern another name than the original pattern, you can just let RequireJS depend on the original pattern and it will be registered and triggered as normal.
+We can include the original pattern via the ``mockup-patterns-structure-url`` path and incldue then the filename.
+The code looks then like so::
+
+    define([
+        'pat-base',
+        'mockup-patterns-structure-url/pattern-structureupdater',
+    ], function(Base) {
+        'use strict';
+        var Pattern = Base.extend({
+          name: 'structureupdater2',  // Give it another name than the original pattern
+          trigger: '.template-folder_contents',
+          parser: 'mockup',
+          init: function() {
+            $('body').on('context-info-loaded', function (e, data) {
+              // Do something
+              $('.breadcrumb').html(data.object && '<li>' + data.object.Title + '</li>');
+            }.bind(this));
+          }
+        });
+        return Pattern;
+    });
diff --git a/mockup/patterns/structure/pattern-structureupdater.js b/mockup/patterns/structure/pattern-structureupdater.js
index 75eebfd3..abaaa214 100644
--- a/mockup/patterns/structure/pattern-structureupdater.js
+++ b/mockup/patterns/structure/pattern-structureupdater.js
@@ -27,8 +27,12 @@ define([
     init: function() {
 
       $('body').on('context-info-loaded', function (e, data) {
-        $(this.options.titleSelector, this.$el).html(data.object && data.object.Title || '&nbsp;');
-        $(this.options.descriptionSelector, this.$el).html(data.object && data.object.Description || '&nbsp;');
+        if (this.options.titleSelector) {
+            $(this.options.titleSelector, this.$el).html(data.object && data.object.Title || '&nbsp;');
+        }
+        if (this.options.descriptionSelector) {
+            $(this.options.descriptionSelector, this.$el).html(data.object && data.object.Description || '&nbsp;');
+        }
       }.bind(this));
 
     }



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot