---------
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 impressions
    * 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 Impressions 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', 'jquery', 'iframe', and 'raw'.  When using the 'javascript',
  'jquery', and 'iframe' methods, 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'.

When displaying advertisements using the JavaScript, jQuery, and IFrame methods
impressions are tracked each time the script is loaded.  When displaying
advertisements using the Raw method, impressions are tracked through the use
of a hidden 1x1 pixel image that is displayed along with each advertisement.

The click_filter module can be enabled to filter out the following invalid
clicks:
    * Duplicate clicks from the same IP address
    * Clicks from the owner of the advertisement
    * Clicks from any user with 'filter clicks' permissions.
    * Clicks from any users in which the word "bot" is contained in their
      HTTP_USER_AGENT

This means that when the click_filter module is enabled, all clicks by UID 1
will be filtered because Drupal will automatically assign all permissions to
this user, including the 'filter clicks' permisison.  The click_filter module
currently has no configuration options beyond the 'filter clicks' permission.