PmWiki | Cookbook / ComplexRecipes

Summary: Guidelines for people who want to share complex cookbook recipes with other PmWiki user

These are some guidelines for people who want to share complex cookbook recipes with other PmWiki users. (In this context, "complex" means "consisting of multiple parts", not necessarily "complicated"!)

Distribution

Choose a good name for your extension. Below, we use "foo"; that's not a good name!
Put your extension into a tarball or zip file (or both).
The tarball or zip file should create a directory with the name of the extension and the version number, like foo-0.1.
Include license information (such as a COPYING file).
Include a README file, with installation and other instructions.
The files in the directory should lay out like this:

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

Installation should comprise opening the tarball, copying the files recursively to the PmWiki directory ("cp -r foo-0.1/pmwiki pmwiki"), throwing a include_once('cookbook/foo.php') into the local/config.php file, and that should be it. Have reasonable defaults for any configuration variables.

Coding guidelines

In the very first line of any PHP code, write

 <?php if (!defined('PmWiki')) exit();

This makes sure that it will run if and only if it is called from PmWiki. (Without that, users might run your script directly, getting anything from a blank page or a nasty error message to a security exploit. The WWW server actually isn't supposed to be configured to allow that scenario, but perfect configurations are quite rare.)

In the first couple of lines of your extension, define a constant for your extension so other code can tell that it's loaded.

  define('FOO_VERSION', '0.1');

Try to follow PmWiki's variable and function naming practices (CamelCase for everything). That makes it easier for everyone.
For configuration variables, prefix the variable name with the name of your extension, to avoid clashes. For example, don't use a variable $Count; use $FooCount instead.
Use the SDV() function for your config variables.

ComplexRecipes

Distribution

Coding guidelines

See also