Allow widgets to control how their "example" is rendered on the "Add content" dialog (including using a static image rather than rendering)

Thinking about this again after so long!

One thing that the issue description doesn't seem to consider is that we show live previews in two situations: when selecting a widget on the "Add content" dialog, and when configuring a widget. The issue summary seems to be talking about using them for both situations, which I could see. But I could also see an argument for using a static image for just selecting the widget on the "Add content" dialog, but rendering a real live preview when configuring the widget.

Should this be configurable on a per widget basis (ie. two different keys on the CTools content type)? Or, a global setting that affects all widgets? Or should we just pick one way?

Also, for FPPs, it's probably most sustainable to created and render (but not save) an actually FPP in code than use an image. Should there be special support for that? I could see a special configuration just for FPPs that is the field values for the preview to be shown in the "Add content" dialog, which would be much simpler to manage than having to create a new static image every time a widget's appearance changes.

Updating the title and issue description to only address the previews in the "Add content" dialog. And, actually, those aren't really previews, let alone live previews (even though that's what they are called in code where it's all tangled up) but actually "examples" of the widget, so, I've switched the terminology to talk about examples.

Hopefully, this'll make things easier in the future too and we can talk about "previews" (where we show a preview of the values the user entered) and "examples" (where we show an example of the widget so users have an idea before they even pick it).

I also removed the idea about the hook, because that just creates too many branches. If a module wants to make an example for another modules widget, it can alter the other module's plugin definitions.

And, I added the idea of an 'example settings' so that widgets can simply give some example settings, which can overloaded for entity values in FPPs. This settles on the idea that we'll have two defaults for 'example callback': one for normal panes, and one for FPPs so they can handle their cases specially.

We can make a new issue later for allowing widgets to control their live preview, but that seems like a less common use case.

Gah, started trying to make this work in code but the Panopoly code has too many things connected with this called 'preview' that I don't want to change for BC reasons, for example: the constants (PANOPOLY_ADD_PREVIEW_SINGLE, etc) and the theme functions ('panopoly_magic_preview', 'panopoly_magic_preview_link', etc). We can't change those without breaking contrib, but I don't want a mix of things called 'example' and 'preview'. Blergh. No extra clarity for us on this issue :-(

I updated the issue summary to revert back to the 'preview' terminology

Add some code examples of how to actually use this

Added an example for a custom preview callback to the issue summary

And here's a patch! This works in my limited testing, but it'll need to run through the tests and get a bunch more manual testing.

EDIT: Here's a Travis build: https://travis-ci.org/panopoly/panopoly/builds/312081483

Here's a new patch based on a bug that @cboyden found! Before this patch, we show "No Preview" for new FPPs, and with this patch we were showing a rendered version of the FPP, but with no data in it, which led to some really, really weird results. This patch will simply return no preview if the FPP has no 'preview settings' and maintain the old behavior. If we want to come up with a way to allow previews of new FPPs (maybe fill in the fields with their default values, and "lorem ipsum" for required values?) we can do that on a separate issue.

EDIT: Here's a Travis build for the new patch https://travis-ci.org/panopoly/panopoly/builds/317094403

Another cool idea that came out of @cboyden's testing: this patch sets a property on the FPP so you can tell it's being rendered in the preview. For example, if you want to check in the FPP template, you could do:

  <?php if (!empty($elements['#fieldable_panels_pane']->panopoly_magic_preview)): ?>
    <div>PREVIEW</div>
  <?php endif; ?>

This way you could render a little differently if necessary

EDIT: Here's the Travis build: https://travis-ci.org/panopoly/panopoly/builds/317105066

Here's a new patch that adds a special case for reusable FPPs. Basically, if a reusable FPP is being previewed, it'll ignore the 'preview callback' and 'preview image' and force the 'preview callback' to be the default FPP one. Because I could see a case where someone had a widget where they want to always use their custom preview, you can set a special key, 'preview always', to a truthy value to prevent this.

I agonized over how to integrate this into the logic in a way that didn't make it convoluted - I'm pretty happy with that part. This keeps the same sort of "cascading" behavior where we look at the callback, the image, and then one of two defaults - it just adds a special case before any of that happens.

I also struggled with what to name the new key to disable this special case. I'm not super happy with what I came up with ('preview always') but I wanted it to be short and similar to the other two keys ('preview callback' and 'preview image'). Other ideas I had just ended up being too long or too weird, ex: 'preview reusable fpp always', 'disable reusable fpp preview default', etc. If anyone has any suggestions, I'd love to hear them! However, in the end, that is probably a rare edge case, so odds are few people will ever need to care about it.

I think I'm going to commit this. It shouldn't cause any regressions - the default behavior shouldn't change. There could be more bugs, but those will only affect people using the new feature.

Commited!

+++ b/panopoly_magic.module
@@ -1549,7 +1549,7 @@ function panopoly_magic_preview_callback_fpp($type, $subtype, $plugin, $renderer
-  $content = fieldable_panels_pane_view($fpp, 'full');
+  $content = fieldable_panels_pane_view($fpp, 'full', $fpp->language);

I don't know that this is right. The $langcode argument is the language to render in, and the $fpp->language is the language the FPP is saved in. It'd be better, I think, to explicitly pass NULL because that will use the current language of the request for rendering.

That said, I don't have a lot of experience with FPP's and multi-lingual, and haven't tested this in any way.

Thanks! Committed :)