API Deprecations for template layer (#11420)

src/Forms/GridField/GridFieldDataColumns.php

@@ -5,6 +5,7 @@
 use SilverStripe\Core\Convert;
 use InvalidArgumentException;
 use LogicException;
+use SilverStripe\Dev\Deprecation;
 use SilverStripe\View\ViewableData;
 
 /**
@@ -228,9 +229,11 @@ public function getColumnMetadata($gridField, $column)
      * @param ViewableData $record
      * @param string $columnName
      * @return string|null - returns null if it could not found a value
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it.
      */
     protected function getValueFromRelation($record, $columnName)
     {
+        Deprecation::notice('5.4.0', 'Will be removed without equivalent functionality to replace it.');
         $fieldNameParts = explode('.', $columnName ?? '');
         $tmpItem = clone($record);
         for ($idx = 0; $idx < sizeof($fieldNameParts ?? []); $idx++) {

src/View/SSTemplateParser.peg

@@ -948,7 +948,7 @@ class SSTemplateParser extends Parser implements TemplateParser
         $arguments = $res['arguments'];
 
         // Note: 'type' here is important to disable subTemplates in SSViewer::getSubtemplateFor()
-        $res['php'] = '$val .= \\SilverStripe\\View\\SSViewer::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getItem(), [' .
+        $res['php'] = '$val .= \\SilverStripe\\View\\SSViewer::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
             implode(',', $arguments)."], \$scope, true);\n";
 
         if ($this->includeDebuggingComments) { // Add include filename comments on dev sites

src/View/SSTemplateParser.php

@@ -3897,7 +3897,7 @@ function Include__finalise(&$res)
         $arguments = $res['arguments'];
 
         // Note: 'type' here is important to disable subTemplates in SSViewer::getSubtemplateFor()
-        $res['php'] = '$val .= \\SilverStripe\\View\\SSViewer::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getItem(), [' .
+        $res['php'] = '$val .= \\SilverStripe\\View\\SSViewer::execute_template([["type" => "Includes", '.$template.'], '.$template.'], $scope->getCurrentItem(), [' .
             implode(',', $arguments)."], \$scope, true);\n";
 
         if ($this->includeDebuggingComments) { // Add include filename comments on dev sites

src/View/SSViewer_DataPresenter.php

@@ -4,14 +4,15 @@
 
 use InvalidArgumentException;
 use SilverStripe\Core\ClassInfo;
+use SilverStripe\Dev\Deprecation;
 use SilverStripe\ORM\FieldType\DBField;
 
 /**
  * This extends SSViewer_Scope to mix in data on top of what the item provides. This can be "global"
  * data that is scope-independant (like BaseURL), or type-specific data that is layered on top cross-cut like
  * (like $FirstLast etc).
  *
- * It's separate from SSViewer_Scope to keep that fairly complex code as clean as possible.
+ * @deprecated 5.4.0 Will be merged into SilverStripe\View\SSViewer_Scope
  */
 class SSViewer_DataPresenter extends SSViewer_Scope
 {
@@ -65,6 +66,7 @@ public function __construct(
         array $underlay = null,
         SSViewer_Scope $inheritedScope = null
     ) {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be merged into ' . SSViewer_Scope::class, Deprecation::SCOPE_CLASS);
         parent::__construct($item, $inheritedScope);
 
         $this->overlay = $overlay ?: [];

src/View/SSViewer_FromString.php

@@ -3,9 +3,11 @@
 namespace SilverStripe\View;
 
 use SilverStripe\Core\Config\Config;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Special SSViewer that will process a template passed as a string, rather than a filename.
+ * @deprecated 5.4.0 Will be replaced with SilverStripe\View\SSTemplateEngine::renderString()
  */
 class SSViewer_FromString extends SSViewer
 {
@@ -37,6 +39,11 @@ class SSViewer_FromString extends SSViewer
      */
     public function __construct($content, TemplateParser $parser = null)
     {
+        Deprecation::noticeWithNoReplacment(
+            '5.4.0',
+            'Will be replaced with SilverStripe\View\SSTemplateEngine::renderString()',
+            Deprecation::SCOPE_CLASS
+        );
         if ($parser) {
             $this->setParser($parser);
         }

src/View/SSViewer_Scope.php

@@ -5,6 +5,7 @@
 use ArrayIterator;
 use Countable;
 use Iterator;
+use SilverStripe\Dev\Deprecation;
 use SilverStripe\ORM\FieldType\DBBoolean;
 use SilverStripe\ORM\FieldType\DBText;
 use SilverStripe\ORM\FieldType\DBFloat;
@@ -123,16 +124,23 @@ public function __construct($item, SSViewer_Scope $inheritedScope = null)
      * Returns the current "active" item
      *
      * @return object
+     * @deprecated 5.4.0 use getCurrentItem() instead.
      */
     public function getItem()
     {
+        Deprecation::notice('5.4.0', 'use getCurrentItem() instead.');
         $item = $this->itemIterator ? $this->itemIterator->current() : $this->item;
         if (is_scalar($item)) {
             $item = $this->convertScalarToDBField($item);
         }
         return $item;
     }
 
+    public function getCurrentItem()
+    {
+        return $this->getItem();
+    }
+
     /**
      * Called at the start of every lookup chain by SSTemplateParser to indicate a new lookup from local scope
      *
@@ -185,7 +193,7 @@ public function resetLocalScope()
      */
     public function getObj($name, $arguments = [], $cache = false, $cacheName = null)
     {
-        $on = $this->getItem();
+        $on = $this->getCurrentItem();
         if ($on === null) {
             return null;
         }
@@ -198,9 +206,11 @@ public function getObj($name, $arguments = [], $cache = false, $cacheName = null
      * @param bool $cache
      * @param string $cacheName
      * @return $this
+     * @deprecated 5.4.0 Will be renamed scopeToIntermediateValue()
      */
     public function obj($name, $arguments = [], $cache = false, $cacheName = null)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be renamed scopeToIntermediateValue()');
         switch ($name) {
             case 'Up':
                 if ($this->upIndex === null) {
@@ -252,7 +262,7 @@ public function obj($name, $arguments = [], $cache = false, $cacheName = null)
      */
     public function self()
     {
-        $result = $this->getItem();
+        $result = $this->getCurrentItem();
         $this->resetLocalScope();
 
         return $result;
@@ -350,8 +360,12 @@ public function next()
      */
     public function __call($name, $arguments)
     {
-        $on = $this->getItem();
-        $retval = $on ? $on->$name(...$arguments) : null;
+        $on = $this->getCurrentItem();
+        if ($on instanceof ViewableData && $name === 'XML_val') {
+            $retval = $on->XML_val(...$arguments);
+        } else {
+            $retval = $on ? $on->$name(...$arguments) : null;
+        }
 
         $this->resetLocalScope();
         return $retval;

src/View/ThemeResourceLoader.php

@@ -9,6 +9,7 @@
 use SilverStripe\Core\Manifest\ModuleLoader;
 use SilverStripe\Core\Manifest\ModuleResourceLoader;
 use SilverStripe\Core\Path;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Handles finding templates from a stack of template manifest objects.
@@ -182,9 +183,11 @@ public function getPath($identifier)
      * @return string Absolute path to resolved template file, or null if not resolved.
      * File location will be in the format themes/<theme>/templates/<directories>/<type>/<basename>.ss
      * Note that type (e.g. 'Layout') is not the root level directory under 'templates'.
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it.
      */
     public function findTemplate($template, $themes = null)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be removed without equivalent functionality to replace it.');
         if ($themes === null) {
             $themes = SSViewer::get_themes();
         }

src/View/ViewableData.php

@@ -426,9 +426,11 @@ public function castingHelper($field)
      *
      * @param string $field
      * @return string
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it.
      */
     public function castingClass($field)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be removed without equivalent functionality to replace it.');
         // Strip arguments
         $spec = $this->castingHelper($field);
         return trim(strtok($spec ?? '', '(') ?? '');
@@ -439,9 +441,11 @@ public function castingClass($field)
      *
      * @param string $field
      * @return string 'xml'|'raw'
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it.
      */
     public function escapeTypeForField($field)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be removed without equivalent functionality to replace it.');
         $class = $this->castingClass($field) ?: $this->config()->get('default_cast');
 
         /** @var DBField $type */
@@ -488,9 +492,11 @@ public function renderWith($template, $customFields = null)
      * @param string $fieldName Name of field
      * @param array $arguments List of optional arguments given
      * @return string
+     * @deprecated 5.4.0 Will be made private
      */
     protected function objCacheName($fieldName, $arguments)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0', 'Will be made private');
         return $arguments
             ? $fieldName . ":" . var_export($arguments, true)
             : $fieldName;
@@ -546,6 +552,9 @@ protected function objCacheClear()
      */
     public function obj($fieldName, $arguments = [], $cache = false, $cacheName = null)
     {
+        if ($cacheName !== null) {
+            Deprecation::noticeWithNoReplacment('5.4.0', 'The $cacheName parameter has been deprecated and will be removed');
+        }
         if (!$cacheName && $cache) {
             $cacheName = $this->objCacheName($fieldName, $arguments);
         }
@@ -588,9 +597,11 @@ public function obj($fieldName, $arguments = [], $cache = false, $cacheName = nu
      * @param array $arguments
      * @param string $identifier an optional custom cache identifier
      * @return Object|DBField
+     * @deprecated 5.4.0 use obj() instead
      */
     public function cachedCall($fieldName, $arguments = [], $identifier = null)
     {
+        Deprecation::notice('5.4.0', 'Use obj() instead');
         return $this->obj($fieldName, $arguments, true, $identifier);
     }
 
@@ -617,9 +628,11 @@ public function hasValue($field, $arguments = [], $cache = true)
      * @param array $arguments
      * @param bool $cache
      * @return string
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it
      */
     public function XML_val($field, $arguments = [], $cache = false)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0');
         $result = $this->obj($field, $arguments, $cache);
         // Might contain additional formatting over ->XML(). E.g. parse shortcodes, nl2br()
         return $result->forTemplate();
@@ -630,9 +643,11 @@ public function XML_val($field, $arguments = [], $cache = false)
      *
      * @param array $fields an array of field names
      * @return array
+     * @deprecated 5.4.0 Will be removed without equivalent functionality to replace it
      */
     public function getXMLValues($fields)
     {
+        Deprecation::noticeWithNoReplacment('5.4.0');
         $result = [];
 
         foreach ($fields as $field) {