NewsFeaturesDownloadsDevelopmentSupportAbout Us

Plugin ads

From LifeType Wiki


Name: ads

Latest version: 20070304

Download link: to be define

License: non-free, to be defined

Author: The Lifetype project

Description

This plugin allows to define an indefinite number of so-called blocks, which are nothing more than dynamic transformations of rendered templates that are applied before the content is sent to the client. This allows to for example ad top banners, advertisement blocks or perform any kind of transformation to the content. Moreover, each of the transformations can be applied to a different blog or group of blogs, allowing for even greater flexibility.

The most straightforward use of this plugin is to display a top banner or ads in all blogs, and hence the name "ads".

Configuration

Enabling the plugin

Once unzipping the contents of the plugin's ZIP file in the plugins/ folder, the plugin must be activated via the user interface. All the plugin pages can be found under Administration->Ads, and the switch that toggles the activation of the plugin is located in Administration->Ads->Configure Ads.

Adding new blocks

New blocks can be added via the Administration->Ads->Add New Block page. For each one of the blocks, the following properties must be defined:

  • Name: this is the string that will be used to identify the block. It should be unique.
  • Mode: this parameter defines which blocks should be affected by this block. There are three different possibilities:
    • All: This block will affect all blogs in the site.
    • Only blogs in the list: Only the blogs that are selected in the list that appears below this setting will be affected.
    • All blogs excepts the ones in the list: The block will affect all blogs in the site except the ones in the list below. If you wanted to force all blogs to show ads or a banner except those ones that pay a fee or have made a donation, this is the option you should use, as you would be listing here all the blogs that should not include those ads or banner.
  • Position: This defines where the markup as defined in the code text area should appear. There are only three possibilities available:
    • Top: This tells the plugin to add the content defined in the code text area at the top of the page. To be precise, the plugin will append the code just next to the <body> tags to make sure that it appears at the top. If you're trying to add a top banner to all blogs in your site, this is the one you want to use.
    • Bottom: This tells the plugin to add the content defined in the code text area at the bottom of the page. To be precise, the plugin will append the code just next to the </body> tag to make sure that it appears at the bottom.
    • Custom: This allows for custom positioning and transformation via specialized PHP code, please see the Notes section below for more information.
  • Code: This is the text that will be added to pages by the plugin. The place where this code will be added depends on the value of the Location attribute. The code added here is not restricted to HTML, Javascript code can also be added. However, Smarty code is not allowed here because at the point in time when the plugin acts, the template has already been parsed and rendered by Smarty so there is no chance to use Smarty code any more.

If the mode attribute is not set to All, an extra list will appear to define to which blogs the block should apply (or to define to which blogs the block should not apply, depending on the value of the mode parameter)

Notes

This plugin and caching

Caching a template also affects this plugin (and all plugins in general), so highly dynamic content will be affected by this as it will be generated once and then cached until next time the content is refreshed.

Please bear this limitation in mind when implementing your own custom blocks.

Adding a top banner to all blogs

Adding a simple HTML-only top banner to all blogs just became extremely simple with this plugin.

Create a new block, let's call it "topbanner". Make sure that mode is set to All, that Position is set to Top and that the Code text area has the following code:

<div style="text-align:left;background-color:#44dead;border:0px;margin:0px;padding:0px;position:absolute;top:0px;left:0px;width:100%;">
 <div style="float:left">
  <span style="font-size:14px">Here goes your service title</span>
 </div>
 <div style="float:right">
  <a href="http://www.yoursite.com/summary.php">Summary</a> |
  <a href="http://www.yoursite.com/admin.php">Log-in</a>
 </div>
</div>

The code above provides a very simple yet unobtrusive topbar absolutely located at the top left corner of the page in a very similar way to what Blogger.com does. If you wanted to include the Google ads code in there instead of a static topbar, then you should include the Google Ads Javascript code generated for your site in the Code text area instead of the HTML code provided above.

Developing custom blocks

The example above described the steps and HTML code necessary to include a very simple top bar at the top of each one of our blogs. However useful, this approach is rather unflexible because we're limited to static content (it's not possible to include Smarty or native PHP code in the Code text area) and because we're only allowed to choose between two positions in the page, either top or bottom.

By using Custom as the value for the Positioning attribute, the plugin is offering us the possibility to provide our own custom PHP code to implement the transformation. While this may scare non-technical users, the possibilities offered by this approach are endless.

In the following example, we will create a custom block that will replace the keywords "{ads}", that will be placed in each one of the user templates. This of course assumes that in the current site, users are not able to edit their own templates.

Creating the block

In order to create block with custom PHP code, create a new block and call it "mycustomblock". Make sure that it applies to All blogs and that Position is Custom. The Code text area doesn't really matter, we will provide our own code in the custom code.

Writing the code

The next step consists of writing the code for our new custom block. The class implementing the custom block should be called mycustomblock.class.php and should be placed in the plugins/ads/customblocks folder. The rule is that classes implementing custom blocks should be called with the exact same name that the block plus the .class.php extension, so a block called xxx should end up with a class called xxx.class.php.

The reason for this is to facilitate upgrading to newer releases of the plugin. If all custom code is isolated in their own classes, moving it to a new version of the plugin is as easy as moving the classes to the new version.

Classes implementing custom blocks should implement the interface of the CustomBlock class (located under plugins/ads/customblocks/customblock.class.php) This class contains one single method, CustomBlock::process() that implements the whole block logic. In our case the logic is very simple:

class MyCustomBlock extends CustomBlock
{
 function process($content, $block, $blog, $eventInfo ) 
 {
  return( str_replace( "{ads}", "here goes the code for your ads", $content );
 }
}

In this case the implementation was very easy, but since this is PHP code, all sorts of complex logic can be implemented.

With regards to the CustomBlock::process() method, it provides the following parameters:

  • $content: This is the content on which the code should perform its transformations.
  • $block: This is an object of type AdBlock, which represents the ad block currently being processed.
  • $blog: This is an object of type BlogInfo, which represents the blog currently being processed.
  • $eventInfo: This is an associative array which contains the information that was provided by the plugin manager to the plugins. It contains the following values:
    • from: This contains the name of the class that originally threw the event.
    • template: This contains the name of the template file currently being processed. We could potentially use this value to display a custom for all template pages except "postandcomments" or viceversa.
    • content: This is the original value of the content when the plugin started to process blocks. By the time our custom block is executed, there could have potentially been several blocks already executed so please use the content as provided by the $content parameter and not whatever may be in this array.

The plugin expects this class to return a string containing the modified content.