Andreas Haugstrup Pedersen | solitude.dk

Yesterday I wrote my first ever Wordpress plugin and overall it was not a pleasant experience. I have been working almost daily with Drupal for a year now and there some things the Wordpress team can learn from the Drupal developers when it comes to helping newcomers.

Wordpress does have documentation for how to write a plugin, but it is very well hidden. I bookmarked it so I don't have have to hunt for it again. Using a wiki for all documentation of Wordpress may allow for a maximum of flexibility when writing, but Drupal's collection of "handbooks" makes for a more pleasant reading experience. Drupal's API reference also comes with 6 example modules that demonstrate different parts of the system. I used these extensively when I began developing for Drupal and I missed them for Wordpress and this is something I would strongly recommend that the Wordpress community creates.

My plugin had to do two things. First it had to insert two javascript files whenever a blog post is being shown, secondly it had to insert a code generator on the page where you write new blog posts. Wordpress' way of handling both of these seem clunky and hack-ish compared to Drupal (I did make the exact same plugin as a Drupal module earlier this month).

In both scenarios you insert markup directly onto the page. In the former case by using the wp_head hook to insert the <script> elements, unlike Drupal that has functions included specifically for inserting javascript and CSS. Not a great problem in a simple plugin, but a potential annoyance when you can never be sure that your javascript file is only included once.

The latter caused more frustrations. Wordpress handles changes to the Write page in the same way—you insert raw HTML onto the page. I found it next to impossible to make the look and feel of my added HTML match whatever else was on that page. This is especially true when you use an admin theme that is not Wordpress' default one. I was able to make my code generator match the default Wordpress admin look, but then it does not look very good on Brittany's blog where she uses a different admin theme. On the other hand Drupal has a powerful Form API used to manipulate all HTML forms. For my Drupal module I simply used that to add my form elements. Using the API ensures that my form will always match the current theme, no matter what that is.

I am sure it is a deliberate decision from the Wordpress developers to have plugin developers insert their raw HTML everywhere instead of having built-in functions and APIs. The learning curve is not as steep and there is more immediate flexibility. However at the same time it becomes harder for users to evaluate the code in a given plugin—it is simply harder to decipher how a plugin does what it does and that's a Bad Thing. At the end of the day it's a matter of trade-offs and I strongly prefers Drupal's approach, even if it takes slightly longer to learn how to get started (at the very least because Drupal has excellent documentation to get me started).

There is however no excuse for Wordpress' disorganized documentation. Drupal's API reference is built directly from the comments in the code and in conjunction with the handbooks the result is a very thorough documentation. The code base in Wordpress has only a fraction of the code comments and I imagine that would make it impossible to make a “Wordpress API Reference”. This is sorely needed as many of the functions are undocumented.