WordPress.org

Making WordPress.org


Ignore:
Timestamp:
01/29/2016 07:48:45 PM (6 years ago)
Author:
drewapicture
Message:

DevHub: Introduce a new template tag, get_private_access_message(), which generates a message for standalone functions or hooks marked with a private @access tag in their respective Docblocks.

If the Handbook plugin is available, more specifically if the WPorg_Handbook_Callout_Boxes class is available, the message markup is generated as an 'alert'-type callout box. Otherwise, fall-back markup and styles are applied to the message.

If an alternative function is referenced via an @see tag in the function or hook DocBlock, make a good-faith effort to try to link to the reference page for that element as an alternative within the access message text.

See #1498.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

    r2290 r2431  
    13501350        return get_post_field( $field, $explanation, $context );
    13511351    }
     1352
     1353    /**
     1354     * Generates a private access message for a private element.
     1355     *
     1356     * @param int|WP_Post $post Optional. Post object or ID. Default global `$post`.
     1357     * @return string Private access message if the given reference is considered "private".
     1358     */
     1359    function get_private_access_message( $post = null ) {
     1360        if ( ! $post = get_post( $post ) ) {
     1361            return '';
     1362        }
     1363
     1364        // Currently only handling private access messages for functions and hooks.
     1365        if ( ! in_array( get_post_type( $post ), array( 'wp-parser-function', 'wp-parser-hook' ) ) ) {
     1366            return '';
     1367        }
     1368
     1369        $tags        = get_post_meta( $post->ID, '_wp-parser_tags', true );
     1370        $access_tags = wp_filter_object_list( $tags, array(
     1371            'name'    => 'access',
     1372            'content' => 'private'
     1373        ) );
     1374
     1375        // Bail if it isn't private.
     1376        if ( empty( $access_tags ) ) {
     1377            return '';
     1378        }
     1379
     1380        $referral = array_shift( wp_filter_object_list( $tags, array( 'name' => 'see' ) ) );
     1381
     1382        if ( ! empty( $referral['refers'] ) ) {
     1383            $refers = sanitize_text_field( $referral['refers'] );
     1384
     1385            if ( ! empty( $refers ) ) {
     1386                /* translators: 1: Linked internal element name */
     1387                $alternative_string = sprintf( __( ' Use %s instead.', 'wporg' ), \DevHub_Formatting::link_internal_element( $refers ) );
     1388            }
     1389        } else {
     1390            $alternative_string = '';
     1391        }
     1392
     1393        /* translators: 1: String for alternative function (if one exists) */
     1394        $contents = sprintf( __( 'This function’s access is marked private. This means it is not intended for use by plugin or theme developers, only in other core functions. It is listed here for completeness.%s', 'wporg' ),
     1395                $alternative_string
     1396        );
     1397
     1398        // Use the 'alert' callout box if it's available. Otherwise, fall back to a theme-supported div class.
     1399        if ( class_exists( 'WPorg_Handbook_Callout_Boxes' ) ) {
     1400            $callout = new \WPorg_Handbook_Callout_Boxes();
     1401            $message = $callout->alert_shortcode( array(), $contents );
     1402        } else {
     1403            $message  = '<div class="private-access">';
     1404            $message .= apply_filters( 'the_content', $contents );
     1405            $message .= '</div>';
     1406        }
     1407
     1408        return $message;
     1409    }
    13521410}
Note: See TracChangeset for help on using the changeset viewer.