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"!)
- 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
- 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
local/config.phpfile, and that should be it. Have reasonable defaults for any configuration variables.
- 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.
- 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
- Use the
SDV()function for your config variables.