Urban Giraffe

Sniplets is a generic text insertion plugin with support for an extensible processing framework. At it's simplest this means you can dynamically replace text in your posts with text that may be defined elsewhere, or created by some other module. For example, you can use Sniplets to perform syntax highlighting of files, execute custom PHP code, insert data from a database, and perform all manner of other useful tasks within a standard interface. On top of this, Sniplets can be automatically inserted at key points on a page. For example, you can automatically insert text on every RSS post.

New for version 1.3

Sniplets can now be placed in a variety of places including RSS feeds. This gives you the ability, for example, to add a message at the end of every RSS post.

Note that since version 1.3 Sniplets requires WordPress 2.5 and PHP 5. While every effort is made to retain data from previous versions, there is no guarantee that your data will survive the upgrade process. Sorry.

If you did use custom theme placements then you will need to change your places. Placements configured from the options screen can be found under 'custom/your place name'.

Version History

Installation

The plugin is simple to install:

You can find full details of installing a plugin on the plugin installation page.

Creating sniplets

Sniplets can be local or shared. A local sniplet is only available to a specific post or page, while a shared sniplet is available across your entire site. Local sniplets are created from a special interface on the edit page:

Shared sniplets are created from the Manage/Sniplets page.

Wherever the sniplet is created it is edited in the same way:

A sniplet has a name, some contents, a template, a number of modules, and a number of placements:

Modules

Sniplets takes the idea of text replacement one step further by allowing you to attach special processing modules to a piece of text. Multiple modules can be attached and are 'executed' in order. The first module takes some text, processes it, and passes it on to the next module. In this way it is possible to chain functions together and create a highly customized sniplet.

Modules can also accept parameters that change how the function works. Parameters are comma-separated, and are specific to the module:

Note how a parameter is defined by a name (language), an equals, and a value (php). If no equals is supplied then the parameter is assumed to be 'true'.

Adding sniplets into a post

Sniplets are inserted into posts by using a special tagging syntax:

[sniplet NAME]

That's it! The name must match either to a local or shared sniplet, including any spaces. The Sniplets plugin will replace this tag with the results of running all functions on the sniplet contents.

If you configure Sniplets to do so, you can also use an additional tag to change the contents of a Sniplet from inside your post:

[snip NAME]new content[/snip]

This is basically the same as before but this time the contents of the sniplet are overridden by whatever is inside the start and end tag.

Placements

Sniplets can be automatically inserted into key points of a page by assigning placement points. For example, adding a placement point 'comment form' to a sniplet will automatically insert that sniplet into the comments form area. The following areas are pre-defined:

As part of version 1.3, these areas can now refined to specified pages of your website. For example, RSS feeds, posts, archives, and home page. Not all places are available for given page (for example, there are no comments on RSS feeds).

Additionally you can define your own placement points from within your theme or from the Sniplets options page. Custom placement points can then be inserted into your theme using template tags. To do this you need to use the special WordPress filter sniplet_places. You can hook into this from the functions.php file in the theme:

<?php
 
add_filter ('sniplet_places', 'my_theme_places');
 
function my_theme_places ()
{
  return array
  (
    'My Theme Name' => array
    (
      'mytheme/myspecialplace' => 'Before the Sidebar',
      'mytheme/myotherplace'   => 'After the Sidebar'
    )
  )
}
 
?>

Note how the points are defined as an array mapping from a unique ID to a description string. Since version 1.3 you must prefix all places with an identifier for your theme.

Alternatively you can define placements from the Sniplets options page. Here you can only specify the unique ID without description.

Limits

Sometimes you may want to limit the number of Sniplets that appear in a particular placement. For example, you have a message area at the top of your posts, but you only want a maximum of two messages to appear. You can achieve this using limits.

Limits are configured per placement area from the Sniplets option screen. Each placement has an input field where you can specify the maximum number of Sniplets allowed to appear there. A value of 0 means there is no limit. In addition to specifying the maximum limit you can also randomize a placement. This has the effect of displaying Sniplets in that placement in a random order. For example, you limit the placement 'message' to three, set the randomise option, and then create five Sniplets for that placement - the plugin will randomly select three of the Sniplets each time the page is viewed.

Templates

Templates are simple wrapping styles that are applied to the output of a Sniplet. Some templates are provided as default and they can be extended from the Sniplets options page:

Templates are defined in the sniplets/view/sniplets directory. If you add a new template to the Sniplets option page then you need to add a corresponding template file.

Bundled functions

The processing functions included with Sniplets are:

Full documentation on modules can be found on the Sniplet modules page.

Execute PHP

The Sniplets plugin has an additional replacement mode that will execute and replace any PHP code in a post. This mode must be enabled from the Sniplets options page as it represents a security risk if you do not trust your editors.

For example, with the mode enable you can directly enter this into a post:

Today is the year <?php echo date ('Y'); ?>, and it's very lovely.

Security Concerns

Some of the modules open a big door into your website and could give someone the ability to cause a lot of mischief. The Sniplet plugin allows anyone to insert a Sniplet tag in a post, but only an administrator can create a Sniplet. This should be sufficient for you to restrict what an untrusted user can do. If you need further restrictions then you may want to consider deleting some of the modules. This can be done simply by deleting the appropriate file in the 'sniplets/modules' directory.

Creating your own module

Creating a custom module is simple (provided you know PHP!):

<?php
/*
Name: Name of your module, as appears in the drop-down box
*/
?>

Template Tags

You can also insert a Sniplet directly in a theme template file by including the function:

<?php the_sniplet ('name'); ?>

You can insert a placement point by including the function:

<?php the_sniplet_place ('place'); ?>

This will insert the contents of all Sniplets that have the same placement.

Alternatively you can insert Sniplets and placements using WordPress 'actions':

<?php
 
do_action ('the_sniplet_place', 'mytheme/yourplace');
do_action ('the_snipet', 'sniplet name');
 
?>

This has the advantage that should the Sniplets plugin not be active then the theme will not show any errors.

Support

Please direct all support questions to the Sniplets support forum. Support questions left on this page may not be answered.

Bugs & New Features

A full list of all bugs can be found in the Sniplets issue tracker.

A full list of all requested features can be found in the Sniplets feature tracker.