Questions answered by this recipe
PmWiki is distributed with a specific file and directory structure that provides a
Some (most?) recipes consist of a single PHP script that goes in the
The simplest add-on recipes are just a single PHP script with an obvious name (recipename.php). It's helpful for your script to include a line to prevent accidental execution of the script and, if it's appropriate, a single line to define the recipe's name and version so a WikiAdministrator can easily check for an update.
Your script can be uploaded and attached to the recipe's page in the Cookbook. Your recipe's Summary and category link(s) at the top of the recipe's page will automatically add it to the appropriate Cookbook index page(s).
If your recipe includes more than just one php script file, then you are encouraged to upload an archive file (i.e., 'zip file' or 'tarball'). The following structure is recommended:
Installing and upgrading become similar to upgrading PmWiki, for example using "
The recipe can be activated in the same way as a single-script recipe, where the WikiAdministrator simply adds a line such as
A recipe with this structure may be easily removed, too. The administrator can simply take the single line out of config.php and delete one script file and two directories to completely remove the recipe.
<?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)));
Simpler Packaging Method
A simpler method of packaging the recipe forgoes the top-level "package-0.01" directory and assumes that packages are unpacking directly into the pmwiki root:
cookbook/ |- package.php `- package/ |- README.txt |- LICENSE.txt ...etc... pub/ `- package/ |- package.js |- package.jpg ...etc...
For example, the recipe author can easily create such an archive from a command line (on a *nix system):
or drag and drop folders from Windows Explorer into Winzip or 7-Zip.
 (note for Windows desktop software users goes here)
Prevent accidental execution
To prevent scripts from being run outside of the PmWiki framework, any .php file should begin with the following line:
Omit the closing ?> php tag
It is recommended to omit the closing ?> tag. The tag is not required, and omitting it avoids problems with unnoticed spaces or blank lines at the end of the file. Also, some file transfer protocols may change the newline character(s) in the file, which can also cause problems. See also the Instruction separation page in the PHP manual.
Set a recipe name and version
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.
The recipe name should match the recipe's CamelCase page name in the Cookbook and the version number should match the one shown on the recipe's cookbook page. This way your recipe will be compatible with automated update-checking. (See Cookbook:RecipeCheck .)
PmWiki and recipes follow a convention that variables acting as "flags" should generally begin with "$Enable...". As a corollary to this, PmWiki never has variables that begin with "$Disable...", so that admins don't have to remember which to use.
Use the SDV() ("set default value") function to assign initial values to configuration variables and give them reasonable default values.
If recipe authors include PmWiki documentation pages (a good idea if the module adds new markup),
This advice seems too specific to include in the guidelines page.
# Insert any styles needed via a
Automated documentation software packages can use your comments if you use JavaDoc style comments (specially formatted C-style comments using /** and */ for comment blocks and // for single-line comments). You start your script with the following
<?php if (!defined('PmWiki')) exit(); /** \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. */ // This recipe's name and version $RecipeInfo['RecipeName']['Version'] = '2007-04-15';
You can also also use JavaDoc commenting style before functions, with \brief (skip line) full description, as outlined above (skip the \file filename portion).
Here are some archives that will greatly speed up the process of creating a brand new recipe:
It would be nice to add a guideline how to prepare your recipe for localization. It seems that most are without. Could that be added to the guidelines? Kenneth, 28 feb 2006.
See Discussion at ModuleGuidelines-Talk
Documenting large/complex recipes
If you have created a recipe that requires more than one page to document it well, just create a separate group for this purpose. So if you have created the recipe
you can create a separate group called e.g.