glBanner - Banner Ad Plugin

The Banner plugin allows administrators to create banner ads which may be displayed in the header and footer. Banners may be assigned to Campaigns, which are assigned to a site member.

• glFusion v1.7.0 or newer
• lgLib plugin 1.0.5 or newer

The Banner Plugin uses the glFusion automated plugin installer. Simply upload the distribution using the glFusion plugin installer located in the Plugin Administration page.

The upgrade process is identical to the installation process, simply upload the distribution from the Plugin Administration page.

• Banners may be one of sevaral types:
  • Locally-uploaded image
  • Remotely-hosted image
  • Raw HTML or Javascript, such as Google Adsense
  • glFusion autotag
• Banners may be published for a limited period, or up to a maximum number of impressions or hits.
• Banners may be grouped into Campaigns. Campaigns may also have limited publishing periods and hit limits.
• Banners may be weighted to give priority to certain ads.
• Campaign owners may disable and enable specific banners within their campaigns.
• Banner Categories are used to determine placement of the banners. Categories may be enabled or disabled, and administrators may create their own categories.
  • 'header' and 'footer' category types are used to place banners in the header and footer templates.
  • 'block' category types are used to place banners in left or right blocks.
• Autotags are available for embedding ads in blocks, stories, and other content types.
  • banner:banner_id - Display a specific banner
  • randombanner:category_id - Display a random banner from within the category. The category ID is optional.
• Site admins may prevent banners from being displayed in certain cases. This is intended to help sites comply with the terms-of-service of their ad provider networks.
  • A list of IP addresses can be entered for hosts that will not be shown banners;
  • Banners may be blocked from appearing on administation pages;
  • Banners may be blocked from appearing to administrators or the ad's owner.
  • A CUSTOM_banner_control() function may be created by the administrator. This function must return 'true' if a banner is to be displayed; 'false' if not.
• Banner click and impression counts can be ignored for administrators or ad owners.

The Banner plugin consists of three main components: Banners, Campaigns and Categories.

The glFusion permission system is used for each of these items. Permissions for campaigns and categories behave slightly differently than for banners

The glFusion “AdBlock” feature is used to place banners in your site. The Banner plugin uses Categories to indicate which banners may be placed in the different possible ad blocks.

The administrator may disable the default categories or create other categories to have ads appear in blocks or embedded in other content.

Plugins that return template names that can display an ad block are shown on the Category edit screen. Some, like a Header, will logically only display one ad while others may display multiple ads interspersed with the content.

A unique identifier for the category, may be anything

The display name for the category

Deprecated, unused beginning with plugin version 0.3.0

This is just for you notes and is not displayed anywhere.

Select a topic, or “All”, where ads in this category should appear

Enter the maximum image size that can be uploaded for this category. This is to ensure that uploaded images conform to the spaces where banners will be placed.

Enable or disable this category.

Indicate if this category is used as a Centerblock on the home page

Each template name must be enabled. If this box is unchecked, the template variable will not be set.

For locations that allow multiple placements, select the position of the ad. For example, select “1” to have the banner appear after the first item, “2” to have it appear after the second, etc.

If this box is checked, then a banner on a list-type page will appear only once according to the Position. If left unchecked, then the Position is used to determine multiple placements, e.g. placing a banner after every 2nd item.

Check this box to have the banner also shown in the main content area, such as the story body, if supported by the content type.

To have a banner show only in the story index after every third story:

• Template: article
• Enabled: Checked
• Position: 3
• Show Once: Unchecked
• Show in Content: Unchecked

To have the banner also be displayed in the story content, check “Show In Content”

To display a banner only in the story content page and not in the index:

• Template: article
• Enabled: Checked
• Position: 0 (This disables the list display)
• Show Once: n/a
• Show in Content: Checked

To display a banner once in the article index, between the first and second listing:

• Template: article
• Enabled: Checked
• Position: 1
• Show Once: Checked
• Show in Content: Unchecked

One or more categories may also be selected to appear in the Centerblock. Refer to the Centerblock Options for help with this configuration.

Each banner must belong to exactly one category.

An ad campaign is a collection of ads. The campaign has its own settings for publication dates and maximum hits & impressions. If the campaign limit is reached for any of these, no banners within the campaign will be displayed.

Each banner must belong to one campaign. Upon installation a single campaign is created which is open to all site members.

The banner ID may be a descriptive text string, but each banner must have a unique ID.

The banner title describes the banner's purpose, customer, etc.

Select the category to determine the placement for this banner.

Select the campaign in which this banner is included.

Select the glFusion topic in which this banner will be displayed. Categories are also associated with topics but banners may be further restricted to a single topic.

Enter the dates between which the banner will be published. This can further restrict banners to only appear during a small window within the Campaign publication period.

Check this box to enable the banner's display. This allows the administrator to temporarily suspend a banner without having to delete it and possibly recreate it later.

