Merge pull request #9281 from creative-commoners/pulls/4/textfield-tip-ui

NEW: Add support for Tip UI in TextField

src/Forms/TextField.php

@@ -7,7 +7,7 @@ use SilverStripe\Dev\Deprecation;
 /**
  * Text input field.
  */
-class TextField extends FormField
+class TextField extends FormField implements TippableFieldInterface
 {
     /**
      * @var int
@@ -16,6 +16,11 @@ class TextField extends FormField
 
     protected $schemaDataType = FormField::SCHEMA_DATA_TYPE_TEXT;
 
+    /**
+     * @var Tip|null A tip to render beside the input
+     */
+    private $tip;
+
     /**
      * Returns an input field.
      *
@@ -59,6 +64,29 @@ class TextField extends FormField
         return $this->maxLength;
     }
 
+    /**
+     * @return Tip|null
+     */
+    public function getTip(): ?Tip
+    {
+        return $this->tip;
+    }
+
+    /**
+     * Applies a Tip to the field, which shows a popover on the right side of
+     * the input to place additional context or explanation of the field's
+     * purpose in. Currently only supported in React-based forms.
+     *
+     * @param Tip|null $tip The Tip to apply, or null to remove an existing one
+     * @return $this
+     */
+    public function setTip(?Tip $tip = null): self
+    {
+        $this->tip = $tip;
+
+        return $this;
+    }
+
     /**
      * @return array
      */
@@ -83,6 +111,11 @@ class TextField extends FormField
     {
         $data = parent::getSchemaDataDefaults();
         $data['data']['maxlength'] =  $this->getMaxLength();
+
+        if ($this->getTip() instanceof Tip) {
+            $data['tip'] = $this->getTip()->getTipSchema();
+        }
+
         return $data;
     }
 

src/Forms/Tip.php

@@ -0,0 +1,134 @@
+<?php
+declare(strict_types=1);
+
+namespace SilverStripe\Forms;
+
+use InvalidArgumentException;
+
+/**
+ * Represents a Tip which can be rendered alongside a form field in the front-end.
+ * See the Tip component in the silverstripe/admin module.
+ */
+class Tip
+{
+    /**
+     * These map to levels in the front-end Tip component
+     */
+    public const IMPORTANCE_LEVELS = [
+        'NORMAL' => 'normal',
+        'HIGH' => 'high',
+    ];
+
+    private const DEFAULT_ICON = 'lamp';
+
+    private const DEFAULT_IMPORTANCE_LEVEL = self::IMPORTANCE_LEVELS['NORMAL'];
+
+    /**
+     * @var string The icon that should be used on the Tip button
+     */
+    private $icon;
+
+    /**
+     * @var string How important the tip is (normal or high). Informs the color and description.
+     */
+    private $importance_level;
+
+    /**
+     * @var string The message to display in the tip
+     */
+    private $message;
+
+    /**
+     * @param string $message The message to display in the tip
+     * @param string $importance_level How important the tip is (normal or high). Informs the color and description.
+     * @param string $icon The icon that should be used on the Tip button
+     * @throws InvalidArgumentException
+     */
+    public function __construct(
+        string $message,
+        string $importance_level = self::DEFAULT_IMPORTANCE_LEVEL,
+        string $icon = self::DEFAULT_ICON
+    ) {
+        $this->setMessage($message);
+        $this->setIcon($icon);
+        $this->setImportanceLevel($importance_level);
+    }
+
+    /**
+     * Outputs props to be passed to the front-end Tip component.
+     *
+     * @return array
+     */
+    public function getTipSchema(): array
+    {
+        return [
+            'content' => $this->getMessage(),
+            'icon' => $this->getIcon(),
+            'importance' => $this->getImportanceLevel(),
+        ];
+    }
+
+    /**
+     * @return string
+     */
+    public function getImportanceLevel(): string
+    {
+        return $this->importance_level;
+    }
+
+    /**
+     * @param string $importance_level
+     * @return Tip
+     * @throws InvalidArgumentException
+     */
+    public function setImportanceLevel(string $importance_level): self
+    {
+        if (!in_array($importance_level, self::IMPORTANCE_LEVELS)) {
+            throw new InvalidArgumentException(
+                'Provided importance level must be defined in Tip::IMPORTANCE_LEVELS'
+            );
+        }
+
+        $this->importance_level = $importance_level;
+
+        return $this;
+    }
+
+    /**
+     * @return string
+     */
+    public function getIcon(): string
+    {
+        return $this->icon;
+    }
+
+    /**
+     * @param string $icon
+     * @return Tip
+     */
+    public function setIcon(string $icon): self
+    {
+        $this->icon = $icon;
+
+        return $this;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage(): string
+    {
+        return $this->message;
+    }
+
+    /**
+     * @param string $message
+     * @return Tip
+     */
+    public function setMessage(string $message): self
+    {
+        $this->message = $message;
+
+        return $this;
+    }
+}

src/Forms/TippableFieldInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace SilverStripe\Forms;
+
+/**
+ * Declares that a form field has the ability to accept and render Tips.
+ */
+interface TippableFieldInterface
+{
+    public function getTip(): ?Tip;
+
+    public function setTip(Tip $tip);
+}

tests/php/Forms/TextFieldTest.php

@@ -5,6 +5,7 @@ namespace SilverStripe\Forms\Tests;
 use SilverStripe\Dev\SapphireTest;
 use SilverStripe\Forms\TextField;
 use SilverStripe\Forms\RequiredFields;
+use SilverStripe\Forms\Tip;
 
 class TextFieldTest extends SapphireTest
 {
@@ -32,4 +33,16 @@ class TextFieldTest extends SapphireTest
         $result = $textField->validate(new RequiredFields());
         $this->assertTrue($result);
     }
+
+    /**
+     * Ensures that when a Tip is applied to the field, it outputs it in the schema
+     */
+    public function testTipIsIncludedInSchema()
+    {
+        $textField = new TextField('TestField');
+        $this->assertArrayNotHasKey('tip', $textField->getSchemaDataDefaults());
+
+        $textField->setTip(new Tip('TestTip'));
+        $this->assertArrayHasKey('tip', $textField->getSchemaDataDefaults());
+    }
 }

tests/php/Forms/TipTest.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace SilverStripe\Forms\Tests;
+
+use InvalidArgumentException;
+use SilverStripe\Dev\SapphireTest;
+use SilverStripe\Forms\Tip;
+
+class TipTest extends SapphireTest
+{
+    /**
+     * Ensure the correct defaults are output in the schema
+     */
+    public function testGeneratesAccurateDefaultSchema()
+    {
+        $tip = new Tip('message');
+
+        $schema = $tip->getTipSchema();
+
+        $this->assertEquals(
+            [
+                'content' => 'message',
+                'icon' => 'lamp',
+                'importance' => 'normal',
+            ],
+            $schema
+        );
+    }
+
+    /**
+     * Ensure custom settings are output in the schema
+     */
+    public function testGeneratesAccurateCustomSchema()
+    {
+        $tip = new Tip(
+            'message',
+            Tip::IMPORTANCE_LEVELS['HIGH'],
+            'page'
+        );
+
+        $schema = $tip->getTipSchema();
+
+        $this->assertEquals(
+            [
+                'content' => 'message',
+                'icon' => 'page',
+                'importance' => 'high',
+            ],
+            $schema
+        );
+    }
+
+    /**
+     * Ensure passing an invalid importance level to the constructor fails
+     *
+     * @expectedException InvalidArgumentException
+     * @expectedExceptionMessage Provided importance level must be defined in Tip::IMPORTANCE_LEVELS
+     */
+    public function testInvalidImportanceLevelInConstructorCausesException()
+    {
+        $tip = new Tip('message', 'arbitrary-importance');
+    }
+
+    /**
+     * Ensure setting an invalid importance level fails
+     *
+     * @expectedException InvalidArgumentException
+     * @expectedExceptionMessage Provided importance level must be defined in Tip::IMPORTANCE_LEVELS
+     */
+    public function testInvalidImportanceLevelInSetterCausesException()
+    {
+        $tip = new Tip('message');
+
+        $tip->setImportanceLevel('arbitrary-importance');
+    }
+}