I would like to get some opinions regarding the best practices for developing WordPress plugins that provide theme integration.
In order to make sense as I ask this question, let me start with an hypothetical example of a scenario that I am curious about. Imagine that I create a plugin called “Discography”. Discography registers three custom post types: “Bands”, “Albums”, and “Tracks”. The plugin also provides meta boxes that provide details for each post type, as well as, custom taxonomies to organize each post type. These post types are tied together with the Posts 2 Posts plugin. Within the admin, the user can add new bands, which can be associated with albums, which, in turn are associated with tracks, all which will have lots of other data added to them via meta boxes and taxonomies.
Now, I don’t want this plugin to simply set up an admin for users to enter this information; I would want it to provide some default displays for the data. A more advanced user/developer would be fine having only this admin. It would be easy enough for her to grab that data and use in the theme; however, without some default views, this plugin would be useless for most users. For this example, you could display anything like (parentheses show the ways the info could be displayed in order of the template hierarchy):
- Bands (single-prefix-band.php, single.php, index.php, shortcode)
- Albums (single-prefix-album.php, single.php, index.php, shortcode)
- Tracks (single-prefix-track.php, single.php, index.php, shortcode)
- Band Listing (template-band-list.php, page-band-listing.php, page-{id}.php, page.php, index.php, shortcode)
- Album Listing (template-album-list.php, page-album-listing.php,
page-{id}.php, page.php, index.php, shortcode) - Album Timeline (template-album-timeline.php, page-album-timeline.php,
page-{id}.php, page.php, index.php, shortcode)
It’s important that there is some default presentation for these post types as the default template files would not display all of the information that is needed for each of the post types. For instance, the Twenty Eleven theme, by default, would just show the name, categories, description and post date for an album. Not very useful for an album. I would want to provide a single post template that pulls in the band, release date, record label, album versions, tracks, etc. As a plugin developer I would feel that that would be important to provide. I know the template wouldn’t work out for every theme, but there should be some default that can be further integrated with the user’s theme.
Again, I’m curious about what is the best way to handle this situation? I think you could do any of the following.
Shortcodes
Shortcodes could be used as a very flexible and user friendly way to allow non-devs to add a bands, albums, tracks, band lists, etc. anywhere in the site. It would be helpful for featuring bands on specific pages or creating separate pages for each band (not very efficient, but some users approach things this way). The shortcode would generate HTML, which would be tied to a provided CSS file that would provide a nice default view of the desired data. Everything would be contained within the plugin files and nothing would need to be done with the theme.
Template Files
The plugin could also ship with template files. The template files could be marked up and styled for a nice default view. You could provide instructions for your user to move the files to the theme folder so that the theme will find the right templates when the post types are viewed. You could even go so far as providing an interface to allow the user to move the files with a single click (note: I would not create files in the user’s theme folder on activation because adding files to their theme without them initiating it is evil).
You can also use filters to utilize these files without moving them out of the plugin folder, keeping everything self contained. I’ve seen the “template_include” and the “{$type}_template” filters used for this purpose. In fact, you could use templates from the themes folder and if they are not present, you can fall back on these filters to provide the default views.
The Question
I like to know what others think are the best practices for these situations, if the presented ideas are problematic in any way, and any alternatives that I’ve not included.
Thank you!
I can’t answer every single Q you asked, as reading the Q took enough time so far ;), but I try to give you some insights about my personal experience with developing free, open source plugins.
1. Never do too much. Features are the death of every plugin. Build a basic version first and test the reaction of your users. If your plugin gets a lot of attention, you can integrate the features that are mostly requested.
2. Avoid filling every use case. You need to maintain your plugin. WP offers a new version every three month. And sometimes it’s hard to follow with all of your plugins. To make an example: A new version of the Settings API is currently discussed on Trac. When this will be finished, then there’s the chance that a lot of plugin or theme developers need to change a large portion of code and some people – like me – have even written an abstraction layer above the API. So you need to go back, rewrite your base/abstraction layer and then rework everything that calls parts of that. I promise that this is a lot of work. And even more if it’s bound tight to your code. When you start filling a lot of use cases, then you also got a lot of WP core code evolution that you need to monitor, as well as you got a lot of work keeping your code up to date.
3. Never ever try to bundle a lot of code-examples (or templates) into your plugins or themes. If you want to target developers and end users: Use your blog for documentation. Developers hate stuff like that and end-users are never satisfied (see: filling every use case).
4. Divide your code wisely into single files. Rule of thumb: One file for one part. Example: styles.php, scripts.php, taxonomies.php, cpts.php, etc. Load everything from a “mother” (factory) class and keep your stuff “pluggable”. If you need to rewrite stuff, you will find it easily. If devs are searching for something: they will find it easily. A lot of well named files, don’t harm you.
5. If you got a list of basic styles (classes), leave it up to the user. Chances are simply too high, that styles from the theme or other plugins will intercept your definitions (no matter how much specifity you throw in). Just try to explain it somewhere with as less text as possible.
6. Love your plugin. But let go if you’re bored. 🙂
Now – in short words – something about your plugin idea in detail:
A. Template files are bad. As I said: Document it on your blog, offer example mark-up and styles there. Your blog will profit (and you as well if you got ads).
B. Shortcodes are kool. They don’t harm anybody if the plugin is gone (in most cases) and could be later extend/evolved to TinyMCE buttons (which people love).
C. Make it clear that your plugin needs another plugin. Question this and add a note to admin_notices (via register_activation_hook) if the other plugin doesn’t exits (link it in this case) or isn’t activated (you could do this for the user on activation). Also note that this plugin comes from a trusted source and will be maintained for the next years.
Note: Nothing I wrote is anything more than my personal opinion, which reflects my experience.
In some regards you have to weigh the balance between creating a plugin or a theme, if your scenario requires a lot of customization/features it is usually always better to create a theme instead. That way the user can then customize in terms of look which is always easier then getting the user to customize the functionality ( by jamming shortcodes everywhere), you have greater feature control, it works with other plugins, etc.
A plugin trying to heavily integrate with all the variety of themes on the market is bound to cause a lot of trouble and honestly a lot of work for you.
For example instead of creating a very integrated plugin based on music and discography management, instead create a theme for that purpose, this is becoming more popular for niche markets that require custom work. A real world example would be a real estate based theme, there is no way I would use a plugin for this since it has such a deep feature set, instead it is created from the ground up as a theme, since themes can take advantage of all the features of plugins anyhow.
It is also likely that from a marketing perspective a niche theme will do better than a plugin when balancing front-end features.
Virtual pages
A third technique I saw was assigning a special page as the placeholder for your plugin and use ‘the_content’ filter to output whatever you need to output.
In this way, you can make templates that blend in with the theme structure, since you don’t have to deal with headers, sidebars, footers and wrapper divs.
A great example of this can be found in the bbPress plugin:
http://bbpress.trac.wordpress.org/browser/branches/plugin/bbp-includes/bbp-core-compatibility.php?rev=3434#L931