Six Reasons To Get A Handbook Page For Your Module

Checkout view being currently disabled in ViewVC is a very good opportunity to remind everyone that linking to your README.txt file in CVS does not count as documentation on your project page!

Here are some things I, or anyone else, can do with a proper documentation page in what used to be called the handbooks section of drupal.org:

  • Correct it.
  • Expand on it.
  • Clarify things for newbies.
  • Add a section listing modules that works with yours that users might be interested to know about, thus helping a tiny tiny bit to make sense of the Big Lego Box.
  • Share some of the things I've done to theme your module.
  • Add to a section on troubleshooting, and hopefully keep some of the more recurring issues out of your queue (or at least give you somewhere to point to in slightly self-righteous manner ;)

In short, with a little bit of seeding (some basic explanations of the concepts of your module and some instructions), you open it up to a whole community of potential writers and editors. Which is a concept we should all be familiar with!

If you say that keeping a documentation book page in sync with your CVS readme file is too much of a hassle (and who said it should be in sync anyway?) then it's because you've not thought about the benefits.

Nodes As NIDs

Is it just me who finds this poor style and potentially confusing:

<?php
function my_function($nodes) {
  foreach (
$nodes as $nid) {
   
// do stuff
 
}
}
?>

To me, a variable names $nodes will be an array of nodes -- that is, node objects. If it's an array of nids, I would call it $nids to avoid confusion about what we have there.

I'm curious if other people agree (in other words, is it worth my time writing a patch for core or will it just lead to bikeshedding?)

In general, though, I think it's a good idea for variables to be named in such a way that describes what they hold; also for the same data to have the same variable name as it travels through functions. In other words, avoid this:

<?php
function foo() {
 
bar($ponies);
}

function
bar($caterpillars) {

}
?>

Unless there's a good reason, say if bar() is generic and can accept any animal. In which case, call its parameter $animals, obviously.

Creating A Set Of Fields In One Swell Foop

Situation: you need a heap of imagefields that more or less have the same setup. Let's not go into why.

You could spend half an hour bored witless clicking through the interface.

Or you could create just the one field, export the content type with content copy, and then doctor the code a little before importing it back in. Like this....

<?php
// The usual content type stuff here.
// Set of image fields
$image_fields = array(
 
'field_image_1' => 'Image 1',
 
'field_image_2' => 'Image 2',
 
// etc
);

foreach (
$image_fields as $name => $label) {
 
$content['fields'][] = array (
   
'label' => $label,
   
'field_name' => $name,
   
'type' => 'filefield',
   
'widget_type' => 'imagefield_widget',
   
'change' => 'Change basic information',
   
'weight' => '-3',
   
// the rest of your field export code here
    // don't forget to fix the brackets, as export code
    // comes out as a numerically keyed array.
    // and don't forget the closing }!
?>

Hey presto, heap of fields created in one go. Don't forget to set their weights nicely afterwards.

Small Core, Big Drupal, Tighter Contrib: Outer Core?

I've been mulling this idea since Paris, trying to figure out the best way to present it.

But basically:

We want a smaller, slimmer, efficient core.
But we also want Drupal to, like, be useful.
We want contrib, at least the high-use end of contrib, to be smoother, more organized, released on time with core.
It's been suggested we have a contrib maintainer, who would have the unenviable task of managing a huge kaboodle.

So on the one hand we want to move things out of core, into contrib: things like poll, blog, even forum and profile. However, moving out to contrib is currently recognized as being a death sentence for the code itself, and dooming users to the curse of a million Lego bricks (to quote webchick).

On the other hand, we want better underpinning for the contrib modules that really make Drupal what it is: views, CCK (what's left of it out of core), panels, flag, voting, token, and so on.

These two things actually seem the same to me: define an Outer Core. This would be a fairly loose collection of modules, not simply the 40 most popular, but those that provide important functions, play well together. Outer Core would get a maintainer or two, to ensure good use of APIs, generalization and abstraction of common code where possible, no duplication of code or features, and plan releases.

Drupal the framework would be just the core.
Drupal the product would be core + outer core. We'd release both simultaneously, available as a single download.

End result, I hope: we tame a sizable part of the Big Lego Brick Box.

Never Write A Line Of Code Again!

Okay, so I lied. But module builder can save you a lot of time when writing custom modules.

And it now works with drush, too. I added support for drush a few weeks ago, which let you do things like "$ drush mb mymodule cron init menu nodeapi --write" and hey presto, a new module folder is created, with an info file and a module file, with hook implementations ready to do your (evil) bidding. (Note: this blog does not sanction use of Drupal, module builder, or drush for evil.)

If you're super lazy you can even say "$ drush mb mymodule cron init menu nodeapi --go", using the wash 'n' go option which writes all the files and enables the new module for you. But don't do this if you're writing an install or enable hook, as they won't have any code in them!

The downside was that you needed to install module builder into each Drupal installation you wanted to generate modules for. Bit of a pain if you're developing a few sites and have a few more test sites kicking around.

But no more! You can now stick the module builder folder wherever drush can find it, and build modules in any Drupal 6 installation. You can download hook data to that installation with "$drush mbdl", or store it in a central location by specifying the --data option.

You might say at this point, core hooks are all very good, but what about hooks for CCK, Views, Ubercart, and so on? Well, like all good modules, module builder comes with a hook. Implement hook_module_builder_info, tell it where you hook documentation can be found on the interwebs, and add your module's distinctiveness to module builder's sugary goodness.

And how might you do this?

drush mb foo module_builder_info

With module builder, of course!

Pages

Subscribe to Joachim's Drupal blog