Changeset 2984 for sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/formatting.php

Timestamp:

04/19/2016 08:15:57 PM (10 years ago)

Author:

coffee2code

Message:

developer.wordpress.org: Prevent overzealous auto-linking of hash parameter text.

Currently, hash params are part of the description text of a single parameter and are not true sub-parameters, so auto-linking the entire hash notation text blob can affect non-description aspects of hash elements (namely when a class is the expected datatype for a hash element) and mess up hash formatting.

• Move param_formatting_fixup() to inc/formatting.php.
• Rename param_formatting_fixup() to fix_param_hash_formatting()`.
• In autolink_references(), don't autolink hash notation text blobs.
• Filter param description text with fix_param_hash_formatting() via filter rather than direct call in content-reference template.
• Call autolink_references() within fix_param_hash_formatting() for hash param item descriptions.

See ​https://wordpress.slack.com/archives/meta/p1460967552000043
See ​https://developer.wordpress.org/reference/classes/wp_customize_control/__construct/

File:

• sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/formatting.php (modified) (3 diffs)

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

@@ -32 +32 @@
         add_filter( 'devhub-format-description', array( __CLASS__, 'autolink_references' ) );
 
+        add_filter( 'devhub-format-description', array( __CLASS__, 'fix_param_hash_formatting' ), 9 );
         add_action( 'the_content', array( __CLASS__, 'fix_unintended_markdown' ) );
     }
@@ -256 +257 @@
      */
     public static function autolink_references( $text ) {
+        // Temporary: Don't do anything if the text is a hash notation string.
+        if ( '{' === $text[0] ) {
+            return $text;
+        }
+
         $r = '';
         $textarr = preg_split( '/(<[^<>]+>)/', $text, -1, PREG_SPLIT_DELIM_CAPTURE ); // split out HTML tags
@@ -386 +392 @@
     }
 
+    /**
+     * Formats the output of params defined using hash notation.
+     *
+     * This is a temporary measure until the parser parses the hash notation
+     * into component elements that the theme could then handle and style
+     * properly.
+     *
+     * Also, as a stopgap this is going to begin as a barebones hack to simply
+     * keep the text looking like one big jumble.
+     *
+     * @param  string $text The content for the param.
+     * @return string
+     */
+    function fix_param_hash_formatting( $text ) {
+        // Don't do anything if this isn't a hash notation string.
+        if ( '{' != $text[0] ) {
+            return $text;
+        }
+
+        $new_text = '';
+        $text     = trim( substr( $text, 1, -1 ) );
+        $text     = str_replace( '@type', "\n@type", $text );
+
+        $in_list = false;
+        $parts = explode( "\n", $text );
+        foreach ( $parts as $part ) {
+            $part = preg_replace( '/\s+/', ' ', $part );
+            list( $wordtype, $type, $name, $description ) = explode( ' ', $part, 4 );
+            $description = trim( $description );
+            $description = self::autolink_references( $description );
+
+            $skip_closing_li = false;
+
+            // Handle nested hashes.
+            if ( '{' === $description[0] || '{' === $name ) {
+                $description = ltrim( $description, '{' ) . '<ul class="param-hash">';
+                $skip_closing_li = true;
+            } elseif ( '}' === substr( $description, -1 ) ) {
+                $description = substr( $description, 0, -1 ) . "</li></ul>\n";
+            }
+
+            if ( '@type' != $wordtype ) {
+                if ( $in_list ) {
+                    $in_list = false;
+                    $new_text .= "</li></ul>\n";
+                }
+
+                $new_text .= $part;
+            } else {
+                if ( $in_list ) {
+                    $new_text .= '<li>';
+                } else {
+                    $new_text .= '<ul class="param-hash"><li>';
+                    $in_list = true;
+                }
+
+                // Normalize argument name.
+                if ( $name === '{' ) {
+                    // No name is specified, generally indicating an array of arrays.
+                    $name = '';
+                } else {
+                    // The name is defined as a variable, so remove the leading '$'.
+                    $name = ltrim( $name, '$' );
+                }
+                if ( $name ) {
+                    $new_text .= "<b>'{$name}'</b><br />";
+                }
+                $new_text .= "<i><span class='type'>({$type})</span></i> {$description}";
+                if ( ! $skip_closing_li ) {
+                    $new_text .= '</li>';
+                }
+                $new_text .= "\n";
+            }
+        }
+
+        if ( $in_list ) {
+            $new_text .= "</li></ul>\n";
+        }
+
+        return $new_text;
+    }
+
 } // DevHub_Formatting