Changeset 2431

Timestamp:

01/29/2016 07:48:45 PM (9 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.

Location:

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer

Files:

• content-reference.php (modified) (1 diff)
• inc/template-tags.php (modified) (1 diff)
• scss/main.scss (modified) (1 diff)
• stylesheets/main.css (modified) (1 diff)

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/content-reference.php

@@ -4 +4 @@
 
     <?php echo get_deprecated(); ?>
+
+    <?php echo get_private_access_message(); ?>
 
     <h1><a href="<?php the_permalink() ?>"><?php echo get_signature(); ?></a></h1>

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

@@ -1350 +1350 @@
         return get_post_field( $field, $explanation, $context );
     }
+
+    /**
+     * Generates a private access message for a private element.
+     *
+     * @param int|WP_Post $post Optional. Post object or ID. Default global `$post`.
+     * @return string Private access message if the given reference is considered "private".
+     */
+    function get_private_access_message( $post = null ) {
+        if ( ! $post = get_post( $post ) ) {
+            return '';
+        }
+
+        // Currently only handling private access messages for functions and hooks.
+        if ( ! in_array( get_post_type( $post ), array( 'wp-parser-function', 'wp-parser-hook' ) ) ) {
+            return '';
+        }
+
+        $tags        = get_post_meta( $post->ID, '_wp-parser_tags', true );
+        $access_tags = wp_filter_object_list( $tags, array(
+            'name'    => 'access',
+            'content' => 'private'
+        ) );
+
+        // Bail if it isn't private.
+        if ( empty( $access_tags ) ) {
+            return '';
+        }
+
+        $referral = array_shift( wp_filter_object_list( $tags, array( 'name' => 'see' ) ) );
+
+        if ( ! empty( $referral['refers'] ) ) {
+            $refers = sanitize_text_field( $referral['refers'] );
+
+            if ( ! empty( $refers ) ) {
+                /* translators: 1: Linked internal element name */
+                $alternative_string = sprintf( __( ' Use %s instead.', 'wporg' ), \DevHub_Formatting::link_internal_element( $refers ) );
+            }
+        } else {
+            $alternative_string = '';
+        }
+
+        /* translators: 1: String for alternative function (if one exists) */
+        $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' ),
+                $alternative_string
+        );
+
+        // Use the 'alert' callout box if it's available. Otherwise, fall back to a theme-supported div class.
+        if ( class_exists( 'WPorg_Handbook_Callout_Boxes' ) ) {
+            $callout = new \WPorg_Handbook_Callout_Boxes();
+            $message = $callout->alert_shortcode( array(), $contents );
+        } else {
+            $message  = '<div class="private-access">';
+            $message .= apply_filters( 'the_content', $contents );
+            $message .= '</div>';
+        }
+
+        return $message;
+    }
 }

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/scss/main.scss

@@ -1020 +1020 @@
             font-style: italic;
         }
+        .private-access {
+            margin-top: 30px;
+            padding: 20px 20px 10px;
+            border: 1px solid #ffb900;
+            background-color: #fff8e5;
+        }
+        .callout {
+            margin-top: 30px;
+        }
     }
 

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/stylesheets/main.css

@@ -1223 +1223 @@
   font-style: italic;
 }
+.devhub-wrap .wp-parser-class .private-access, .devhub-wrap .wp-parser-function .private-access, .devhub-wrap .wp-parser-hook .private-access, .devhub-wrap .wp-parser-method .private-access {
+  margin-top: 30px;
+  padding: 20px 20px 10px;
+  border: 1px solid #ffb900;
+  background-color: #fff8e5;
+}
+.devhub-wrap .wp-parser-class .callout, .devhub-wrap .wp-parser-function .callout, .devhub-wrap .wp-parser-hook .callout, .devhub-wrap .wp-parser-method .callout {
+  margin-top: 30px;
+}
 .devhub-wrap.archive .wp-parser-class h1 a, .devhub-wrap.archive .wp-parser-function h1 a, .devhub-wrap.archive .wp-parser-hook h1 a, .devhub-wrap.archive .wp-parser-method h1 a, .devhub-wrap.search .wp-parser-class h1 a, .devhub-wrap.search .wp-parser-function h1 a, .devhub-wrap.search .wp-parser-hook h1 a, .devhub-wrap.search .wp-parser-method h1 a {
   font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;