Mercurial > defr > drupal > ad

comparison documentation/README.txt @ 0:d8a3998dac8e ad

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ajout module ad
author pierre
date Fri, 20 Feb 2009 14:04:09 +0000
parents
children 948362c2a207
comparison
equal deleted inserted replaced
-1:000000000000 0:d8a3998dac8e
1 ---------
2 Overview:
3 ---------
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
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
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
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
12 integration with other Drupal modules.
13
14 Features:
15 * auto-generated ad blocks supporting a configurable number of ads
16 * automatically or manually embed ads into site content
17 * collection of comprehensive statistics allowing time-based reporting and
18 analysis
19 * tracking of when and where ads are clicked, by which user and which IP
20 * advertisements can have multiple owners
21 * granular per-advertisement/per-owner permissions system
22 * activation/expiration scheduling based on time, clicks or impressions
23 * an ad_image plug-in for image (aka banner) ads
24 * an ad_text plug-in for simple text ads
25 * an ad_html plug-in for raw html ads
26 * an externally maintained ad_geoip plug-in provides support for
27 geotargeting ads
28 * an ad_report plug-in for basic graphical reports
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
31 * an administrative statistics overview page
32 * support for any number of configurable ad groups, utilizing Drupal's
33 taxonomy (category) subsystem
34 * display ads based on node ids (nids) or taxonomy terms (categories)
35 * file-based caching for improved performance
36 * memcache-based caching for improved performance
37 * support for external caching methods
38 * MySQL and PostgreSQL support
39
40
41 ------
42 Usage:
43 ------
44 Installation and requirements information can be found within the INSTALL.txt
45 file included with this module.
46
47
48 -------------
49 Creating ads:
50 -------------
51 Once the ad module is properly installed an enabled, you can create
52 advertisements by visiting 'create content' on your website and choosing
53 'advertisement' as the content type. If you have enabled multiple ad type
54 modules, you can select one of them from the resulting menu, such as 'image
55 advertiesment' or 'text advertisement'.
56
57 Text ads:
58 ---------
59 Text ads are very simple, requiring that you fill out only three fields of
60 information. First, you need to specify the Destination URL where you want
61 people to be redirected when they click on your text ad. Second, you enter
62 the a header for your ad. The header will be linked to the Destination URL.
63 Finally, you need to specify the body of your ad.
64
65 Image ads:
66 ----------
67 Image ads or only slightly more complicated than text ads. They depend on
68 the drupal core Upload module for managing the actual images. As with text
69 ads, you first need to specify the Destination URL where you want people to
70 be redirected when they click on your image ad. Second, you can optoinally
71 enter some Mouseover text. If you enter text in the mouseover field this
72 text will be displayed when people hover their mouse pointer over the
73 advertisement. Finally, you need to scroll down to the File attachements
74 section of the page and click the Browser button to select your image, then
75 click Attach to upload the image.
76
77 HTML ads:
78 ---------
79 HTML ads allow you to easily define your own custom ad type by simply pasting
80 in a block of HTML code. At this time, however, the ad module is unable to
81 track when html ads are clicked.
82
83 Ad groups:
84 ----------
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
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
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
91 randomly selects an active ad from the specified group. Each ad can be a
92 member of any number of groups.
93
94 Ad status:
95 ----------
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
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
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
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
104 Expired state is no longer being displayed. An ad in the Denied state means
105 it was not approved by the site administrator.
106
107 Scheduling:
108 -----------
109 If you put an ad into the Approved state and then enter a date and time in the
110 Automatically Activate Ad field, the ad will be automatically activated
111 on the date and time specified. This feature requires that cron be functional
112 on your website. If you enter a date and time in the Automatically Expire Ad
113 field, the ad will be automatically expired on the date and time specified.
114 Again, this feature requires that cron be functional on your website.
115
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.
118
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.
121
122
123 ---------------
124 Displaying ads:
125 ---------------
126 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
128 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
130 module.
131
132 ----------
133 Ad blocks:
134 ----------
135 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"
137 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.
139
140 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.
142
143 -------------
144 Embedded ads:
145 -------------
146 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
148 Management >> Ads >> Settings >> Embedded ads".
149
150 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
152 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
154 how many ads to display at a time can be found by visiting "Administer >>
155 Help >> Embed".
156
157 If you wish to automatically embed ads in your content, configure this on a
158 per-content-type basis in the lower configuration section.
159 embeded ads".
160
161 ------------------------
162 Displaying ads from PHP:
163 ------------------------
164 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
166 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
168 parameters:
169 <?php print ad(); ?>
170
171 To display two ads from all ads that have not been assigned to any group
172 you would execute the following code:
173 <?php print ad(0, 2); ?>
174
175 (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
177 assigned to any group. The second parameter specifies the number of ads
178 to display at one time.)
179
180 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:
182 <?php print ad(NULL, 1, array('nids' => '69,76')); ?>
183
184 (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
186 ad to be displayed at a time. And the third parameter is an array that
187 tells the ad module to randomly display either ad 69 or ad 76.)
188
189 To display and ad randomly selected from multiple groups you can simply
190 specify multiple groups separated by commas. For example, to display 3
191 ads from groups 24, 56 and 98 you would pass in the following parameters:
192 <?php print ad('24,56,98', 2); ?>
193
194 You can also specify how to display a given ad. Current display methods are
195 'javascript' and 'raw'. When using the 'javascript' method, ads will
196 randomly change even when the Drupal pagecache is enabled. When using the
197 'raw' method, ads will only change when the Drupal pagecache is flushed.
198 To force one ad with a tid of 76 to display using JavaScript you would pass
199 in the following parameters:
200 <?php print ad(76, 1, array('method' => 'javascript'));
201
202 To force two ads with a tid of 101 or 102 to display using the Raw method
203 you would pass in the following parameters:
204 <?php print ad('101,102', 76, array('method' => 'raw'));
205
206 ------------
207 Theming ads:
208 ------------
209 All ads are wrapped in the following tags:
210 <div class="advertisement" id="group-#"></div>
211
212 All ads are in the same "advertisement" class. Each ad group gets a unique
213 id. This makes it possible to create generic advertisement formatting as
214 well as specific advertisement formatting.
215
216 CSS Example 1:
217 --------------
218 This sample code can be added to your theme's custom style.css. It adds
219 padding to advertisements, wrapping them in a dashed border and giving
220 them a background color. It also adds the text "Advertisement:" above
221 the ad:
222
223 .advertisement {
224 padding: 5px;
225 border: dashed;
226 background-color: #ffd;
227 }
228
229 .advertisement:before {
230 content: "Advertisement:";
231 }
232
233 CSS Example 2:
234 --------------
235 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
237 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,
239 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:
241
242 .image-advertisement {
243 float: left;
244 padding: 3px;
245 }
246
247
248 -------------------
249 Ad module settings:
250 -------------------
251 The ad module and related modules provide a number of configuration options.
252
253 ----------------
254 Global settings:
255 ----------------
256 The ad module allows you to specify some global settings at "Administer >>
257 Content management >> Ads >> Settings >> Global settings".
258
259 Even if you do not plan to make any changes, you should visit this page at
260 least one time as the ad module will perform a series of sanity tests when
261 you visit this page, alerting you to any installation problems.
262
263 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
265 in INSTALL.txt to properly install the ad module.
266
267 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
269 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
271 include rel="nofollow" in automatically generated links. You can select
272 to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML.
273 Finally, you can disable URL validation, and enable advertisement filtering.
274
275 Checking 'Filter ads' allows you to apply Drupal's standard input filters
276 to your advertisements. If you enable this option, be sure to apply a
277 compatible filter that doesn't strip away the <div> and other tags used by
278 the various advertisement types.
279
280 The next section allows you to configure IFrames, if you are using them to
281 display advertisements.
282
283 For better performance, you can also enable a cache. At this time there is
284 only a file cache available. When the file cache is enabled, ads are quickly
285 displayed from a cache file without bootstrapping Drupal. On very busy
286 websites you may need to increase the number of cache files to prevent
287 cache file contention.
288
289 ---------
290 Text ads:
291 ---------
292 The ad_text module allows you to specify some minimum and maximum lengths for
293 text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
294
295 ----------
296 Image ads:
297 ----------
298 The ad_image module allows you to specify some image constraints on a
299 per-group basis at "Administer >> Content management >> Ads >> Settings >>
300 Image ads".
301
302 -------------
303 Embedded ads:
304 -------------
305 Manually and automatically embedded ads can be configured at "Administer >>
306 Content management >> Ads >> Settings >> Embedded ads".
307
308
309 -----------
310 Statistics:
311 -----------
312 The ad module tracks how often each ad is viewed and clicked. The statistics
313 are tracked to an hourly granularity.
314
315 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
317 same. When available, statistics will also include 'Last hour', 'Yesterday',
318 'Last month', and 'Last year'.