Mercurial > defr > drupal > ad

comparison documentation/README.txt @ 1:948362c2a207 ad

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update advertisement
author pierre
date Thu, 02 Apr 2009 15:28:21 +0000
parents d8a3998dac8e
children 416ea999ed76
comparison
equal deleted inserted replaced
0:d8a3998dac8e 1:948362c2a207
1 --------- 1 ---------
2 Overview: 2 Overview:
3 --------- 3 ---------
4 The ad module is a powerful advertising system for Drupal-powered websites. It 4 The ad module is a powerful advertising system for Drupal-powered websites. It
5 supports the random display and tracking of graphical (banner), text and raw 5 supports the random display and tracking of graphical (banner), text and raw
6 html ads. Ads can easily be displayed in themes, blocks, or embedded in site 6 html ads. Ads can easily be displayed in themes, blocks, or embedded in site
7 content. The module records comprehensive statistics about when and how often 7 content. The module records comprehensive statistics about when and how often
8 ads are viewed and clicked, including a plug-in module for generating graphical 8 ads are viewed and clicked, including a plug-in module for generating graphical
9 time-based reports. Ads can be assigned to multiple owners, each of which can 9 time-based reports. Ads can be assigned to multiple owners, each of which can
10 be assigned their own set of permissions. Installation is simple by design. An 10 be assigned their own set of permissions. Installation is simple by design. An
11 API is provided allowing the development of additional functionality and 11 API is provided allowing the development of additional functionality and
12 integration with other Drupal modules. 12 integration with other Drupal modules.
13 13
14 Features: 14 Features:
15 * auto-generated ad blocks supporting a configurable number of ads 15 * auto-generated ad blocks supporting a configurable number of ads
16 * automatically or manually embed ads into site content 16 * automatically or manually embed ads into site content
17 * collection of comprehensive statistics allowing time-based reporting and 17 * collection of comprehensive statistics allowing time-based reporting and
18 analysis 18 analysis
19 * tracking of when and where ads are clicked, by which user and which IP 19 * tracking of when and where ads are clicked, by which user and which IP
20 * advertisements can have multiple owners 20 * advertisements can have multiple owners
21 * granular per-advertisement/per-owner permissions system 21 * granular per-advertisement/per-owner permissions system
22 * activation/expiration scheduling based on time, clicks or impressions 22 * activation/expiration scheduling based on time, clicks or impressions
23 * an ad_image plug-in for image (aka banner) ads 23 * an ad_image plug-in for image (aka banner) ads
24 * an ad_text plug-in for simple text ads 24 * an ad_text plug-in for simple text ads
25 * an ad_html plug-in for raw html ads 25 * an ad_html plug-in for raw html ads
26 * an externally maintained ad_geoip plug-in provides support for 26 * an externally maintained ad_geoip plug-in provides support for
27 geotargeting ads 27 geotargeting ads
28 * an ad_report plug-in for basic graphical reports 28 * an ad_report plug-in for basic graphical reports
29 * an ad_notify plug-in for scheduling automatic email notifications 29 * an ad_notify plug-in for scheduling automatic email notifications
30 * an ad_remote plug-in for hosting ads on remote (non-Drupal) websites 30 * an ad_remote plug-in for hosting ads on remote (non-Drupal) websites
31 * an administrative statistics overview page 31 * an administrative statistics overview page
81 track when html ads are clicked. 81 track when html ads are clicked.
82 82
83 Ad groups: 83 Ad groups:
84 ---------- 84 ----------
85 Ads can be organized into groups. For example, you may have a group called 85 Ads can be organized into groups. For example, you may have a group called
86 "Text Ads" and another group called "Image Ads." You could then assign your 86 "Text Ads" and another group called "Image Ads." You could then assign your
87 text ads to the "Text Ads" group, and your image ads to your "Image Ads" 87 text ads to the "Text Ads" group, and your image ads to your "Image Ads"
88 groups. (This is not required, it is perfectly valid to include both image 88 groups. (This is not required, it is perfectly valid to include both image
89 ads and text ads in the same group.) When displaying ads, you typically tell 89 ads and text ads in the same group.) When displaying ads, you typically tell
90 the ad module to display ads from a certain group and then the ad module 90 the ad module to display ads from a certain group and then the ad module
91 randomly selects an active ad from the specified group. Each ad can be a 91 randomly selects an active ad from the specified group. Each ad can be a
92 member of any number of groups. 92 member of any number of groups.
93 93
94 Ad status: 94 Ad status:
95 ---------- 95 ----------
96 There are several states that an ad can exist in. An ad in the Pending state 96 There are several states that an ad can exist in. An ad in the Pending state
97 is one that has recently been uploaded and is waiting to be approved by a 97 is one that has recently been uploaded and is waiting to be approved by a
98 privileged user. An ad in the Approved state is one that has been approved 98 privileged user. An ad in the Approved state is one that has been approved
99 by a privileged user but is not actively being displayed, the ad could be 99 by a privileged user but is not actively being displayed, the ad could be
100 waiting on an autoactivation event. An ad in the Active state is being 100 waiting on an autoactivation event. An ad in the Active state is being
101 actively displayed. An ad in the Offline state is approved but is currently 101 actively displayed. An ad in the Offline state is approved but is currently
102 not being displayed. An ad in the Unpublished state means that the ad node 102 not being displayed. An ad in the Unpublished state means that the ad node
103 was unpublished so the ad is not any longer being displayed. An ad in the 103 was unpublished so the ad is not any longer being displayed. An ad in the
104 Expired state is no longer being displayed. An ad in the Denied state means 104 Expired state is no longer being displayed. An ad in the Denied state means
105 it was not approved by the site administrator. 105 it was not approved by the site administrator.
106 106
107 Scheduling: 107 Scheduling:
108 ----------- 108 -----------
109 If you put an ad into the Approved state and then enter a date and time in the 109 If you put an ad into the Approved state and then enter a date and time in the
116 If you enter a number into the Maximum Impressions field, the ad will be 116 If you enter a number into the Maximum Impressions field, the ad will be
117 automatically expired once it has been displayed this number of times. 117 automatically expired once it has been displayed this number of times.
118 118
119 If you enter a number into the Maximum Clicks field, the ad will be 119 If you enter a number into the Maximum Clicks field, the ad will be
120 automatically expired once it has been clicked this number of times. 120 automatically expired once it has been clicked this number of times.
121
122 121
123 --------------- 122 ---------------
124 Displaying ads: 123 Displaying ads:
125 --------------- 124 ---------------
126 There are many ways to display ads with the ad module. The simplest way 125 There are many ways to display ads with the ad module. The simplest way
127 is to enable one of the automatically generated ad blocks. It is also possible 126 is to enable one of the automatically generated ad blocks. It is also possible
128 to use the ad_embed module to automatically embed ads within your site content. 127 to use the ad_embed module to automatically embed ads within your site content.
129 And you can even display ads from within the PHP of your theme or another 128 And you can even display ads from within the PHP of your theme or another
130 module. 129 module.
131 130
132 ---------- 131 ----------
133 Ad blocks: 132 Ad blocks:
134 ---------- 133 ----------
135 The ad module automatically generates on ad block for every ad group that you 134 The ad module automatically generates on ad block for every ad group that you
136 create. For example, if you visit "Administer >> Site building >> Blocks" 135 create. For example, if you visit "Administer >> Site building >> Blocks"
137 you will find a block named "ad group: default". If you enable this block, 136 you will find a block named "ad group: default". If you enable this block,
138 it will display a random ad from all active ads in the default group. 137 it will display a random ad from all active ads in the default group.
139 138
140 You can optionally configure the block to display more than one ad at a time 139 You can optionally configure the block to display more than one ad at a time
141 by clicking the 'configure' link on the block administration page. 140 by clicking the 'configure' link on the block administration page.
142 141
143 ------------- 142 -------------
144 Embedded ads: 143 Embedded ads:
145 ------------- 144 -------------
146 If you enabled the ad_embed module, it is possible to embed ads into your 145 If you enabled the ad_embed module, it is possible to embed ads into your
147 site content. To configure the ad_embed module go to "Administer >> Content 146 site content. To configure the ad_embed module go to "Administer >> Content
148 Management >> Ads >> Settings >> Embedded ads". 147 Management >> Ads >> Settings >> Embedded ads".
149 148
150 If you wish to manually embed ads in your content, check the box next to 149 If you wish to manually embed ads in your content, check the box next to
151 "Replace ad bracket tags" or "Replace ad comment tags". This will cause the 150 "Replace ad bracket tags" or "Replace ad comment tags". This will cause the
152 ad_embed module to replace embedded [[add]] or <!--ad--> tags respectively. 151 ad_embed module to replace embedded [[add]] or <!--ad--> tags respectively.
153 Instructions on how to specify specific ad groups or even specific ads and 152 Instructions on how to specify specific ad groups or even specific ads and
154 how many ads to display at a time can be found by visiting "Administer >> 153 how many ads to display at a time can be found by visiting "Administer >>
155 Help >> Embed". 154 Help >> Embed".
156 155
157 If you wish to automatically embed ads in your content, configure this on a 156 If you wish to automatically embed ads in your content, configure this on a
158 per-content-type basis in the lower configuration section. 157 per-content-type basis in the lower configuration section.
159 embeded ads". 158 embeded ads".
162 Displaying ads from PHP: 161 Displaying ads from PHP:
163 ------------------------ 162 ------------------------
164 To display an ad from within PHP code, make a call to the ad() function. 163 To display an ad from within PHP code, make a call to the ad() function.
165 You can optionally specify an ad group, the number of ads to display, and 164 You can optionally specify an ad group, the number of ads to display, and
166 several other options. For example, to display one random ad from all ads 165 several other options. For example, to display one random ad from all ads
167 that have not been assigned to any group you don't have to pass in any 166 that have not been assigned to any group you don't have to pass in any
168 parameters: 167 parameters:
169 <?php print ad(); ?> 168 <?php print ad(); ?>
170 169
171 To display two ads from all ads that have not been assigned to any group 170 To display two ads from all ads that have not been assigned to any group
172 you would execute the following code: 171 you would execute the following code:
175 (The first parameter specifies the ad group to display ads from. By 174 (The first parameter specifies the ad group to display ads from. By
176 specifying 0, we are telling the ad module to display ads that are not 175 specifying 0, we are telling the ad module to display ads that are not
177 assigned to any group. The second parameter specifies the number of ads 176 assigned to any group. The second parameter specifies the number of ads
178 to display at one time.) 177 to display at one time.)
179 178
180 To randomly display an ad from a specific group of nids, for example with 179 To randomly display an ad from a specific group of nids, for example with
181 the node ID 69 or 76, you would pass in the following parameters: 180 the node ID 69 or 76, you would pass in the following parameters:
182 <?php print ad(NULL, 1, array('nids' => '69,76')); ?> 181 <?php print ad(NULL, 1, array('nids' => '69,76')); ?>
183 182
184 (When specifying specific nids, any specified ad group is ignored, so we 183 (When specifying specific nids, any specified ad group is ignored, so we
185 leave the first parameter as NULL. The second parameter causes only one 184 leave the first parameter as NULL. The second parameter causes only one
227 } 226 }
228 227
229 .advertisement:before { 228 .advertisement:before {
230 content: "Advertisement:"; 229 content: "Advertisement:";
231 } 230 }
232 231
233 CSS Example 2: 232 CSS Example 2:
234 -------------- 233 --------------
235 Here is more sample code that could be added to your theme's custom 234 Here is more sample code that could be added to your theme's custom
236 style.css. It will cause multiple image ads to be displayed horizontally 235 style.css. It will cause multiple image ads to be displayed horizontally
237 one beside the other (space permitting), rather than vertically one 236 one beside the other (space permitting), rather than vertically one
238 below the other. The ads are aligned to the left side of the screen, 237 below the other. The ads are aligned to the left side of the screen,
239 if you'd prefer them to be aligned to the right side of the screen change 238 if you'd prefer them to be aligned to the right side of the screen change
240 the word "left" to "right" in the snippet: 239 the word "left" to "right" in the snippet:
241 240
263 This page begins by displaying the path to serve.php. If you see an error 262 This page begins by displaying the path to serve.php. If you see an error
264 here, then the ad module is not properly installed. Review the directions 263 here, then the ad module is not properly installed. Review the directions
265 in INSTALL.txt to properly install the ad module. 264 in INSTALL.txt to properly install the ad module.
266 265
267 In the General section you can specify what happens when an advertisement is 266 In the General section you can specify what happens when an advertisement is
268 clicked. For example, you can choose to have the resulting Destination URL 267 clicked. For example, you can choose to have the resulting Destination URL
269 opened in the same browser window, or in a new browser window. You can also 268 opened in the same browser window, or in a new browser window. You can also
270 enable the "nofollow" check box causing ads served by the ad module to 269 enable the "nofollow" check box causing ads served by the ad module to
271 include rel="nofollow" in automatically generated links. You can select 270 include rel="nofollow" in automatically generated links. You can select
272 to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML. 271 to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML.
273 Finally, you can disable URL validation, and enable advertisement filtering. 272 Finally, you can disable URL validation, and enable advertisement filtering.
274 273
275 Checking 'Filter ads' allows you to apply Drupal's standard input filters 274 Checking 'Filter ads' allows you to apply Drupal's standard input filters
293 text ads at "Administer >> Content management >> Ads >> Settings >> Text ads". 292 text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
294 293
295 ---------- 294 ----------
296 Image ads: 295 Image ads:
297 ---------- 296 ----------
298 The ad_image module allows you to specify some image constraints on a 297 The ad_image module allows you to specify some image constraints on a
299 per-group basis at "Administer >> Content management >> Ads >> Settings >> 298 per-group basis at "Administer >> Content management >> Ads >> Settings >>
300 Image ads". 299 Image ads".
301 300
302 ------------- 301 -------------
303 Embedded ads: 302 Embedded ads:
304 ------------- 303 -------------
305 Manually and automatically embedded ads can be configured at "Administer >> 304 Manually and automatically embedded ads can be configured at "Administer >>
306 Content management >> Ads >> Settings >> Embedded ads". 305 Content management >> Ads >> Settings >> Embedded ads".
307 306
308 307
309 ----------- 308 -----------
310 Statistics: 309 Statistics:
311 ----------- 310 -----------
312 The ad module tracks how often each ad is viewed and clicked. The statistics 311 The ad module tracks how often each ad is viewed and clicked. The statistics
313 are tracked to an hourly granularity. 312 are tracked to an hourly granularity.
314 313
315 When an advertisement is first enabled, the statistics for 'This hour', 'Today', 314 When an advertisement is first enabled, the statistics for 'This hour', 'Today',
316 'Last seven days', 'This month', 'This year' and 'All time' will all be the 315 'Last seven days', 'This month', 'This year' and 'All time' will all be the
317 same. When available, statistics will also include 'Last hour', 'Yesterday', 316 same. When available, statistics will also include 'Last hour', 'Yesterday',
318 'Last month', and 'Last year'. 317 'Last month', and 'Last year'.