From 3170dd61eafa50c3f894c997193820674d6e7a18 Mon Sep 17 00:00:00 2001
From: Samuel Georges <sam@daftspunk.com>
Date: Tue, 16 Dec 2014 15:41:50 +1100
Subject: [PATCH] Add new methods propertyName() and paramName() to Component
 base class for accessing names of external properties.

---
 CHANGELOG.md                          |  3 ++
 modules/cms/classes/ComponentBase.php | 78 ++++++++++++++++++++++++++-
 modules/cms/classes/Controller.php    |  1 +
 3 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e62d17ab7..76a763cf8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,6 @@
+* **Build 171** (2014-12-xx)
+  - Add new methods `propertyName()` and `paramName()` to Component base class for accessing names of external properties.
+
 * **Build 169** (2014-12-16)
   - Native `alert` and `confirm` functions have been styled in the back-end.
   - Back-end user groups have a new description field, this is shown in the group list and when creating a new administrator.
diff --git a/modules/cms/classes/ComponentBase.php b/modules/cms/classes/ComponentBase.php
index ee3c9156b..84113a359 100644
--- a/modules/cms/classes/ComponentBase.php
+++ b/modules/cms/classes/ComponentBase.php
@@ -73,9 +73,9 @@ abstract class ComponentBase extends Extendable
     protected $page;
 
     /**
-     * @var array Cache of linked Component objects, used for page links.
+     * @var array A collection of external property names used by this component.
      */
-    // protected $pageLinkCache = [];
+    protected $externalPropertyNames = [];
 
     /**
      * Component constructor. Takes in the page or layout code section object
@@ -167,6 +167,80 @@ abstract class ComponentBase extends Extendable
         return $this->alias;
     }
 
+    //
+    // External properties
+    //
+
+    /*
+     * Description on how to access external property names.
+     *
+     * # When
+     * pageNumber = "7"
+     * $this->propertyName('pageNumber'); // Returns NULL
+     * $this->paramName('pageNumber');    // Returns NULL
+     *
+     * # When
+     * pageNumber = "{{ :page }}"
+     *
+     * $this->propertyName('pageNumber'); // Returns ":page"
+     * $this->paramName('pageNumber');    // Returns "page"
+     *
+     * # When
+     * pageNumber = "{{ page }}"
+     *
+     * $this->propertyName('pageNumber'); // Returns "page"
+     * $this->paramName('pageNumber');    // Returns NULL
+     */
+
+    /**
+     * Sets names used by external properties.
+     * @param array $names The key should be the property name,
+     *                     the value should be the external property name.
+     * @return void
+     */
+    public function setExternalPropertyNames(array $names)
+    {
+        $this->externalPropertyNames = $names;
+    }
+
+    /**
+     * Sets an external property name.
+     * @param string $name Property name
+     * @param string $extName External property name
+     */
+    public function setExternalPropertyName($name, $extName)
+    {
+        return $this->externalPropertyNames[$name] = $extName;
+    }
+
+    /**
+     * Returns the external property name when the property value is an external property reference.
+     * Otherwise the default value specified is returned.
+     * @param string $name The property name
+     * @param mixed $default
+     * @return string
+     */
+    public function propertyName($name, $default = null)
+    {
+        return array_get($this->externalPropertyNames, $name, $default);
+    }
+
+    /**
+     * Returns the external property name when the property value is a routing parameter reference.
+     * Otherwise the default value specified is returned.
+     * @param string $name The property name
+     * @param mixed $default
+     * @return string
+     */
+    public function paramName($name, $default = null)
+    {
+        if (($extName = $this->propertyName($name)) && substr($extName, 0, 1) == ':') {
+            return substr($extName, 1);
+        }
+
+        return $default;
+    }
+
     /**
      * @deprecated Returns a defined property or parameter value.
      * @todo Remove this method if year >= 2015
diff --git a/modules/cms/classes/Controller.php b/modules/cms/classes/Controller.php
index c77027ade..c0ac0648c 100644
--- a/modules/cms/classes/Controller.php
+++ b/modules/cms/classes/Controller.php
@@ -1126,6 +1126,7 @@ class Controller extends BaseController
                 }
 
                 $component->setProperty($propertyName, $newPropertyValue);
+                $component->setExternalPropertyName($propertyName, $paramName);
             }
         }
     }