NEW Add ability to define image size preset for the TinyMCE editor. (#9276)

* NEW Add ability to define image size preset for the TinyMCE editor.
* DOC Explain how to define image size pre-sets

_config/html.yml

@@ -13,3 +13,14 @@ SilverStripe\Core\Injector\Injector:
     class: SilverStripe\Forms\HTMLEditor\TinyMCECombinedGenerator
     properties:
       AssetHandler: '%$SilverStripe\Assets\Storage\GeneratedAssetHandler'
+
+SilverStripe\Forms\HTMLEditor\TinyMCEConfig:
+  image_size_presets:
+    - width: 600,
+      i18n: SilverStripe\Forms\HTMLEditor\TinyMCEConfig.BEST_FIT
+      text: Best fit
+      name: bestfit
+      default: true
+    - i18n: SilverStripe\Forms\HTMLEditor\TinyMCEConfig.ORIGINAL
+      text: Original
+      name: originalsize

docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md

@@ -190,6 +190,53 @@ We use [shortcodes](/developer_guides/extending/shortcodes) to store information
 [ShortcodeParser](api:SilverStripe\View\Parsers\ShortcodeParser) API post-processes the HTML content on rendering, and replaces the shortcodes accordingly. It also 
 takes care of care of placing the shortcode replacements relative to its surrounding markup (e.g. left/right alignment).
 
+### Image size pre-sets
+SilverStripe will suggest pre-set image size in the HTMLEditor. Editors can quickly switch between the pre-set size when interacting with images in the HTMLEditorField.
+
+The default values are "Best fit" (600 pixels width) and original size. Developers can customise the pre-set sizes by altering their HTMLEditorConfig.
+
+You can alter the defaults for all HTMLEditor in your YML configuration.
+
+```yaml
+SilverStripe\Forms\HTMLEditor\TinyMCEConfig:
+  image_size_presets:
+    - name: widesize
+      i18n: SilverStripe\Forms\HTMLEditor\TinyMCEConfig.WIDE_SIZE
+      text: Wide size
+      width: 900
+```
+
+You can edit the image size pre-sets for an individual configuration with this code snippet.
+
+```php
+<?php
+use SilverStripe\Forms\HTMLEditor\HtmlEditorConfig;
+use SilverStripe\Forms\HTMLEditor\TinyMCEConfig;
+
+HtmlEditorConfig::get('cms')->setOption('image_size_presets', [
+    [
+        'width' => 300,
+        'text' => 'Small fit',
+        'name' => 'smallfit',
+        'default' => true
+    ],
+    [
+        'width' => 600,
+        'i18n' =>  TinyMCEConfig::class . '.BEST_FIT',
+        'text' => 'Best fit',
+        'name' => 'bestfit'
+    ],
+    [
+        'i18n' =>  TinyMCEConfig::class . '.ORIGINAL_SIZE',
+        'text' => 'Original size',
+        'name' => 'originalsize'
+    ]
+]);
+```
+
+
+
+
 ## oEmbed: Embedding media through external services
 
 The ["oEmbed" standard](http://www.oembed.com/) is implemented by many media services around the web, allowing easy 

src/Forms/HTMLEditor/TinyMCEConfig.php

@@ -13,6 +13,7 @@ use SilverStripe\Core\Manifest\ModuleResource;
 use SilverStripe\Core\Manifest\ModuleResourceLoader;
 use SilverStripe\Dev\Deprecation;
 use SilverStripe\i18n\i18n;
+use SilverStripe\i18n\i18nEntityProvider;
 use SilverStripe\View\Requirements;
 use SilverStripe\View\SSViewer;
 use SilverStripe\View\ThemeResourceLoader;
@@ -20,7 +21,7 @@ use SilverStripe\View\ThemeResourceLoader;
 /**
  * Default configuration for HtmlEditor specific to tinymce
  */
-class TinyMCEConfig extends HTMLEditorConfig
+class TinyMCEConfig extends HTMLEditorConfig implements i18nEntityProvider
 {
     /**
      * @config
@@ -209,6 +210,19 @@ class TinyMCEConfig extends HTMLEditorConfig
      */
     protected $contentCSS = null;
 
+
+    /**
+     * List of image size preset that will appear when you select an image. Each preset can have the following:
+     * * `name` to store an internal name for the preset (required)
+     * * `i18n` to store a translation key (e.g.: `SilverStripe\Forms\HTMLEditor\TinyMCEConfig.BESTFIT`)
+     * * `text` that will appear in the button (should be the default English translation)
+     * * `width` which will define the horizontal size of the preset. If not provided, the preset will match the
+     *   original size of the image.
+     * @var array[]
+     * @config
+     */
+    private static $image_size_presets = [ ];
+
     /**
      * TinyMCE JS settings
      *
@@ -662,10 +676,39 @@ class TinyMCEConfig extends HTMLEditorConfig
         }
         $settings['theme_url'] = $theme;
 
+        $this->initImageSizePresets($settings);
+
         // Send back
         return $settings;
     }
 
+    /**
+     * Initialise the image preset on the settings array. This is a custom configuration option that asset-admin reads
+     * to provide some preset image sizes.
+     * @param array $settings
+     */
+    private function initImageSizePresets(array &$settings): void
+    {
+        if (empty($settings['image_size_presets'])) {
+            $settings['image_size_presets'] = self::config()->get('image_size_presets');
+        }
+
+        foreach ($settings['image_size_presets'] as &$preset) {
+            if (isset($preset['i18n'])) {
+                $preset['text'] = _t(
+                    $preset['i18n'],
+                    isset($preset['text']) ? $preset['text'] : ''
+                );
+            } elseif (empty($preset['text']) && isset($preset['width'])) {
+                $preset['text'] = _t(
+                    self::class . '.PIXEL_WIDTH',
+                    '{width} pixels',
+                    $preset
+                );
+            }
+        }
+    }
+
     /**
      * Get location of all editor.css files.
      * All resource specifiers are resolved to urls.
@@ -860,4 +903,19 @@ class TinyMCEConfig extends HTMLEditorConfig
         $this->setOption('upload_folder_id', $folderID);
         return $this;
     }
+
+    public function provideI18nEntities()
+    {
+        $entities = [
+            self::class . '.PIXEL_WIDTH' => '{width} pixels',
+        ];
+        foreach (self::config()->get('image_size_presets') as $preset) {
+            if (empty($preset['i18n']) || empty($preset['text'])) {
+                continue;
+            }
+            $entities[$preset['i18n']] = $preset['text'];
+        }
+
+        return $entities;
+    }
 }

tests/php/Forms/HTMLEditor/TinyMCEConfigTest.php

@@ -68,4 +68,26 @@ class TinyMCEConfigTest extends SapphireTest
             $config->getContentCSS()
         );
     }
+
+    public function testProvideI18nEntities()
+    {
+        TinyMCEConfig::config()->set('image_size_presets', [
+            ['i18n' => TinyMCEConfig::class . '.TEST', 'text' => 'Foo bar'],
+            ['text' => 'No translation key'],
+            ['i18n' => TinyMCEConfig::class . '.NO_TRANSLATION_TEXT'],
+            ['i18n' => TinyMCEConfig::class . '.TEST_TWO', 'text' => 'Bar foo'],
+        ]);
+
+        $config = TinyMCEConfig::create();
+        $translations = $config->provideI18nEntities();
+
+        $this->assertEquals(
+            3,
+            sizeof($translations),
+            'Only two presets have valid translation + the generic PIXEL_WIDTH one'
+        );
+        $this->assertEquals('Foo bar', $translations[TinyMCEConfig::class . '.TEST']);
+        $this->assertEquals('Bar foo', $translations[TinyMCEConfig::class . '.TEST_TWO']);
+        $this->assertEquals('{width} pixels', $translations[TinyMCEConfig::class . '.PIXEL_WIDTH']);
+    }
 }