[wp-trac] [WordPress Trac] #14808: Add Editor Documentation Functions URL for theme-defined functions

[WordPress Trac]

#14808: Add Editor Documentation Functions URL for theme-defined functions
-------------------------------------------------+-------------------------
 Reporter:  GamajoTech                           |       Owner:  exthilion
     Type:  enhancement                          |      Status:  assigned
 Priority:  normal                               |   Milestone:  Future
                                                 |  Release
Component:  General                              |     Version:
 Severity:  normal                               |  Resolution:
 Keywords:  good-first-bug has-patch needs-      |     Focuses:
  refresh changes-requested                      |  administration
-------------------------------------------------+-------------------------

Comment (by dontfeedthecode):

 I've taken a stab at refactoring this as per the suggestion from @desrosj
 and have provided a patch.

 https://core.trac.wordpress.org/attachment/ticket/14808/doc-override.diff

 Below are usage examples, the patch provides two filters (one for theme
 links, one for plugin links to make a clear distinction between the two)
 and allows the user to override links down to an individual function
 level.

 The onchange event for the button does a simple check to see if the option
 value starts with http or https, opens that link rather than the default
 if provided and falls back to the original if not. I'd like to have moved
 this JS out of the inline event tag and into a script block to allow for a
 more robust solution, e.g. using a try/catch with URL(), as this would be
 quite lengthy.

 {{{#!php
 <?php
 /**
  * Filter the function documentation URL in either the theme or plugin
 editor.
  *
  * @param string $function Name of the selected function.
  * @param string $file Full path of the file being edited.
  * @param string $theme Director name of the theme being edited.
  * @return string
  */
 function override_theme_documentation_links( $function, $file, $theme ) {

         // Ignore for anything but our test theme.
         if ( 'test-theme' !== $theme ) {
                 return $function;
         }

         // Example 1: Override documentation URL's for specific functions.
         if ( 'get_header' === $function ) {
                 return 'https://mysite.com/different-docs?function=' .
 $function;
         }

         // Example 2: Override documentation URL's for all functions
 within a specific file.
         if ( str_contains( $file, 'header.php' ) ) {
                 return 'https://mysite.com/header-docs?function=' .
 $function;
         }

         // Exmaple 3: Override documentation URL's for all functions for
 theme.
         return 'https://mysite.com/docs?function=' . $function;
 }

 add_filter( 'theme_editor_documentation_url',
 'override_theme_documentation_links', 10, 3 );

 /**
  * Filter the function documentation URL in the plugin editor.
  *
  * @param string $function Name of the selected function.
  * @param string $file Full path of the file being edited.
  * @param string $name Name of the plugin being edited.
  * @return string
  */
 function override_plugin_documentation_links( $function, $file, $plugin )
 {

         // Ignore for anything but our test plugin.
         if ( 'hello.php' !== $plugin ) {
                 return $function;
         }

         // Exmaple 3: Override documentation URL's for all functions for
 plugin.
         return 'https://mysite.com/plugin-docs?function=' . $function;
 }

 add_filter( 'plugin_editor_documentation_url',
 'override_plugin_documentation_links', 10, 3 );
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/14808#comment:14>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform