WP Gallery A gallery of wordpress plugins

WordPress Post-Template Plugin

This plugin offers simple and advanced mechanisms for embedding parameterised post snippets into posts.

For the purposes of this plug-in a WordPress Post-Template is simply a WordPress post (or page) which embeds the values of its own custom variables within its html content by means of simple mark-up. The WordPress post-template can then be embedded within another post, also by means of simple markup, with the option to override the custom variables differently each time the post template is embedded.

Additionally custom variables, global variables (defined on the plug-in settings page) and external files can contain XML which can be iterated by the post-template. CSV files are also supported - they are simply converted to <row> and <col> tags and after that it is business as usual. Internally the post-template engine deals with XML (addressable by the power of XQuery). It's most important aspect is that it is hierarchical. Read on to see why this is such a useful feature.

With this plugin you could create a post-template describing an embedded video or a mobile phone deal "box". As you will see below you can then repeatedly render it on some page (optionally) based on variables from an xml file. If you later decide to change the way it looks or you want to render it differently on another site then you only have to change the post-template instead of updating all instances of it on every page it occurs on. Likewise if you want to add more similar content you just have to update the xml file.

Example: Embedding the "Showcase" Post-Template

The "showcase" shown below is rendered using the following directives:

{rewrite}[call(@showcase,class{Mobile Phones},brand{Apple})]{/rewrite}

where the following parameters are passed to the "call" method,

• one anonymous parameter which is being set to "@showcase" which is shorthand for "globals/showcase".The global variables are specified in the settings page of the plugin. On that page "showcase" contains the number of the post-template to embed - "55".
• The class of the devices to show. We are overriding "class" which is defined as a custom variable for post 55.
• The brand of the devices to show. We are overriding "brand" which is defined as a custom variable for post 55.

iPhone 4 16GB Black Refreshed - FREE Mobile Phone - 2000 Minutes - 5000 Texts Only £31 a month (x24) More Deals >> iPhone 4 16GB White Refreshed - FREE Mobile Phone - 2000 Minutes - 5000 Texts Only £31 a month (x24) More Deals >> iPhone 4 8GB Black - £99 up front - 2000 Minutes - 5000 Texts Only £30 a month (x24) More Deals >> iPhone 4 8GB White - £99 up front - 2000 Minutes - 5000 Texts Only £30 a month (x24) More Deals >>

What's Inside the "Showcase" Post-Template?

The "showcase" post-template has four custom variables; style (a style sheet), devices (main xml data), class (device class) and brand (device brand). The post-template is defined as follows (html or text view):

The code above is relatively easy to understand - if you consider how much it is doing. It contains three nested rewrite sections which are iterating the accompanying xml data at various levels. Here is what the data looks like (devices):

<devices><device class="Mobile Phone" brand="Apple" model="iPhone 4 16GB Refreshed"><specs>5.0 megapixel camera with LED flash. HD video recording &amp; editing. Glass design for optical quality and scratch resistance. 3.5&quot; high-resolution screen</specs><variants><variant link="" image="http://three-stores.co.uk/thumb.jpg.php?img=8801466744862.jpg&amp;mw=100&amp;mh=80">iPhone 4 16GB Black Refreshed</variant><variant link="" image="http://three-stores.co.uk/thumb.jpg.php?img=8800932495390.jpg&amp;mw=100&amp;mh=80">iPhone 4 16GB White Refreshed</variant></variants><deals><deal id="1" cost="600" monthly="31" months="24"><line type="upfront" value="0">FREE Mobile Phone</line><line type="minutes" value="2000">2000 Minutes</line><line type="texts" value="5000">5000 Texts</line></deal></deals></device><device class="Mobile Phone" brand="Apple" model="iPhone 4 8GB"><specs>5.0 megapixel camera with LED flash. Comes with iOS 5. HD video recording &amp; editing. Glass design for optical quality and scratch resistance. 3.5&quot; high-resolution screen</specs><variants><variant link="" image="http://three-stores.co.uk/thumb.jpg.php?img=8801466744862.jpg&amp;mw=100&amp;mh=80">iPhone 4 8GB Black</variant><variant link="" image="http://three-stores.co.uk/thumb.jpg.php?img=8800932495390.jpg&amp;mw=100&amp;mh=80">iPhone 4 8GB White</variant></variants><deals><deal id="2" cost="819" brand="Apple" model="iPhone 4 8GB" monthly="30" months="24"><line type="upfront" value="99">£99 up front</line><line type="minutes" value="2000">2000 Minutes</line><line type="texts" value="5000">5000 Texts</line></deal></deals></device></devices>

Here is the style sheet (style):

