• View
• Edit
• History
• Attach
• Print

Module Guidelines

Questions answered by this recipe

Description

Notes

Distributed recipes go in the cookbook/ subdirectory.

PmWiki's distribution has a specific file/directory structure. Pm recommends that authors of Cookbook recipes, especially those packaged into archives of some sort, place such recipes in the cookbook/ directory. If the recipe includes publicly accessible files such as images or CSS stylesheets, they should go in a subdirectory of pub/.

Archive files (i.e., 'zipfiles' or 'tarballs') should be organized in the following layout:

 package-0.1/
     COPYING.package (license info)
     README.package (install & other instructions)
     cookbook/
         package.php (single script, loads others if necessary)
         package/
            bar.php
            baz.php
     pub/
         package/
            [any skins, images, etc.]
     wikilib.d/
         Package.HomePage (documentation in PmWiki format)
         Package.OtherDocumentation

This way, the files can be copied recursively ("cp -r foo-0.1/* pmwiki") from within their package directory into the PmWiki top-level directory and fit into the appropriate directory. From there, WikiAdministrators? can then be told to simply add a line such as @include_once("$FarmD/cookbook/recipe.php"); to a local customization? file, and not have to worry about conflicts with other files in local/ or scripts/.

Prevent accidental execution of cookbook scripts

To prevent scripts from being run outside of the PmWiki framework, the following line should occur inside any .php files and before any other command.

Other tips

1. Start your source files with a comment that has
   1. your copyright
   2. licensing information.
   3. JavaDoc style comments when you want a comment publicly documented (use /** comment */ style, or /// for single-line comments) so that automated documentation software packages can use your comments.

     /** \file filename
      * \brief a brief, one-line module description
      *
      * a see-also line with a full URL to the Cookbook
      *     (or other) page where the documentation is kept.
      * A longer description of your file, usage, etc.
      */

2. In the first couple of lines of your extension, set the recipe+version for your extension so other code can tell that it's loaded.
   $RecipeInfo['RecipeName']['Version'] = '2006-10-25';
   The recipe name should match the recipe's page name in the cookbook and the version number should match the one shown on the recipe's cookbook page.
3. To avoid function collisions, any function not meant to override another should have the name of the package prepended. Thus "ListToText()" should be "PackageListToText()." Do this also for global variables. For example, don't use a variable $Count; use $FooCount instead.
4. The configuration variables should have reasonable default values.
5. Use the SDV() function to assign initial values to configuration variables.
6. Try to follow PmWiki's variable- and function-naming practices: $CamelCase for global variables, lower case for local variables
7. Insert any styles needed via a $HTMLStylesFmt definition, or if you use a lot and want to call a separate stylesheet use $HTMLHeaderFmt['myrecipe']="<link ..../>";, but if this is used inside a function called by markup, then first create an empty entry with $HTMLHeaderFmt['myrecipe']=''; at the beginning of the script. This will ensure the loading of the stylesheet at the right place in the sequence of css loading. Otherwise it will load last of all, possibly overwriting admin and skin style settings.
8. Use JavaDoc commenting style before functions, with \brief (skip line) full description, as outlined above (skip the \file filename portion).
9. See DebuggingForCookbookAuthors for hints, tips & tricks about writing modules for PmWiki

Comments

Proposal for a Simpler Approach

I propose a much simpler recipe structure as follows:

package-0.01/
   cookbook/
      README.txt    (introduction and installation instructions)
      LICENSE.txt   (license information)
      package.php   (single script that loads others if necessary)
      package/
         foo.php
         bar.php
         bundlepages.php  (script that Adds a page storage location)
         wikilib.d/
            Site.Package         (documentation or whatever)
            Site.PackageXLPage   (translatable strings)
            [any pages you want to bundle]
   pub/
      package/
         [any skins, images, etc.]

Here's bundlepages.php:

<?php if (!defined('PmWiki')) exit();
// Add a custom wikipage storage location for bundles pages.
global $WikiLibDirs;
$PageStorePath = dirname(__FILE__)."/wikilib.d/\$FullName";
$where = count($WikiLibDirs);
if ($where>1) $where--;
array_splice($WikiLibDirs, $where, 0,
  array(new PageStore($PageStorePath)));

Here are some proof-of-concept archives that should greatly speed up the process of getting a new recipe started:

Among other things, this approach would make removing a recipe as simple as deleting two directories and taking the single line out of config.php.

HaganFox August 20, 2005

See Also

• Debugging for cookbook authors - with some more tips
• http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/

Contributors