WordPress.org

Make WordPress Core

Opened 9 years ago

Last modified 3 months ago

#14808 assigned enhancement

Add Editor Documentation Functions URL for theme-defined functions

Reported by: GamajoTech Owned by: exthilion
Milestone: Priority: normal
Severity: normal Version:
Component: Themes Keywords: good-first-bug has-patch
Focuses: Cc:

Description

Currently, functions that are called within template files shown on the editor are included in the list of functions that you can try and lookup documentation for.

(The $ignore_functions array only seems to be for functions defined, not called, in a file.)

As the http://api.wordpress.org/core/handbook/1.0/?function=... seems to be hard-coded in, it's not possible for themes to overwrite it for functions they've defined.

Is it possible to allow themes to define where the documentation lookup should be for their own functions?

Attachments (3)

14808.diff (1.2 KB) - added by GaryJ 8 years ago.
First draft.
filter.diff (2.8 KB) - added by exthilion 3 years ago.
Apply @GaryJ's original patch to theme and plugin editor
filter-https.diff (2.8 KB) - added by exthilion 3 years ago.
https links by default, per @chriscct7

Download all attachments as: .zip

Change History (13)

#1 @nacin
9 years ago

  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to Future Release

@GaryJ
8 years ago

First draft.

#2 @GaryJ
8 years ago

  • Cc gary@… added

First attempt at adding a filter here.

  • esc_url() may or may not be the right escape here.
  • The filter name may need to be a less general name if the plugin editor can't be filtered with the same signature.
  • The current theme and file path are passed as arguments, so the URL can be changed conditionally.
  • It may be that passing the full path as the $file is not helpful, and can perhaps be trimmed down to be a relative path from the theme folder.

Themes could now filter the URL as per normal:

add_filter( 'documentation_url', 'child_documentation_url', 10, 3 );
/**
 * Filter the function documentation URL in theme editor.
 *
 * @param string $url
 * @param string $theme Name of the theme
 * @param string $file full path of the file being edited
 * @return string
 */
function child_documentation_url( $url, $theme, $file ) {

	if ( 'My Awesome Theme' != $theme )
		return $url;

	return 'http://my.example.com/?theme= ' . $theme . '&function=';

}

It would then be up to the script at my.example.com to check the function name against a list of known functions for that theme (or at least ones they want to provide documentation for - could even provide more detailed documentation for WP functions) and redirect to their own documentation, or redirect back to api.wordpress.org/code/handbook/1.0/?function= accordingly.

#3 @defries
8 years ago

  • Cc remkus@… added

#4 @SergeyBiryukov
8 years ago

  • Keywords has-patch added; needs-patch removed

#5 @chriscct7
5 years ago

  • Keywords needs-refresh added

Refresh to adjust link to https

#6 @iseulde
5 years ago

  • Component changed from Editor to Themes

#7 @swissspidy
4 years ago

  • Keywords good-first-bug needs-patch added; has-patch needs-refresh removed

I guess this needs a new patch for the theme and plugin editors, including proper filter docs.

Probably a better filter name than documentation_url as well, maybe file_editor_documentation_url.

@exthilion
3 years ago

Apply @GaryJ's original patch to theme and plugin editor

#8 @exthilion
3 years ago

I'm new to submitting patches here, so please forgive me if this isn't the right way to approach this.
Per the patch above by @GaryJ

<?php
add_filter( 'file_editor_documentation_url', 'child_documentation_url', 10, 3 );
/**
 * Filter the function documentation URL in theme editor.
 *
 * @param string $url a default url if $provider doesn't provide a custom url
 * @param string $provider Name of the theme or plugin
 * @param string $file full path of the file being edited
 * @return string
 */
function child_documentation_url( $url, $provider, $file ) {
        // Check if $provider is handled by this filter. If not, use default.
        if ( 'My Awesome Theme or Plugin' != $provider )
                return $url;
        // Provide some kind of logic here to generate correct documentation url for $file.
        return 'http://my.example.com/?theme= ' . $provider . '&function=';
}

Seems like a trivial change, but I am also unsure of what @swissspidy means by proper docs.

Last edited 3 years ago by exthilion (previous) (diff)

@exthilion
3 years ago

https links by default, per @chriscct7

#9 @swissspidy
3 years ago

@exthilion Thanks for the patch.

As per our inline documentation standards, each hook and filter in core needs inline documentation, similar to how you documented child_documentation_url in your example above.

#10 @DrewAPicture
3 years ago

  • Keywords has-patch added; needs-patch removed
  • Owner set to exthilion
  • Status changed from new to assigned

Assigning to mark the good-first-bug as "claimed".

See filter-https.diff

Note: See TracTickets for help on using tickets.