- "Hey - you know that box thing in Panels? It's that...ugh, y'know, it's that rectangular, light-colored box. And it's in the Panels editor. It's right there on the editing form, with its name at the top. No, no! Not the name I gave it on the other form, I CAN read - I mean the name of the boxy THING! What in tarnation do I call the thing itself!?!"*
If you've ever tried to talk or write about - or, let's be honest, even
use - Panels, then you probably know right where that sentence is coming from. Panels has all kinds of 'things' in it - things you click on, things you look at, things that contain other things, things that pop up, things that slide away, things that...well, the list goes on. It's enough of a challenge knowing what they are when we see them, but trying to communicate about Panels with real people, and not Panels itself? Fuhgettaboutit. So we're working on a little glossary that we're hoping might make that just a little better.
Panels' basic purpose is structure content for viewing, and it makes use of its own set of terms to describe this structure. There are three essential terms -
Pane,
Panel, and
Display.
- Pane:
- Panes are individual content items, and are the smallest/highest-level unit of content that the Panels API itself configures and renders. If you've used the Panels 2 content editor at all, then you're probably most familiar with panes via the 'Add Content' panels_glossary_term_modal where you pick out the content you'd like to add. Each one of the items on that form is a content type (or subtype); once you select one and fill out the form, you'll see a graphical representation of the new pane appear.
- Panel:
- Panels are the containers that hold Panes. When you select a layout, what you're choosing is the number and arrangement of panels. The content editor represents panels quite well: panels are the blue (by default) boxes with their name at the top and the plus-shaped button that opens the 'Add content' panels_glossary_term_modal. And yes the namespace ambiguity is awful - we're resolving it soon.
- Display:
- The Display unit is the most abstract of the three layout terms. Again, the Panels 2 content editor is a good way to think about it: there's no visual representation of a display in the editor because the display IS what you're editing: it's the object that contains the panels, and it's settings in the display object that govern, for example, which content types are available on the 'Add Content' form.
Displays are abstract and often the most difficult for newcomers to Panels to understand. They're also probably the most important thing that developers implementing the Panels API in a client module need to understand, as client modules work primarily with display objects. Displays are essentially the 'root' object of the API - this is functionally true in Panels 2, but it will be literally the case after Panels is rewritten in OO for Panels 3.
In addition to panels, displays hold almost all of Panels' plugins and are required in most of the main API functions; this is why client modules interact with the Panels API primarily through display objects.
At its core, Panels is really just a structure for negotiating and handling its plugins. For a thorough introduction to plugins, see the introduction to the
plugins API.
The following terms are relevant to all plugin types:
- Plugin Declaration Function:
- All plugins begin with a declaration function. These declaration functions are what Panels searches for in compiling the list of available plugins, and as such are subject to strict naming conventions. The sole purpose of a plugin declaration function is to return a plugin definition array populated with plugin properties.
- Plugin Definition Array:
- Plugin definition arrays are returned from plugin declaration functions. They are made up of two types of properties: setting properties and callback properties. During each page request, Panels stores the information provided by these plugin definition arrays using the logic defined in panels_get_plugins(), allowing other parts of the Panels API to check settings and/or fire callbacks that have been defined in the definition array.
- Plugin Properties:
- Every plugin definition array is an associative array, and we refer to each of the key/value pairs in that array as a 'property.' These properties govern all aspects of the plugin's behavior.
- Setting Properties:
- Setting properties are values that Panels will use directly in various internal processes when deciding how to handle the plugin. Many setting properties are booleans that govern how Panels moves that plugin through various control statements; others are simple strings for administrative interface titles, or drupal 'weight' integers used to sort the plugin within lists.
- Callback Properties:
- Callback properties are strings containing function names; Panels fires these callbacks at certain points in its internal processes.
Panels currently manages eight different types of plugins:
- Arguments:
- Content Types:
- Context:
- Layouts:
- Styles:
- Relationships:
- Cache:
- Switchers:
If we could find categories to put these in, we would. Just because we can't find a group to put them in, though, doesn't mean they're not important!
- Javascript Modal Form:
- Client Module:
* Yep, that's right - we were talking about a Panel! Oh, the ambiguity...
