Add new methods propertyName() and paramName() to Component base class for accessing names of external properties.

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.

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

modules/cms/classes/Controller.php

@@ -1126,6 +1126,7 @@ class Controller extends BaseController
                 }
 
                 $component->setProperty($propertyName, $newPropertyValue);
+                $component->setExternalPropertyName($propertyName, $paramName);
             }
         }
     }