A rough introduction to building a page in Panels 3

Note: The CTools / Panels UI has changed drastically since this article was written, so much of it doesn't apply anymore.

This article is for folks used to making Panels pages in Panels 2 feeling bewildered by Panels 3. I wrote it quickly while my son had lunch and it's not polished at all but it may help some folks until there are better docs. I'm assuming you have bleeding edge Panels 3 and CTools installed for this.

If you go looking to add a page under the main Panels menu, you won't find it. Instead, you need to go to Site Building -> Pages (admin/build/pages). On that page, you'll find a list of existing "System Pages" as well as the ability to create your own. If you are overriding an existing Drupal page, such as the user page or node pages, this is the section you want. If you are creating a brand new page, you'll want the other section. So far I've only overridden the user page so that is what I'm going to use as an example.

Find the line that says "User view" and look all the way to the right for the word "Operations". Click on that. You'll see an option pop up for "Task handlers", which is some new lingo we got in Panels 3. My understanding is that a "task handler" is one of possibly several items that potentially handle the task of showing the page. What this means is that, unlike Panels 2 where you had only one Panels page per path, you can have multiple possible Pages for a path and set the rules for which one is used when the page is viewed. So click on "Task handlers" and let's get started making one.

In the "choose" dropdown, choose Panel and then add new handler. You are then taken to a page where you can determine access control. I haven't played with that, yet, so just continue. Then you need to choose a layout. Be aware that only the flexible layout lets you use the fancy layout tool at this time. If you choose any other one, it's static. For our example, choose flexible and then continue. This takes you to the add content page.

Click on "show layout designer" and the screen will change. Flexible starts you out with one region for adding content. Odds are you'll want to add more. Take some time to plan out how you want to do it because it can be tricky to move columns/rows around once you have content in them. How it works is this: The "canvas" lets you add columns. Columns let you add rows. Rows let you add either regions or more columns. Notice that the canvas won't let you add rows. That's very important. If you start out with a left and right column in the canvas and then decide you want to add a footer row across the bottom of them, you're out of luck. To do that, you need to have one column in the canvas, add two rows to that, and then put your side by side column in the first row. It's a bit tricky to get your head around, which is why pre-planning is a good idea. Once you have your structure of columns and rows, you'll want to add regions into each one. Regions are where you actually put the content.

In addition to adding columns, rows, and regions, you can use the grippy bars to make columns wider and narrower and the settings to make them fluid or fixed. You can run into some trouble with some combinations of fluid and fixed. If you get a division by 0 error, you have a combo that doesn't work right. Another neat trick is to hold down the shift key while you drag to get it to jump in whole number increments.

Once you have your structure set up, hide the layout designer. You should now see all your regions laid out. Now you can click the plus and choose "add content". This will pop up a dialog with all the content types available for the context you have. What context do you have? At this point, just the user context because it comes for free when you override the user page. If you want to add, say, cck fields from the related content profile node type, you can't do that yet. This is a bit awkward and hopefully will be fixed before the final version. But, back to adding content. Along the left side are the various categories of content types available to you. Pick a category to see the content types in it. For a handy example, click on the "user" category. Then add "user profile". This particular one only has a setting to override the title. Other content types may have more complex forms with various options to set. Continue adding content this way until you have everything you want. You can drag content from one region to another if you decide you don't like where you put it.

When you're done adding content, click finish. And then make sure you save it on the page that comes up. Now go to user/1 (or any other uid) and you should see it replaced by the page you just created. If you want to add more contexts, say a relationship to the content profile node, you can go back to the task handler page and choose "contexts" from the operations popup. Then you will have more content types to add on the add content page. Warning: Don't use the tabs across the top to jump directly from adding contexts to adding content or it will not save. You need to click the continue button at the bottom to save the new context, even though continue doesn't take you to the add content page. Then you can click the link to go to add content.

This article just barely scratched the surface of what's possible. As more people begin using Panels 3, I'm sure there will be lots more in depth articles getting into all the possibilities. For now, hopefully this will get you started.