Mercurial > defr > drupal > ad
comparison documentation/README.txt @ 0:d8a3998dac8e ad
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'. |