restruct/silverstripe-shortcodable

Provides a simple button to insert Shortcodes into the HTMLEditorField + an API for developers to define shortcodes

4.0.11 2024-05-15 12:44 UTC

Requires

• restruct/silverstripe-simpler: ^0.1
• silverstripe/framework: ^4
• silverstripe/vendor-plugin: ^1.0

Replaces

• sheadawson/silverstripe-shortcodable: *

BSD-3-Clause

• Restruct
• Shea Dawson

• silverstripe
• shortcode

README

Adds a button to HTMLEditorField for CMS users to insert Shortcodes in page content.
Shortcodes can optionally be represented in TinyMCE with a placeholder image.

This module is a partial-to-largely rewrite of sheadawson/silverstripe-shortcodable.
It depends on Silverstripe Simpler for some non-react UI functionalities (mainly the modal dialog).

Configuration

Register DataObjects or classes as shortcodable via Yaml config:

---
name: my_shortcodables
Only:
    classexists: Shortcodable\Shortcodable
---
Shortcodable\Shortcodable:
    shortcodable_classes:
        - My\Namespaced\Shortcodes\CurrentYearShortcode
        - My\Namespaced\Shortcodes\SomeOtherShortcode
        - ...
---

Required methods on shortcodable objects/classes

Implement these methods on your shortcodable classes (may also be added via an Extension):

(Required) shortcode parser callback:
public static function parse_shortcode(...)
OR:
public function MyCustomParser(...) combined with:
private static $shortcode_callback = 'MyCustomParser'

Parser method arguments: (see shortcode documentation)
($attrs, $content=null, $parser=null, $shortcode, $info)

NOTE: the parser method gets called on a singleton object instance.
(So there's no $this->ID or $this->owner->ID etc.)

Optional:

• private static $shortcode (optional, else short ClassName will be used as [ClassName])
• getShortcodeLabel() (optional nice description for in dropdown, singular_name() or else ClassName.Shortname will be used as fallback)
• getShortcodeFields() (optional, attribute-formfields for popup)
• getShortcodableRecords() (optional, if applied to DataObject)
• getShortcodePlaceholder($attributes) (optional)

Wrapping (optional): In this module, $shortcodable_is_block and $disable_wrapper have been replaced with $shortcode_close_parent:

• private static $shortcode_is_block (optional, set to true if your shortcode output is a block-type html element)

If you set $shortcode_close_parent to true, the parent node will be closed before your shortcode output and reopened after.
Eg <p>Some [shortcode] content</p> would become <p>Some </p>[shortcode]<p> content</p>;

Shortcode placeholder images

To display a nice image instead of the raw shortcode in the CMS editor, implement a getShortcodePlaceHolder method on your shortcodable object:

/**
* Redirect to an image OR return image data directly to be displayed as shortcode placeholder in the editor
* (getShortcodePlaceHolder gets loaded as/from the 'src' attribute of an <img> tag)
*
* @param array $attributes attribute key-value pairs of the shortcode
* @return \SilverStripe\Control\HTTPResponse
**/
public function getShortcodePlaceHolder($attributes)
{
    // Flavour one: redirect to image URL (for this example we're also including the attributes array in the URL)
    Controller::curr()->redirect('https://www.silverstripe.org/apple-touch-icon-76x76.png?attrs='.json_encode($attributes));

    // Flavour two: output image/svg data directly (any bitmap but may also be SVG)
    // Hint: process attributes eg to show a set of image thumbnails wrapped in an SVG as gallery-placeholder
    $response = Controller::curr()->getResponse();
    $response->addHeader('Content-Type','image/svg+xml');
    $response->addHeader('Vary','Accept-Encoding');
    $response->setBody('<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-code-square" viewBox="0 0 16 16">
      <path d="M14 1a1 1 0 0 1 1 1v12a1 1 0 0 1-1 1H2a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1h12zM2 0a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V2a2 2 0 0 0-2-2H2z"/>
      <path d="M6.854 4.646a.5.5 0 0 1 0 .708L4.207 8l2.647 2.646a.5.5 0 0 1-.708.708l-3-3a.5.5 0 0 1 0-.708l3-3a.5.5 0 0 1 .708 0zm2.292 0a.5.5 0 0 0 0 .708L11.793 8l-2.647 2.646a.5.5 0 0 0 .708.708l3-3a.5.5 0 0 0 0-.708l-3-3a.5.5 0 0 0-.708 0z"/>
    </svg>');
    $response->output();
}

Status

• TinyMCE button/plugin
• Shortcode form in popup dialog
• Custom/configurable shortcode independent of class name
• Custom/configurable shortcode parser callback methods
• Inserting new & editing existing shortcode (+undo)
• Re-implement DataObjects as shortcodable (incl. getShortcodableRecords etc)
• Re-implement placeholders
• Check/re-implement(?) BOM fix and in ShortcodeController
• Check/re-implement(?) P/DIV wrapper fix
• Check/restore functionality for Uploadfields to load existing value
• Check/implement(?) wrapping shortcodes

Refs:

• General shortcode documentation
• Shortcodable V2 documentation