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