---------
Overview:
---------
The ad module is a powerful advertising system for Drupal-powered websites. It
supports the random display and tracking of graphical (banner), text and raw
html ads. Ads can easily be displayed in themes, blocks, or embedded in site
content. The module records comprehensive statistics about when and how often
ads are viewed and clicked, including a plug-in module for generating graphical
time-based reports. Ads can be assigned to multiple owners, each of which can
be assigned their own set of permissions. Installation is simple by design. An
API is provided allowing the development of additional functionality and
integration with other Drupal modules.
Features:
* auto-generated ad blocks supporting a configurable number of ads
* automatically or manually embed ads into site content
* collection of comprehensive statistics allowing time-based reporting and
analysis
* tracking of when and where ads are clicked, by which user and which IP
* advertisements can have multiple owners
* granular per-advertisement/per-owner permissions system
* activation/expiration scheduling based on time, clicks or views
* an ad_image plug-in for image (aka banner) ads
* an ad_text plug-in for simple text ads
* an ad_html plug-in for raw html ads
* an externally maintained ad_geoip plug-in provides support for
geotargeting ads
* an ad_report plug-in for basic graphical reports
* an ad_notify plug-in for scheduling automatic email notifications
* an ad_remote plug-in for hosting ads on remote (non-Drupal) websites
* an administrative statistics overview page
* support for any number of configurable ad groups, utilizing Drupal's
taxonomy (category) subsystem
* display ads based on node ids (nids) or taxonomy terms (categories)
* file-based caching for improved performance
* memcache-based caching for improved performance
* support for external caching methods
* MySQL and PostgreSQL support
------
Usage:
------
Installation and requirements information can be found within the INSTALL.txt
file included with this module.
-------------
Creating ads:
-------------
Once the ad module is properly installed an enabled, you can create
advertisements by visiting 'create content' on your website and choosing
'advertisement' as the content type. If you have enabled multiple ad type
modules, you can select one of them from the resulting menu, such as 'image
advertiesment' or 'text advertisement'.
Text ads:
---------
Text ads are very simple, requiring that you fill out only three fields of
information. First, you need to specify the Destination URL where you want
people to be redirected when they click on your text ad. Second, you enter
the a header for your ad. The header will be linked to the Destination URL.
Finally, you need to specify the body of your ad.
Image ads:
----------
Image ads or only slightly more complicated than text ads. They depend on
the drupal core Upload module for managing the actual images. As with text
ads, you first need to specify the Destination URL where you want people to
be redirected when they click on your image ad. Second, you can optoinally
enter some Mouseover text. If you enter text in the mouseover field this
text will be displayed when people hover their mouse pointer over the
advertisement. Finally, you need to scroll down to the File attachements
section of the page and click the Browser button to select your image, then
click Attach to upload the image.
HTML ads:
---------
HTML ads allow you to easily define your own custom ad type by simply pasting
in a block of HTML code. At this time, however, the ad module is unable to
track when html ads are clicked.
Ad groups:
----------
Ads can be organized into groups. For example, you may have a group called
"Text Ads" and another group called "Image Ads." You could then assign your
text ads to the "Text Ads" group, and your image ads to your "Image Ads"
groups. (This is not required, it is perfectly valid to include both image
ads and text ads in the same group.) When displaying ads, you typically tell
the ad module to display ads from a certain group and then the ad module
randomly selects an active ad from the specified group. Each ad can be a
member of any number of groups.
Ad status:
----------
There are several states that an ad can exist in. An ad in the Pending state
is one that has recently been uploaded and is waiting to be approved by a
privileged user. An ad in the Approved state is one that has been approved
by a privileged user but is not actively being displayed, the ad could be
waiting on an autoactivation event. An ad in the Active state is being
actively displayed. An ad in the Offline state is approved but is currently
not being displayed. An ad in the Unpublished state means that the ad node
was unpublished so the ad is not any longer being displayed. An ad in the
Expired state is no longer being displayed. An ad in the Denied state means
it was not approved by the site administrator.
Scheduling:
-----------
If you put an ad into the Approved state and then enter a date and time in the
Automatically Activate Ad field, the ad will be automatically activated
on the date and time specified. This feature requires that cron be functional
on your website. If you enter a date and time in the Automatically Expire Ad
field, the ad will be automatically expired on the date and time specified.
Again, this feature requires that cron be functional on your website.
If you enter a number into the Maximum Views field, the ad will be
automatically expired once it has been displayed this number of times.
If you enter a number into the Maximum Clicks field, the ad will be
automatically expired once it has been clicked this number of times.
---------------
Displaying ads:
---------------
There are many ways to display ads with the ad module. The simplest way
is to enable one of the automatically generated ad blocks. It is also possible
to use the ad_embed module to automatically embed ads within your site content.
And you can even display ads from within the PHP of your theme or another
module.
----------
Ad blocks:
----------
The ad module automatically generates on ad block for every ad group that you
create. For example, if you visit "Administer >> Site building >> Blocks"
you will find a block named "ad group: default". If you enable this block,
it will display a random ad from all active ads in the default group.
You can optionally configure the block to display more than one ad at a time
by clicking the 'configure' link on the block administration page.
-------------
Embedded ads:
-------------
If you enabled the ad_embed module, it is possible to embed ads into your
site content. To configure the ad_embed module go to "Administer >> Content
Management >> Ads >> Settings >> Embedded ads".
If you wish to manually embed ads in your content, check the box next to
"Replace ad bracket tags" or "Replace ad comment tags". This will cause the
ad_embed module to replace embedded [[add]] or <!--ad--> tags respectively.
Instructions on how to specify specific ad groups or even specific ads and
how many ads to display at a time can be found by visiting "Administer >>
Help >> Embed".
If you wish to automatically embed ads in your content, configure this on a
per-content-type basis in the lower configuration section.
embeded ads".
------------------------
Displaying ads from PHP:
------------------------
To display an ad from within PHP code, make a call to the ad() function.
You can optionally specify an ad group, the number of ads to display, and
several other options. For example, to display one random ad from all ads
that have not been assigned to any group you don't have to pass in any
parameters:
<?php print ad(); ?>
To display two ads from all ads that have not been assigned to any group
you would execute the following code:
<?php print ad(0, 2); ?>
(The first parameter specifies the ad group to display ads from. By
specifying 0, we are telling the ad module to display ads that are not
assigned to any group. The second parameter specifies the number of ads
to display at one time.)
To randomly display an ad from a specific group of nids, for example with
the node ID 69 or 76, you would pass in the following parameters:
<?php print ad(NULL, 1, array('nids' => '69,76')); ?>
(When specifying specific nids, any specified ad group is ignored, so we
leave the first parameter as NULL. The second parameter causes only one
ad to be displayed at a time. And the third parameter is an array that
tells the ad module to randomly display either ad 69 or ad 76.)
To display and ad randomly selected from multiple groups you can simply
specify multiple groups separated by commas. For example, to display 3
ads from groups 24, 56 and 98 you would pass in the following parameters:
<?php print ad('24,56,98', 2); ?>
You can also specify how to display a given ad. Current display methods are
'javascript' and 'raw'. When using the 'javascript' method, ads will
randomly change even when the Drupal pagecache is enabled. When using the
'raw' method, ads will only change when the Drupal pagecache is flushed.
To force one ad with a tid of 76 to display using JavaScript you would pass
in the following parameters:
<?php print ad(76, 1, array('method' => 'javascript'));
To force two ads with a tid of 101 or 102 to display using the Raw method
you would pass in the following parameters:
<?php print ad('101,102', 76, array('method' => 'raw'));
------------
Theming ads:
------------
All ads are wrapped in the following tags:
<div class="advertisement" id="group-#"></div>
All ads are in the same "advertisement" class. Each ad group gets a unique
id. This makes it possible to create generic advertisement formatting as
well as specific advertisement formatting.
CSS Example 1:
--------------
This sample code can be added to your theme's custom style.css. It adds
padding to advertisements, wrapping them in a dashed border and giving
them a background color. It also adds the text "Advertisement:" above
the ad:
.advertisement {
padding: 5px;
border: dashed;
background-color: #ffd;
}
.advertisement:before {
content: "Advertisement:";
}
CSS Example 2:
--------------
Here is more sample code that could be added to your theme's custom
style.css. It will cause multiple image ads to be displayed horizontally
one beside the other (space permitting), rather than vertically one
below the other. The ads are aligned to the left side of the screen,
if you'd prefer them to be aligned to the right side of the screen change
the word "left" to "right" in the snippet:
.image-advertisement {
float: left;
padding: 3px;
}
-------------------
Ad module settings:
-------------------
The ad module and related modules provide a number of configuration options.
----------------
Global settings:
----------------
The ad module allows you to specify some global settings at "Administer >>
Content management >> Ads >> Settings >> Global settings".
Even if you do not plan to make any changes, you should visit this page at
least one time as the ad module will perform a series of sanity tests when
you visit this page, alerting you to any installation problems.
This page begins by displaying the path to serve.php. If you see an error
here, then the ad module is not properly installed. Review the directions
in INSTALL.txt to properly install the ad module.
In the General section you can specify what happens when an advertisement is
clicked. For example, you can choose to have the resulting Destination URL
opened in the same browser window, or in a new browser window. You can also
enable the "nofollow" check box causing ads served by the ad module to
include rel="nofollow" in automatically generated links. You can select
to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML.
Finally, you can disable URL validation, and enable advertisement filtering.
Checking 'Filter ads' allows you to apply Drupal's standard input filters
to your advertisements. If you enable this option, be sure to apply a
compatible filter that doesn't strip away the <div> and other tags used by
the various advertisement types.
The next section allows you to configure IFrames, if you are using them to
display advertisements.
For better performance, you can also enable a cache. At this time there is
only a file cache available. When the file cache is enabled, ads are quickly
displayed from a cache file without bootstrapping Drupal. On very busy
websites you may need to increase the number of cache files to prevent
cache file contention.
---------
Text ads:
---------
The ad_text module allows you to specify some minimum and maximum lengths for
text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
----------
Image ads:
----------
The ad_image module allows you to specify some image constraints on a
per-group basis at "Administer >> Content management >> Ads >> Settings >>
Image ads".
-------------
Embedded ads:
-------------
Manually and automatically embedded ads can be configured at "Administer >>
Content management >> Ads >> Settings >> Embedded ads".
-----------
Statistics:
-----------
The ad module tracks how often each ad is viewed and clicked. The statistics
are tracked to an hourly granularity.
When an advertisement is first enabled, the statistics for 'This hour', 'Today',
'Last seven days', 'This month', 'This year' and 'All time' will all be the
same. When available, statistics will also include 'Last hour', 'Yesterday',
'Last month', and 'Last year'.
View source
- ---------
- Overview:
- ---------
- The ad module is a powerful advertising system for Drupal-powered websites. It
- supports the random display and tracking of graphical (banner), text and raw
- html ads. Ads can easily be displayed in themes, blocks, or embedded in site
- content. The module records comprehensive statistics about when and how often
- ads are viewed and clicked, including a plug-in module for generating graphical
- time-based reports. Ads can be assigned to multiple owners, each of which can
- be assigned their own set of permissions. Installation is simple by design. An
- API is provided allowing the development of additional functionality and
- integration with other Drupal modules.
-
- Features:
- * auto-generated ad blocks supporting a configurable number of ads
- * automatically or manually embed ads into site content
- * collection of comprehensive statistics allowing time-based reporting and
- analysis
- * tracking of when and where ads are clicked, by which user and which IP
- * advertisements can have multiple owners
- * granular per-advertisement/per-owner permissions system
- * activation/expiration scheduling based on time, clicks or views
- * an ad_image plug-in for image (aka banner) ads
- * an ad_text plug-in for simple text ads
- * an ad_html plug-in for raw html ads
- * an externally maintained ad_geoip plug-in provides support for
- geotargeting ads
- * an ad_report plug-in for basic graphical reports
- * an ad_notify plug-in for scheduling automatic email notifications
- * an ad_remote plug-in for hosting ads on remote (non-Drupal) websites
- * an administrative statistics overview page
- * support for any number of configurable ad groups, utilizing Drupal's
- taxonomy (category) subsystem
- * display ads based on node ids (nids) or taxonomy terms (categories)
- * file-based caching for improved performance
- * memcache-based caching for improved performance
- * support for external caching methods
- * MySQL and PostgreSQL support
-
-
- ------
- Usage:
- ------
- Installation and requirements information can be found within the INSTALL.txt
- file included with this module.
-
-
- -------------
- Creating ads:
- -------------
- Once the ad module is properly installed an enabled, you can create
- advertisements by visiting 'create content' on your website and choosing
- 'advertisement' as the content type. If you have enabled multiple ad type
- modules, you can select one of them from the resulting menu, such as 'image
- advertiesment' or 'text advertisement'.
-
- Text ads:
- ---------
- Text ads are very simple, requiring that you fill out only three fields of
- information. First, you need to specify the Destination URL where you want
- people to be redirected when they click on your text ad. Second, you enter
- the a header for your ad. The header will be linked to the Destination URL.
- Finally, you need to specify the body of your ad.
-
- Image ads:
- ----------
- Image ads or only slightly more complicated than text ads. They depend on
- the drupal core Upload module for managing the actual images. As with text
- ads, you first need to specify the Destination URL where you want people to
- be redirected when they click on your image ad. Second, you can optoinally
- enter some Mouseover text. If you enter text in the mouseover field this
- text will be displayed when people hover their mouse pointer over the
- advertisement. Finally, you need to scroll down to the File attachements
- section of the page and click the Browser button to select your image, then
- click Attach to upload the image.
-
- HTML ads:
- ---------
- HTML ads allow you to easily define your own custom ad type by simply pasting
- in a block of HTML code. At this time, however, the ad module is unable to
- track when html ads are clicked.
-
- Ad groups:
- ----------
- Ads can be organized into groups. For example, you may have a group called
- "Text Ads" and another group called "Image Ads." You could then assign your
- text ads to the "Text Ads" group, and your image ads to your "Image Ads"
- groups. (This is not required, it is perfectly valid to include both image
- ads and text ads in the same group.) When displaying ads, you typically tell
- the ad module to display ads from a certain group and then the ad module
- randomly selects an active ad from the specified group. Each ad can be a
- member of any number of groups.
-
- Ad status:
- ----------
- There are several states that an ad can exist in. An ad in the Pending state
- is one that has recently been uploaded and is waiting to be approved by a
- privileged user. An ad in the Approved state is one that has been approved
- by a privileged user but is not actively being displayed, the ad could be
- waiting on an autoactivation event. An ad in the Active state is being
- actively displayed. An ad in the Offline state is approved but is currently
- not being displayed. An ad in the Unpublished state means that the ad node
- was unpublished so the ad is not any longer being displayed. An ad in the
- Expired state is no longer being displayed. An ad in the Denied state means
- it was not approved by the site administrator.
-
- Scheduling:
- -----------
- If you put an ad into the Approved state and then enter a date and time in the
- Automatically Activate Ad field, the ad will be automatically activated
- on the date and time specified. This feature requires that cron be functional
- on your website. If you enter a date and time in the Automatically Expire Ad
- field, the ad will be automatically expired on the date and time specified.
- Again, this feature requires that cron be functional on your website.
-
- If you enter a number into the Maximum Views field, the ad will be
- automatically expired once it has been displayed this number of times.
-
- If you enter a number into the Maximum Clicks field, the ad will be
- automatically expired once it has been clicked this number of times.
-
-
- ---------------
- Displaying ads:
- ---------------
- There are many ways to display ads with the ad module. The simplest way
- is to enable one of the automatically generated ad blocks. It is also possible
- to use the ad_embed module to automatically embed ads within your site content.
- And you can even display ads from within the PHP of your theme or another
- module.
-
- ----------
- Ad blocks:
- ----------
- The ad module automatically generates on ad block for every ad group that you
- create. For example, if you visit "Administer >> Site building >> Blocks"
- you will find a block named "ad group: default". If you enable this block,
- it will display a random ad from all active ads in the default group.
-
- You can optionally configure the block to display more than one ad at a time
- by clicking the 'configure' link on the block administration page.
-
- -------------
- Embedded ads:
- -------------
- If you enabled the ad_embed module, it is possible to embed ads into your
- site content. To configure the ad_embed module go to "Administer >> Content
- Management >> Ads >> Settings >> Embedded ads".
-
- If you wish to manually embed ads in your content, check the box next to
- "Replace ad bracket tags" or "Replace ad comment tags". This will cause the
- ad_embed module to replace embedded [[add]] or tags respectively.
- Instructions on how to specify specific ad groups or even specific ads and
- how many ads to display at a time can be found by visiting "Administer >>
- Help >> Embed".
-
- If you wish to automatically embed ads in your content, configure this on a
- per-content-type basis in the lower configuration section.
- embeded ads".
-
- ------------------------
- Displaying ads from PHP:
- ------------------------
- To display an ad from within PHP code, make a call to the ad() function.
- You can optionally specify an ad group, the number of ads to display, and
- several other options. For example, to display one random ad from all ads
- that have not been assigned to any group you don't have to pass in any
- parameters:
-
-
- To display two ads from all ads that have not been assigned to any group
- you would execute the following code:
-
-
- (The first parameter specifies the ad group to display ads from. By
- specifying 0, we are telling the ad module to display ads that are not
- assigned to any group. The second parameter specifies the number of ads
- to display at one time.)
-
- To randomly display an ad from a specific group of nids, for example with
- the node ID 69 or 76, you would pass in the following parameters:
- '69,76')); ?>
-
- (When specifying specific nids, any specified ad group is ignored, so we
- leave the first parameter as NULL. The second parameter causes only one
- ad to be displayed at a time. And the third parameter is an array that
- tells the ad module to randomly display either ad 69 or ad 76.)
-
- To display and ad randomly selected from multiple groups you can simply
- specify multiple groups separated by commas. For example, to display 3
- ads from groups 24, 56 and 98 you would pass in the following parameters:
-
-
- You can also specify how to display a given ad. Current display methods are
- 'javascript' and 'raw'. When using the 'javascript' method, ads will
- randomly change even when the Drupal pagecache is enabled. When using the
- 'raw' method, ads will only change when the Drupal pagecache is flushed.
- To force one ad with a tid of 76 to display using JavaScript you would pass
- in the following parameters:
- 'javascript'));
-
- To force two ads with a tid of 101 or 102 to display using the Raw method
- you would pass in the following parameters:
- 'raw'));
-
- ------------
- Theming ads:
- ------------
- All ads are wrapped in the following tags:
-
-
- All ads are in the same "advertisement" class. Each ad group gets a unique
- id. This makes it possible to create generic advertisement formatting as
- well as specific advertisement formatting.
-
- CSS Example 1:
- --------------
- This sample code can be added to your theme's custom style.css. It adds
- padding to advertisements, wrapping them in a dashed border and giving
- them a background color. It also adds the text "Advertisement:" above
- the ad:
-
- .advertisement {
- padding: 5px;
- border: dashed;
- background-color: #ffd;
- }
-
- .advertisement:before {
- content: "Advertisement:";
- }
-
- CSS Example 2:
- --------------
- Here is more sample code that could be added to your theme's custom
- style.css. It will cause multiple image ads to be displayed horizontally
- one beside the other (space permitting), rather than vertically one
- below the other. The ads are aligned to the left side of the screen,
- if you'd prefer them to be aligned to the right side of the screen change
- the word "left" to "right" in the snippet:
-
- .image-advertisement {
- float: left;
- padding: 3px;
- }
-
-
- -------------------
- Ad module settings:
- -------------------
- The ad module and related modules provide a number of configuration options.
-
- ----------------
- Global settings:
- ----------------
- The ad module allows you to specify some global settings at "Administer >>
- Content management >> Ads >> Settings >> Global settings".
-
- Even if you do not plan to make any changes, you should visit this page at
- least one time as the ad module will perform a series of sanity tests when
- you visit this page, alerting you to any installation problems.
-
- This page begins by displaying the path to serve.php. If you see an error
- here, then the ad module is not properly installed. Review the directions
- in INSTALL.txt to properly install the ad module.
-
- In the General section you can specify what happens when an advertisement is
- clicked. For example, you can choose to have the resulting Destination URL
- opened in the same browser window, or in a new browser window. You can also
- enable the "nofollow" check box causing ads served by the ad module to
- include rel="nofollow" in automatically generated links. You can select
- to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML.
- Finally, you can disable URL validation, and enable advertisement filtering.
-
- Checking 'Filter ads' allows you to apply Drupal's standard input filters
- to your advertisements. If you enable this option, be sure to apply a
- compatible filter that doesn't strip away the
and other tags used by
- the various advertisement types.
-
- The next section allows you to configure IFrames, if you are using them to
- display advertisements.
-
- For better performance, you can also enable a cache. At this time there is
- only a file cache available. When the file cache is enabled, ads are quickly
- displayed from a cache file without bootstrapping Drupal. On very busy
- websites you may need to increase the number of cache files to prevent
- cache file contention.
-
- ---------
- Text ads:
- ---------
- The ad_text module allows you to specify some minimum and maximum lengths for
- text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
-
- ----------
- Image ads:
- ----------
- The ad_image module allows you to specify some image constraints on a
- per-group basis at "Administer >> Content management >> Ads >> Settings >>
- Image ads".
-
- -------------
- Embedded ads:
- -------------
- Manually and automatically embedded ads can be configured at "Administer >>
- Content management >> Ads >> Settings >> Embedded ads".
-
-
- -----------
- Statistics:
- -----------
- The ad module tracks how often each ad is viewed and clicked. The statistics
- are tracked to an hourly granularity.
-
- When an advertisement is first enabled, the statistics for 'This hour', 'Today',
- 'Last seven days', 'This month', 'This year' and 'All time' will all be the
- same. When available, statistics will also include 'Last hour', 'Yesterday',
- 'Last month', and 'Last year'.