I have updated panels to the latest version and wanted to try out the IPE. However I have a couple of styles that come up as legacy styles in the status report.

My question is, what to I have to do to upgrade these - I realise that legacy.inc checks the version number - but how is this set in the first place?

I would appreciate a pointer on how to do this for both a module located style and a theme located style plugin.



#10 panels-865840-10.patch1.26 KBc4rl


kmv’s picture


smoothify’s picture

Ok, after some further delving into this I think I have worked it out:

For a module you need to add

function  MODULENAME_ctools_plugin_api($module, $api) {
  if ($module == 'panels' && $api == 'styles') {
    return array('version' => 2);

For a theme you need to add

api[panels][styles][version] = 2

to your theme's info file

Now once done this will not trigger the legacy mode, however if the style works for regions then you are likely to need further changes to it.

merlinofchaos’s picture

The primary difference between a 2.0 style and a legacy style is that 'render panel' changed to 'render region' and regions now receive fully rendered panes in the array rather than unrendered panes in the array.

I believe if you make those changes plus what's already mentioned in this post, you can update your styles to work with IPE.

smoothify’s picture


I noticed your comment in the other issue about using PANELS_REQUIRED_CTOOLS_API to detect which version is in use and if required to deliver a deprecated version.

However, as a quick thought - is there any harm in having both 'render panel' and 'render region' callbacks in the style and then just returning a different version number depending on the CTOOLS_API version?

smoothify’s picture

Just to give a reason for my last comment, by having both callbacks in the same style, it means it can easily handle when panels / ctools is up to date but panels is running in legacy mode (perhaps due to another style not being updated).

merlinofchaos’s picture

I hadn't thought about that, but you can have both.

smoothify’s picture

I have (hopefully) completed the patch for panels_tabs module so it no longer uses legacy mode.

I did run into some issues though, some of which can be seen here (might be useful for those wanting to upgrade their own styles)

#865922: Update to work fully with panels 3.7

I was using the renderer->prepare method in my pre_render hook implementation which does not exist in the legacy renderer only the standard. I had made that call conditional by checking if the ctools api was up to date but I wasn't actually checking if another style had triggered legacy mode. When I added the extra check it fixed the error but broke the style output.

After delving into the code I noticed that the panels_renderer_legacy class actually checks if the style is legacy and if not it runs the new 'render region' call back despite being in legacy mode and using the legacy renderer.

To resolve the problem, I had to adapt my code so it works in both modes, and the end result is if ctools is upto date then it will always trigger 'render region', otherwise 'render panel' will be used

merlinofchaos’s picture

Component: Plugins - styles » Documentation
Category: support » task

Making this a documentation task.

perusio’s picture

Hmm, is this correct, particularly regarding the part about just adding

api[panels][styles][version] = 2

to a theme .info file and you're done? I just did that to a project that has been in the back burner, but that now I'm finishing and with the new CTools & Panels if do that, i.e., place the api version declaration in the theme .info file I get a blank page: no site template is rendered.

Going back to legacy mode fixes it. This theme implements both layout and style plugins, should I also replace the render_panel callback by render_region to make it compatible and thus operate out of legacy mode? Ah, yes this is a Panels Everywhere theme and I'm using my own page.tpl.php.

Thank you,

c4rl’s picture

Priority: Normal » Critical
1.26 KB

The priority of this seems critical as your panel is completely broken if these changes aren't made. Is http://drupal.org/node/496278 a good place to document this?

In addition to the remarks above, if layout plugins and styles plugins reside in a subdirectory of your theme, you also need to define the path relative to the theme's .info file.

So, suppose your layouts are in sites/all/mytheme/panels/layouts and your styles are in sites/all/mytheme/panels/styles. Altogether, your panels information in mytheme.info file should look something like this:

plugins[panels][layouts] = panels/layouts
plugins[panels][styles] = panels/styles
api[panels][styles][version] = 2
api[panels][styles][path] = panels

Unhappily, the update status page doesn't inform you of this, nor provide a proper link to documentation.

FWIW the attached one-liner patch (somewhat ironically) changes the update status page to link to this very issue until proper style plugin documentation can be made. Better than linking to "###FIXME."

Dubs’s picture

For anyone who may be interested I had to update a style plugin. As well as the changes mentioned in #9 and #10 I had to do the following changes to my .inc file.

In the hook_panels_styles function:

-'render panel' => 'example_style_panel',
+'render region' => 'example_style_panel',

In the theme function for each region:

function theme_example_style_panel($display, $panelid, $panes, $settings){
	foreach($panes as $pane_id => $renderedpane) {
                - $content->content .= panels_render_pane($data, $display->content[$pane_id], $display);
		+ $content->content .= $renderedpane;
	return theme('example', $content);

The important part is that $panes are now already rendered. panels_render_pane will not return anything which explained the empty displays we had.

Hopefully this might help someone else with the same problem...

smira’s picture

Status: Needs review » Active

please commit #10

thank you for your help!

merlinofchaos’s picture

Status: Active » Needs review

Wasn't marked 'needs review' which means it didn't show up in the normal patch review process.

smira’s picture

Status: Active » Needs review

my bad

rootwork’s picture

Status: Needs review » Reviewed & tested by the community

It would be really nice for that patch to be applied just so the notice doesn't have a big, obvious, broken link. If there's really no other help documentation, this page is better than nothing, isn't it?

Given that this is just a textual documentation change and no one has suggested a better page to link to after 10 months of patch review, I say this is RTBC.

If there's now documentation on this, by all means we can change that ###FIXME to some real documentation...

Letharion’s picture

Status: Reviewed & tested by the community » Fixed

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.