Update the embed format.

[StevenDufresne]

Closes: #34

This PR updates the embed layout by creating an embed.php file and serving a custom embed view.

Changes:

• If function add ()
• If hook, apply the correct function that wraps it.
• If hook of functions has arguments, add ... to denote parameters
  • I tried to show all the properties but it's overwhelming, at least how I had them styled.
• Show parameters in a list
• If parameters list is > 4 truncate

There are no examples of classes, and this wasn't tested on "classes" because of #35. This PR should probably wait for that bug fix.

If you think there is more pertinent information to add to the embed that is missing, please comment below!

Screenshots

[ryelle]

This is looking good! I started playing with it locally so I hope you don't mind that I made a few changes to the CSS.

• Increased the contrast of the text so it passes AA
• Switched the title to use a code font, since it's the function/hook name
• Moved the quotes and comma into the wp-embed-hook span, since those are also green on the main page
• Switched to single quotes for hooks, unless there is a variable

[StevenDufresne]

Those are all great additions. What about we reduce the heading size to 20px? I find it kind of big, especially with the "Fira Code" font.

The difference appears negligible in the screenshots below, but it goes a long way for longer functions.

Before	After

[StevenDufresne]

@ryelle Why this change? I didn't want to make get_params a dependency of get_signature seeing that its values are not used. Although there are no tests, it does make it less testable.

[ryelle]

Oops, I left my reasoning in the commit, not the comment — I did that so it would match the main theme's template tag (e52a950). It also surprised me that you would need to tell get_signature that the function has args, it seems like something that should be detected in the function (since usually it would also output those params - though I know it doesn't here).

[StevenDufresne]

Got it. I think I would prefer to have it less similar than more. Maybe it makes more sense to create a truncated form of the function in template-tags.php since it does appear like we'll be keeping the signature around as it is with some modifications.

What about something like:

function get_truncated_signature() {
 return get_signature( ..., true )
}

...

function get_signature( ..., truncate = false ) {

}

[ryelle]

Yeah, if we might use it elsewhere, I like your suggestion 👍🏻

[tellyworth]

These look great!

The hook stuff has got me thinking about the way we display those in the headline, ie apply_filters( 'hook', ... ) and do_action( 'hook', ... ). Not just in embeds but in general.

That is definitely clearer than displaying just the hook name. And it'll definitely make some people happy. But it feels kind of backwards to me, and I wonder if some other people might feel the same. What I mean is, in the function reference, the title/headline represents the code I should write in order to use the function, more or less. Whereas with the hooks, the headline represents the code core uses to call the hook, not the code I should write.

Perhaps both of these would be solved by having a one-line example immediately below the headline for every function, hook, etc. Something like:

apply_filters( 'pre_wp_filesize', ... )

add_filter( 'pre_wp_filesize', 'example_callback', 10, 2 );

..where the example line is syntax highlighted and easily copyable. We could also allow multiple examples, ref #12 (comment)

[dd32]

Perhaps both of these would be solved by having a one-line example immediately below the headline for every function, hook
...
add_filter( 'pre_wp_filesize', 'example_callback', 10, 2 );

with #12 in mind, this would work well for hooks IMHO, but I'd expand that to have the function in there too:

add_filter( 'pre_wp_filesize', 'example_callback', 10, 2 );
function example_callback( $param1, $param2 ) {
    return $param1;
}

[StevenDufresne]

I agree that for hooks do_action & apply_filters are useless. Can we change the headline for those and then also follow up with a fully qualified example afterward?