add new filter for attributes on link anchor elements in wporg-developer theme

[pbiron]

DevHub_Formatting::make_doclink_clickable() should have a filter to add attributes, e.g., class and/or title, to the anchor element that is generated.

For those of us who use child themes of wporg-developer in producing documentation for our plugins/themes, having such a filter would make it easier to make it clear to our users which links in our documentation are internal and which are external.

I currently use jQuery to add class and title attributes to such external links (and bit of CSS for adding a decoration to the link based on the class attribute, see below) but it has always felt like a kludge to do it that way.

[pbiron]

here's a screenshot of the output I'd produce by hooking into the proposed filter. Notice the WP logo and "External link to wordpress.org" tool-tip.

[pbiron]

Here's how I would use the proposed filter to produce the screenshot I just attached to this ticket.

Suppose I have the following DocBlock:

<?php
/**
 * Tries to convert an attachment URL for intermediate sized images into a post ID.
 *
 * This function is intended to be hooked into {@link https://developer.wordpress.org/reference/hooks/attachment_url_to_postid/ attachment_url_to_postid}
 * to overcome the fact that {@link https://developer.wordpress.org/reference/functions/attachment_url_to_postid/ attachment_url_to_postid()}
 * will only find an attachment ID when the `$url` is for the full-sized image.
 *
 * @param int $post_id The found post ID.
 * @param string $url The URL to resolve.
 * @return int The found post ID, or 0 on failure.
 */
function shc_attachment_url_to_postid_filter( $post_id, $url ) {
...
}

I'd hook the following function into the proposed filter

<?php
add_filter( 'devhub-format-link-attributes', 'shc_link_attributes', 10, 2 );
function shc_link_attributes( $attrs, $url ) {
        $host = parse_url( $url, PHP_URL_HOST );
        switch ( $host ) {
                case 'developer.wordpress.org':
                case 'codex.wordpress.org':
                case 'make.wordpress.org':
                        $attrs['class'] = 'external wporg';
                        $attrs['title'] = 'External link to wordpress.org';

                        break;

                case 'php.net':
                        $attrs['class'] = 'external php';
                        $attrs['title'] = 'External link to php.net';

                        break;

                case 'w3.org':
                case 'www.w3.org':
                        $attrs['class'] = 'external w3c';
                        $attrs['title'] = 'External link to w3.org';

                        break;
        }

        return $attrs;
}

and use the following snippet of CSS:

a.external::after {
        background-origin: content-box;
        background-position: center;
        background-repeat: no-repeat;
        background-size: 1em 1em;
        content: '';
        display: inline-block;
        height: 1em;
        margin: 0 0 0 5px;
        width: 1em;
}

a.external.wporg::after {
        background-image: url( images/wordpress-logo.svg );
}
a.external.php::after {
        background-image: url( images/php-logo.svg );
}
a.external.w3c::after {
        background-image: url( images/w3c-logo.svg );
}

to produce the WP logo "decoration" of the link.

[pbiron]

As I said, I currently use jQuery (and the CSS above) to produce the same output. But it seems kludgy to do it that way, not least because the WP logo doesn't appear until after the rest of the page has rendered.

[obenland]

How about making $link filterable in the callback function. That way you could modify the output with a little regex and it would require us to introduce a new utility function just for that purpose.

[pbiron]

Replying to obenland:

How about making $link filterable in the callback function. That way you could modify the output with a little regex and it would require us to introduce a new utility function just for that purpose.

Did you mean to say "...and it would not require us to introduce..."?

That would work, however, I'm not a big fan of filters that operate on HTML strings because functions that hook into such filters need to use regexes to "parse" the HTML string which is not reliable.

And the reason my patch introduces the generate_link() utility function is actually that I find the existing code pretty "unpoetic" by having 6 different places where an anchor tag is generated (5 of which use string concatenation, 1 of which uses sprintf() and only 3 of which esc_url() on the URL).

[pbiron]

Replying to pbiron:

And the reason my patch introduces the generate_link() utility function is actually that I find the existing code pretty "unpoetic" by having 6 different places where an anchor tag is generated (5 of which use string concatenation, 1 of which uses sprintf() and only 3 of which esc_url() on the URL).

That is, I think generate_link() would be good to have whether my proposal for an attribute filter is accepted or not.

[coffee2code]

In 7769:

developer.wordpress.org: Centralize creation of doclink link markup into new generate_link().

Also adds 'devhub-format-link-attributes' filter for adding/editing attributes used for a link.

Props pbiron.
Fixes #3649.

[pbiron]

Thank you!!!