You can currently make two types of extensions:

• Snippet Extensions
• Hook Extensions

Snippet Extensions are pieces of code that define a template [[tag]]. Hook Extensions are pieces of code that are included and executed in certain parts of pivot itself. An example of this is how the blacklist is able to do its mojo when a comment/trackback is posted, or when a referer is added.

First, get yourself a Pivot development IDE. You can pay a lot of money for the best, from Zend Studio or NuSphere PhpEd, or you can use some very good free IDEs, such as Maguma Studio or PHP Designer.

Now, write your snippet. If you don’t know where to start, try to understand the code of an existing snippet, preferably one which does something close to what you want to do.

There is also a skeleton snippet which tries to show some common functionality which snippets might like to perform. If it doesn’t include an example of a general principle which you would like to see demonstrated, then please request one.

When you have written your script, you will then want to test it. There appear to be two philosophies to this:

• Some people prefer to upload the snippet and test it in situ; I personally don’t like this, as it means repeatedly adding debug echo statements and uploading again until the script is debugged.

• Other people prefer to test offline on a PC. All of the IDEs mentioned above will download and install PHP on your computer, and you can run the script there, where it is quicker to add more echo statements if you need them than it is to upload to your web site.

The non-free IDEs mentioned above have excellent integrated debuggers, where you can set breakpoints, run to a particular line of code, examine and change variables, etc. The two free IDEs mentioned above can probably also be used in conjunction with free debuggers.

If you prefer to test offline, you could use the philosophy used in graham_k's skeleton snippet. Always start with

// development testing outside Pivot/offline
if(!defined('INPIVOT')) {
        $pcTesting = true;
        require_once('../../pivot/pv_core.php');
}

then declare the snippet function (two functions if use the dynamic snippet method) and finish up with the following executable code:

if ($pcTesting == true) {
        echo main_snippet_my_Snippet(‘some’, ‘parameters’);
}

This code will only execute when offline testing on my PC, since we are not ‘in Pivot’ when testing, but will do nothing when the snippet is executed within someone’s blog.

If you need more help, please ask in the ”Extension Discussion & Development” forum.

Snippet Extensions are placed in the snippets/ folder in your extensions folder. So, usually this is extensions/snippets/.

There are three “flavours” of snippets:

• Static snippets (which always produce the same output). A typical example is the Hello World snippet.
• Dynamic snippets (which produce different output each time the page is loaded).
• Dynamic snippets which can appear once each in multiple entries on a page.
• You can even use (some) snippets on pages outside of Pivot.

This page gives some examples of how to implement various common functionalities of snippets. If you get stuck on anything and manage to solve it, please post here and help others.

There is also a sample skeleton snippet at http://forum.pivotlog.net/viewtopic.php?t=7908 which illustrates some of these principles and which you might want to use as a basis for your (first) snippets.

Probably the most basic functionality. Many, if not most, snippets loop through the database, displaying information about your posts in various ways.

// firslty, get all entries
$myDb = new db();
$entries_array = $myDb->getlist_range("0000-00-00-00-00", "2010-01-01-00-00","","", FALSE);

// now loop through them
foreach($entries_array as $entry)
{
  ...
}

ATTENTION: do NOT fall into the trap of

$db = new db();

because of a name clash with the global $db

Use the make_filelink() function.

$url = make_filelink($entry['code'], $weblog, '');
$output .= ' <a href="' . $url . '">' . $title . '</a><br>';

This is useful for making a list of entries, by listing the title of each entry, and possibly its date, category, etc, as a URL whic when clicked opens theentrypage for that entry.

Simple, once you know how -use the lang function.

echo lang('numbers', 2) . ' + ' . lang('numbers', 2) . ' = ' . lang('numbers', 2 + 2);

outputs

two + two = four

if your language is English, and

zwei + zwei = vier

if your language is German.

This one is slightly tricky, but it allows you to make your snippets totally independdant in a way that allows others to easilly add strings for a new language.

Here is a very simple example:

function Parse_output($index, $value='')
{
  global $Cfg;

  $language = $Cfg['deflang']; 
  $strings = 
  array('eng' =>
          array('on %value%', 
                '%value% weeks ago' 
                ), // end of English			 
          'ger' =>
           array('an %value%', 
                 'vor %value% Wochen'
                 )  // end of German, add other languages here
          ); 
  
  return str_replace("%value%", $value, $strings[$language][$index]);
} // end of Parse_output()

So that Parse_output(0, 2) in English gives ”On Monday” and Parse_output(1, 2) gives ”two weeks ago”.

• An example of a simple (static) snippet: Hello World
• Passing Parameters to snippets: Uppercase Snippet
• How to write dynamic snippets: Dynamic Snippet