How to create custom block parsing

[shoaibsharif]

Hi, I would like to know how I create an embed using custom notation. i.e. in dev.to markdown editor if we write:

{% embed https://codepen.io/shoaibsharif/pen/jOBvbOj %}

It will spit an iframe. I would like to know how I can achieve that in commonmark. I tried to look at the documentation but unfortunately it didn't help me much.

[colinodell]

Version 2.3 (not yet released) will have an EmbedExtension with a very simple syntax:

Just place the link on its own line:

https://codepen.io/shoaibsharif/pen/jOBvbOj

^ Like that

2.3.0 probably won't be released for a few weeks, so if you need this sooner (or would like to use the syntax you proposed) then you'll want to implement this as a custom block parser that looks for {% embed followed by a URL and then %}. The code might look something like this (untested!):

final class EmbedParser extends AbstractBlockContinueParser
{
    /** @psalm-readonly */
    private Embed $block;

    public function __construct(string $url)
    {
        $this->block = new Embed($url);
    }

    public function getBlock(): Embed
    {
        return $this->block;
    }

    public function tryContinue(Cursor $cursor, BlockContinueParserInterface $activeBlockParser): ?BlockContinue
    {
        return BlockContinue::none();
    }

    public static function blockStartParser(): BlockStartParserInterface
    {
        return new class () implements BlockStartParserInterface {
            /** @psalm-readonly-allow-private-mutation */
            private ConfigurationInterface $config;

            public function tryStart(Cursor $cursor, MarkdownParserStateInterface $parserState): ?BlockStart
            {
                if ($cursor->isIndented()) {
                    return BlockStart::none();
                }

                $cursor->advanceToNextNonSpaceOrTab();

                // The line must start with '{% embed'
                if ($cursor->match('/^{% +embed +/') === null) {
                    return BlockStart::none();
                }

                // There must be an absolute URL next
                if (($url = LinkParserHelper::parseLinkDestination($cursor)) === null) {
                    return BlockStart::none();
                }

                // The rest of the line must contain whitespace then '%}'
                $cursor->advanceToNextNonSpaceOrTab();
                if ($cursor->match('/^%} *$/') === null) {
                    return BlockStart::none();
                }

                return BlockStart::of(new EmbedParser($url))->at($cursor);
            }
        };
    }
}

(This example combines the block start parser and block continue parser into one. You can use separate classes if you prefer.)

I recommend looking at these classes for inspiration:

• https://github.com/thephpleague/commonmark/blob/main/src/Extension/Embed/EmbedStartParser.php
• https://github.com/thephpleague/commonmark/blob/main/src/Extension/Embed/EmbedParser.php
• https://github.com/thephpleague/commonmark/blob/main/src/Extension/TableOfContents/TableOfContentsPlaceholderParser.php

[jv2222]

@colinodell First, thanks for the software of course it is awesome!

One note, I think an end-to-end example of a custom block parser has always been needed in the docs.

I've been migrating a Laravel app from 5.6 -> 9 (back in the day they created a custom block parser). As I've been moving through Laravel versions, I've also been migrating the custom block parser (up through different versions of league/commonmark).

I must confess at 2.1 I have been stumped for a few weeks now as I need to re-build it from scratch since the 1.x way no longer exists. An end-to-end system example would have been supremely helpful!

The above is very helpful and I will start approaching like this.

All that said, your EmbedExtension might do the job for me! Will it somehow be able to handle custom renders like this?

class EmbeddedRenderer implements BlockRendererInterface
{
    public function render(AbstractBlock $block, ElementRendererInterface $htmlRenderer)
    {
        // Setup an appropriate embeddable object
        $embeddable = \App\Extensions\Embeddable\EmbeddableFactory::fromLink($block->data['url']);

        if ($embeddable) {

            // Find the link we should use
            $embedLink = $embeddable->getEmbedLink();

            if ($embeddable instanceof \App\Extensions\Embeddable\EmbeddableLink) {
                $link = new HtmlElement('a', [
                    'href' => $embeddable->getLink(),
                    'target' => '_blank',
                    'class' => 'presentation',
                ], 'View in new browser tab');

                $coaching = new HtmlElement('div', [
                    'class' => 'coaching-message',
                ], "Details of the user's work within the embedded page are not available in the Coaching View.");

                // Setup the embed
                $frame = new HtmlElement('iframe', [
                    'src' => $embedLink,
                    'frameborder' => '0',
                ]);

                $div = new HtmlElement('div', [
                    'class' => 'embedded-link',
                ],
                [
                    $frame,
                    $coaching,
                    $link,
                ]);

                // We need there to always be a line break before this element, otherwise the cursor
                // won't be able to move before it in edit mode
                return '<br/>'.((string) $div);
            } else {
                return new HtmlElement('iframe', [
                    'src' => $embedLink,
                    'frameborder' => '0',
                    'class' => 'ql-video',
                ]);
            }
        }
    }
}