Enter the number of hits and imressions already incurred for this banner, if any.

Enter the hit and impression limit for the banner. Enter zero if unlimited.

Enter the URL, including "https://", where visitors will be sent when they click on the banner. Leave this empty for a display-only banner, and for HTML or Javascript banners which will have the URL embedded in their code.

Select which window will be used to display the URL for the banner. “New Window” is recommended.

Select one of “Uploaded Image”, “Remotely-Hosted Image”, “HTML or Javascript”, or “Autotag”. The remaining options will depend upon this selection.

For uploaded image banners, select the file to upload here.

For remotely-hosted banners, enter the URL to the image file.

Enter the image dimensions. For uploaded banners the dimensions will be derived from the image file if not entered here. For remotely-hosted banners these values should be entered.

For HTML/Javascript banners enter the complete ad code, e.g. the code provided by Google Adsense.

Select a weight to give the banner. A higher value increases the chance of it being shown for a given page load.

Banners associated with a category of type “block” are automatically placed in the predefined banner blocks. The administrator may also create additional category types to appear in different blocks.

There are 2 blocks that are created during installation but are not enabled: Banners and Random Banner.

• Banners - This displays all banners with category type “block”
• Random Banner - This block displays a single randomly-chosen banner with category type “block”.

To create additional banner blocks:

1. Create a new banner category with a new type. For example, “special”.
2. Create a new PHP block. The function name is either “phpblock_banner_topic” or “phpblock_banner_topic_random, depending upon which type of block you'd like. The category type (“special” in this example) is supplied to the PHP function as a parameter:

   phpblock_banner_topic_random(special)

   This tells the plugin to search for only banners of type “special” for this block.

Starting with version 0.1.0, any template may contain banners. Simply create a variable named {banner_templatename} in the template and create a matching banner category named templatename. Banners assigned to this category will replace the corresponding template variable when the template is rendered. You may use any string other than “header” or “footer” as long as it contains only characters. You may also have more than one such banner in a template, each with different names (if you use the same name, all that will happen is you replicate the one banner).

The “templatename” that you use needs to match the template name used by glFusion, which isn't always obvious. For example, to have a banner appear in “featuredstorytext.thtml”, you'd specify “featuredarticle” as the template name. Some template names are:

The permissions system for campaigns and categories is a bit different than for normal content.

• Categories may only be edited by an administrator (with the banner.admin privilege).
• Campaigns may be edited by the designated owner, or by a user with the banner.admin privilege.
• The “Read” permission gives the user access to view ads within the campaign/category. Combining the campaign, category and banner permissions determines whether an ad will be displayed to a given user.
• The “Edit” permission gives the user the ability to submit an ad to the campaign or category.

By giving different permissions to different campaigns and categories, you can show certain types of ads only to certain user groups, such as “Anonymous”.

The category only has a “visibility” setting to indicate which users will see the banners.

Configuration Options are set by the Banner section in the site Configuration area. There is no config.php required unless you wish to override any other settings.

This controls whether the banner plugin will attempt to put “header” and “footer” banners in the templates. If this is set to “No”, or if there are no header or footer banners defined, nothing will appear in the site template.

The available template variables are:

• header_banner
• footer_banner

Determines whether regular site members may submit banners at all. Anonymous users can never submit banners.

• Yes : Site members may submit banners, subject to the submission queue setting below.
• No : Only members with the banner.submit privilege may submit banners. In this case, the submission queue setting is effectively not used.

Determines whether new submissions from regular site members are diverted to the submission queue for moderator approval.

• Yes : Submissions from members without banner.admin or banner.submit privileges are sent to the submission queue.
• No : Submissions from members are immediately published.

• Yes : A notification email will be sent to the site admin email address when a new ad has been submitted.
• No : Notifications are suppressed.

Determines what to do with banners that are owned by a site user that is deleted.

• Yes : When a site user account is deleted, all banners owned by that user are also deleted.
• No : The banner is kept and its ownership is changed to a user with the banner.admin privilege.

• Yes : When an ad is clicked, a new browser window or tab is opened for the target URL.
• No : The target URL is displayed in the same window as your site, causing your users to leave your site.

These settings control the maximum dimensinos of an uploaded image, and are meant only as a sanity check. The site administrator is responsible for making sure that the banner images, whether uploaded, remotely-hosted or provided by an ad service, will fit properly in their display locations.

Each banner also has a width and height value that is used to control the display of locally- and remotely-hosted images via the HTML “img” tags. No size control is exerted over ads provided by ad services.

This value is the default weight applied to new banner ads. The weight is used to give priority to some banners relative to others. For the individual banner a higher or lower weight value may be given which will cause the banner to appear more or less often, respectively.

