WordPress.org

Making WordPress.org

Opened 14 months ago

Closed 9 months ago

Last modified 9 months ago

#3649 closed enhancement (fixed)

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

Reported by: pbiron Owned by: coffee2code
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch has-screenshots
Cc:

Description

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.

Attachments (2)

3649.patch.diff (4.7 KB) - added by pbiron 14 months ago.
link-attributes-filter-screenshot.png (46.6 KB) - added by pbiron 14 months ago.
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.

Download all attachments as: .zip

Change History (9)

@pbiron
14 months ago

@pbiron
14 months ago

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.

#1 @pbiron
14 months ago

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.

#2 @pbiron
14 months ago

  • Keywords has-patch has-screenshots added

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.

#3 follow-up: @obenland
14 months ago

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.

#4 in reply to: ↑ 3 ; follow-up: @pbiron
14 months ago

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).

#5 in reply to: ↑ 4 @pbiron
14 months ago

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.

#6 @coffee2code
9 months ago

  • Owner set to coffee2code
  • Resolution set to fixed
  • Status changed from new to closed

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.

#7 @pbiron
9 months ago

Thank you!!!

Note: See TracTickets for help on using tickets.