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.1.2 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
• 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

Categories indicate the placement of the banners. Three categories are provided at installation and may not be deleted:

The administrator may disable the default categories or create other categories to have ads appear in blocks or embedded in other content. Other category types may be used for additional blocks or with autotags, for example. The Header and Footer categories are fixed in their purpose.

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.

Banners under the “Header” and “Footer” categories (or any category of type “header” or “footer”) are automatically placed in the glFusion template, replacing the variables {banner_header} and {banner_footer}, respectively. Most likely you'll want to add {banner_header} in the header.thtml file and {banner_footer} in footer.thtml, but the plugin actually has no knowledge of where the banners are placed.

Also, if you do create Header or Footer banners, but do not implement the template variables, you'll need to turn off “Show Banners in Templates” in the plugin online configuration. Since the plugin has no way of knowing whether the template variables are actually defined, the impression count will quickly become inaccurate as the plugin thinks that it is constantly displaying banners when it isn't.

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”.

Banner permissions follow more closely the traditional glFusion security model:

• “Read” gives the user access to view an ad
• “Edit” gives the user access to modify or delete an ad.

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