Everything you need to know about Mango pods – Part 2: Plugin Pods
In part two of this three part series, I'm going to show you how to create a pod from a plugin and discuss the implications of doing so.
Just as with Template Pods, you need to have a pod-enabled theme. There is actually still one way to get your pod content displayed in a non-pod-enabled theme, but let's not get ahead of ourselves.
This post is going to be long enough as it is, so I am not going to cover the fundamentals of plugin creation here. (Maybe some other time.) To get you started, I would recommend you read the plugin documentation, followed by Seb Duggan's posts on plugin architecture changes in Mango 1.3+ (here and here). From there, my advice is to find a plugin that does something similar to what you want to do, and reverse engineer it. I'm also going to assume you have a basic understanding of how Mango dispatches (aka broadcasts) events, and how to respond to them. (Not to be redundant, but that's a fundamental of plugin creation in Mango.)
Before you can create a pod, you have to understand exactly what it is, and everything that it does. In it's simplest form, a pod is a small block of HTML that is typically added to a website's sidebar, and its location — at least the order of things on that sidebar — is easily configurable from admin. You can make it more complex if you want, but for the sake of simple explanations, let's just think of it as a block of HTML. But in addition to creating that block of HTML, your plugin must also respond to various events so that customization through configuration is possible.
If you've seen Mango's pod manager, you know that it works by giving you a list of available pods and their associated IDs, and a text box for you to pick which pods to display, and in what order, by typing in the IDs in the order you want them displayed (one per line). How does Mango know that your plugin creates a pod? And how does it know what that pod's ID is?
Mango knows these things because your plugin responds when it dispatches the event named "getPodsList". Your plugin is listening for that event, and responds with a structure of information about it's available pod including the Name and ID.
plugin.xml:
plugin.cfc:
This information is used in the Pod Manager to give the end user the option to display the pod, and the choice of where to display it. The next event that Mango will dispatch that your plugin needs to respond to is "getPods". You also have to check if your pod has been enabled, by checking for it in the list variable event.allowedPodIds. Obviously, if the variable contains an asterisk, (meaning display all) you should count that as a match:
plugin.xml:
plugin.cfc:
Pro-tip: Did you notice that I just included a CFM template from inside our plugin CFC object? You can do that, and the code inside the CFM template acts as if it's written in the CFC. It has access to the same local scope and variables scope — as well as everything else — that code written directly in this spot would. This content is not cached with the CFC instance, either, which makes modifying and debugging its content during development much faster and simpler. There's no need to clear the cache or de-activate and re-activate the plugin. I use this method for all of my rendered content areas: settings pages, pod bodies, and content added to events (like Related Entries).
So now your plugin properly informs Mango of your pod's existence, and properly renders the pod content when it's requested. What's left to do? Well, what about non-pod-enabled themes? We don't want to just leave these users out in the cold, do we? No, we don't!
Another beautiful thing about Mango is it's ability to create custom events, and the simplicity of doing it. Listening for your own custom event to display the pod content will allow users with non-pod-enabled themes, or users who want to put your pod somewhere outside the pod group (in a "custom" location, if you will) to use your plugin. Listening for the custom event is as simple as adding a message listener to your plugin.xml file, and adding the event name to your if statement:
plugin.xml:
plugin.cfc:
And dispatching that event? Even easier. You just instruct the user to add this line of code where they want the pod to be rendered.
I'm pretty sure this covers everything about creating a pod from a plugin. If I've missed anything, leave a comment to let me know and I'll update the post accordingly. Next time, I'll show how to make an existing theme pod-enabled, when it's not already.
Posted in Mango | No Responses Yet