<style>
#showcase {position:relative;width:620px;padding:0px;margin:0px;}
.child {height:172px;float:left;width:190px;padding:4px;margin:2px;text-align:left;color:navy;background:white;border:1px solid #4797CB;font-family:arial;font-size:12px;}
</style>

The "DealPost" Post-Template (Individual Deal Boxes)

The best way to work with template designs in WordPress' would be a combination of visual and html modes. You can also use an external html editor to design your deal box and then copy the html into your post in html mode.

The "dealpost" post-template has the following custom variables:

• "image" - A link to the image to display.
• "lines" - The lines to display in the deal box.
• "link" - A link to the deal.
• "title" - The title of the deal.
• "monthly" - The monthly amount to pay.
• "months" - The number of months to pay.
• "specs" - The device's specifications.

Complete Syntax and Usage

The following definitions will give a clear understanding of the information that follows:

• Definitions
• source text - Text that may include embedded template tags.
• variable - The name of a variable and optional xpath suffix.
• expression - Can be one of the following:
• a variable - e.g. "model"
• a number - e.g. "123"
• a method - e.g. "call(expression/assignment,assignment,...)"
• source text surrounded by "{" and "}"- e.g. "{Hello World}"
• template tag - Mostly [expression] but can also be {source text} or [assignment] (no output)
• assignment - A variable followed by template tag - e.g. variable[expression] or variable{source text}

Plugin directives are embedded in posts (the source text) in the same way you would create a normal post/page consisting only of text. Refer to the definition of template tag above - that's what you will be adding into your post. However the plugin will do nothing with that tag if you either did not activate the plugin or you forgot to surround the post or post section with {rewrite} and {/rewrite} tags.

{Rewrite} Directives

Everything between the {rewrite} and {/rewrite} directives is rewritten by the plugin, but a {rewrite} directive can also specify which portion of an xml document it is rendering when using the extended syntax {rewrite:var2 var1:xpath} for which the corresponding end-tag is {/rewrite:var2}. This indicates to the plugin that you want to iterate all the node identified by xpath, assuming var1 contains the xml document that you loaded previously. For each node found (var2) the template repeats the template replacements found between the two rewrite:var2 tags. See how this works in the examples above.

Pre-Defined Methods Available

The following methods are available which deal with posts:

• postraw(expression) - The raw post content of the post identified by expression (post id) is returned.
• rewrite(expression, assignment, assignment, ...) - The (result of) expression is rewritten using the inputs.
• call(expression, assignment, assignment, ...) - The post identified by expression is rewritten using the inputs.

The following additionals methods are available:

• ucwords(expression) - Upper cases the first letter of every word in a string.
  
• ucfirst(expression) - Upper cases the first letter of a string.
  
• setcookies(expression, assignment, ...) - Sets cookies according to assignments. Expression is the expiry (ms).
  
• loadxml(expression) - Loads XML from file/url/string. Assumed to be string if starts with "<".
• savexml(expression[, file]) - Outputs expression as xml text. Optional file{filename} or file[expression] parameter.
  
• loadcsv(expression) - Similar to "loadxml" but makes csv rows and column into xml <row> and <col> elements.
  
• replace(expression,search,replace) - Searches expression for search expr and replaces it with replace expr.

Pre-defined Global Values

The following variables deal with variables on the plugin settings page, cookies, request and referrer arguments

• globals - This is an XML variable that can be used with an xpath suffix. It contains:
• All the variables defined on the plugins settings page (accessible as "globals/variable" or "@variable")
• @request - The page arguments - e.g. for "?x=1", @request/@x would return "1".
• @referrer - The referrer arguments - e.g. for "?q=mobile", @referrer/@q would return "mobile".
• @cookies - The http cookies as elements - e.g. "@cookies/tid" gives the value of cookie named "tid".

The following variables are provided for convenience. They have higher precedence than the preceding global variables:

• @single = Has a value of "1" for single-post pages and "0" otherwise - e.g. "0"
• @url - The page URL (permalink) - e.g. "http://www.wpgallery.co.uk/wordpress-post-template/?"
• @ip - The client's IP address - e.g. "54.234.42.16"
• @cbip - IP address with "." replaced with "o" - e.g. "54o234o42o16"
• @id - The post's id - e.g. "4"

The following pre-defined variables deal with "escaping" issues:

• lcrl = "{"
• rcrl = "}"
• lsqb = "["
• rsqb = "]"
• pipe = "|"
• amps = "&"

User-Defined Variables and Functions

You can define your own PHP function for use in the templates. Simply add a file called 'xmlt-custom.php' to the plugin's folder. Here is a simple example of what would go in the file:

<?php

function xml_template_myfunc(&$vars)
{
  return "This is what myfunc is returning";
}

function xml_template_customfunctions(&$vars)
{
  $vars['myvar'] = "This is the value of myvar";
  $vars['myfunc()'] = "xml_template_myfunc";
}
?>

Look for other examples of function definitions at the bottom of the 'xmlt-rewrite.php' file.

How do I install the WordPress Post-Template plugin?

1. Unzip the zip file into your WordPress ".../wp-content/plugins" folder.
2. "Activate" the plugin on the dashboard "Plugins" page.

That's about it for now. Leave a comment if you need assistance.

Enjoy playing and working with this plugin!