These settings control who will actually see the ads, and for whom the impressions and click-throughs are counted. Typically, especially with ad-serving services such as Google Adsense, the administrator needs to be careful about causing false impressions or click-throughs. The Banner plugin has no control over measuring click-throughs in these cases, but can control whether an ad is displayed to certain classes of visitor.

This determines whether ads are shown at all on pages that fall under the site admin URL (http://www.example.com/admin).

Enter an array element for each IP address, or part of an address (such as “192.168”), for hosts that should not be shown ads.

• Yes : Site members will see ads for which they are the owner
• No : Site members will only see ads that they do not own.

• Yes : Administrators (members with the banner.admin privilege) will see ads.
• No : Ads will be hidden from administrators.

• Yes : When an ad owner clicks on his/her own ad, the click-through will be added to the ad's hit counter.
• No : Clicks made by an ad's owner are ignored. Recommended

• Yes : When an ad administrator clicks on his/her own ad, the click-through will be added to the ad's hit counter.
• No : Clicks made by an administrator are ignored. Recommended

• Yes : When an ad owner views his/her own ad, the ad's impression count will be incremented.
• No : Impressions made by an ad's owner are ignored. Recommended

• Yes : When an ad administrator views an ad, the ad's impression count will be incremented.
• No : Impressions made by an administrator are ignored. Recommended

These options control whether and how a banner will be displayed in a center block. At least one category must have its Centerblock option selected in order for these options to have any effect.

• Yes : Ads from selected categories will be displayed in a centerblock, subject to the other centerblock settings.
• No : No centerblock will be displayed.

Selecting “Yes” for this option will cause the banner ad to be displayed by itself as your site's home page.

Note that this option working correctly depends upon whether any other plugin has a similar option set. Depending upon the order in which plugins are loaded, the Banner plugin may never get a chance to become the home page.

This allows the administrator to select the position of the centerblock. Options are:

• Top of Page
• Following Featured Story
• Bottom of Page

These are the default permissions applied to new ads. They may be modified during the ad submission.

• The block banner doesn't correctly search the database. Changed in SVN, now uses Banner::GetBanner and passes options to it to limit the search and handle one or more returns.

• Centerblock doesn't work. The configuration variable name controlling the centerblock is mismatched between the database and the code. Fixed in SVN for version 0.1.1.
  
  To implement the fix, edit line 129 in functions.inc as shown:
  

  --- functions.inc.010	2009-12-09 07:46:32.000000000 -0800
  +++ functions.inc	2009-12-09 07:46:15.000000000 -0800
  @@ -126,7 +126,7 @@
  
       // If centerblock not enabled, or just for homepage and
       // we're not on the homepage, just return
  -    if ($_CONF_BANR['cb_enabled'] == 0 ||
  +    if ($_CONF_BANR['cb_enable'] == 0 ||
               ($CONF_BANR['cb_home'] == 1 && ($page > 1 || $topic != ''))) {
           return '';
       }

• Banners are not shown with stories when the topics match
  Banner::GetBanner() does not check for category.topic='all' when it searches for banners. Updated banner.class.php for inclusion with release 0.1.1
  

  --- banner.class.php.010	2009-12-14 15:23:14.000000000 -0800
  +++ banner.class.php	2009-12-14 14:33:26.000000000 -0800
  @@ -648,7 +648,7 @@
                       break;
                   case 'topic':
                       // different variable name used in DB
  -                    $sql_cond .= " AND c.tid = '$value'";
  +                    $sql_cond .= " AND (c.tid = '$value' OR c.tid='all')";
                       break;
                   case 'limit':
                       $limit_clause = " LIMIT $value";

• Plugin crashes under PHP 4
  The banner.class.php and category.class.php files use “public” variable declarations. This has been fixed in SVN for version 0.1.1. Extract these new files into your plugin_dir/banner/classes directory:
  • banner.class.php.gz
  • category.class.php.gz

One of the changes is to the glFusion-style date fields in the banner form. A misplaced parentheses causes an error if you use 24-hour time.

Around line 1175 of banner.class.php, replace this:

if ($_CONF['hour_mode'] == 24) {
    $T->set_var('start_hour_options',
        COM_getHourFormOptions(date('H', $startdt, 24)));
    $T->set_var('end_hour_options',
        COM_getHourFormOptions(date('H', $enddt, 24)));
} else {

with this:

 if ($_CONF['hour_mode'] == 24) {
    $T->set_var('start_hour_options',
        COM_getHourFormOptions(date('H', $startdt), 24));
    $T->set_var('end_hour_options',
        COM_getHourFormOptions(date('H', $enddt), 24));
} else {

See that one of the closing parentheses is moved from the end of the COM_getHourFormOptions lines to right after the date variable name.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This plugin is based on the Banner plugin for Geeklog by Hiroshi Sakuramoto, Copyright (C) 2009 by Hiroshi Sakuramoto and Ivy. See http://www.ivywe.co.jp